Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

76.3 KB
Raw Blame
import 'identity.dart' show superTabPersonName;
import 'live_card_model.dart';
import 'profile_model.dart';
import 'pulse_model.dart';

export 'profile_model.dart';

/// Backend records are independent of the desktop's visible panes and tab layout.
Map<String, dynamic> superTabMap(Object? value) => value is Map
    ? Map<String, dynamic>.from(value)
    : throw const FormatException('Invalid Swarm response.');

String _text(Map<String, dynamic> value, String key) => value[key] is String
    ? value[key] as String
    : throw FormatException('Missing Swarm $key.');

List<T> _list<T>(Object? value, T Function(Map<String, dynamic>) read) =>
    value is List
    ? List.unmodifiable(value.map((row) => read(superTabMap(row))))
    : throw const FormatException('Invalid Swarm list.');

/// [rows] by id; the first row wins where two share one, as a scan would.
Map<String, T> _byId<T>(List<T> rows, String Function(T row) idOf) => {
  for (final row in rows.reversed) idOf(row): row,
};

/// Work that waits on a person: the agent needs a decision (`needs_human`) or
/// is stuck (`blocked`). Both stay active work until the agent moves on.
bool superTabWorkWaits(Object? status) =>
    status == 'needs_human' || status == 'blocked';

/// How a work status reads in the app. `blocked` is what the agent calls it;
/// people read Stuck. Statuses this build does not know read as sent.
String superTabWorkStatusLabel(String status) =>
    status == 'blocked' ? 'stuck' : status.replaceAll('_', ' ');

/// What a project calls its coordinator when the backend names none (one from before project instructions), and
/// what every new project starts with.
const kDefaultCoordinatorName = 'Product Manager';

/// A role's compact badge: the name when it is 12 characters or fewer, else its first 11 and "…".
String superTabRoleBadge(String roleName) {
  final characters = roleName.runes.toList();
  return characters.length <= 12
      ? roleName
      : '${String.fromCharCodes(characters.take(11))}…';
}

class SuperTabPerson {
  SuperTabPerson.fromJson(Map<String, dynamic> row)
    : id = _text(row, 'id'),
      email = _text(row, 'email'),
      role = _text(row, 'role'),
      generation = row['generation'] as String?,
      joinedVia = row['joinedVia'] as String?,
      avatar = SuperTabAvatarPicture.fromJson(row['avatar']),
      status = SuperTabPersonStatus.fromJson(row['status']),
      timeZone = switch (row['timeZone']) {
        final String zone when zone.trim().isNotEmpty => zone,
        _ => null,
      },
      chosenUsername = row['username'] as String?,
      name = switch (row['name']) {
        final String name when name.trim().isNotEmpty => name,
        _ => null,
      },
      username =
          row['username'] as String? ??
          superTabDefaultUsername(_text(row, 'email'));
  SuperTabPerson._named(SuperTabPerson person, this.username)
    : id = person.id,
      email = person.email,
      role = person.role,
      generation = person.generation,
      joinedVia = person.joinedVia,
      avatar = person.avatar,
      status = person.status,
      timeZone = person.timeZone,
      chosenUsername = person.chosenUsername,
      name = person.name;
  final String id, email, role;
  final SuperTabAvatarPicture? avatar;
  final SuperTabPersonStatus? status;

  /// Their time zone's IANA name, as their own app told the Swarm (Desktop's
  /// local_time_zone.dart); null until it has. The phone shows no card yet.
  final String? timeZone;

  /// How the Swarm tags them (`@username`), as the server sends it; from an
  /// older server, their default ([superTabUsernames]). Desktop's rule.
  final String username;

  /// The name the server sent; null from a server without usernames.
  final String? chosenUsername;

  /// The name they set for the Swarm to show (`member.name`, "Minh Nguyen");
  /// null until they set one, and from an older server.
  final String? name;

  /// How the Swarm shows them: their [name], else their [username]. A tag
  /// still types and matches the [username].
  String get shownName => name ?? username;

  /// Their status while it lasts.
  SuperTabPersonStatus? statusAt(DateTime now) =>
      status?.shownAt(now) == true ? status : null;

  /// This membership: a new one each time the person joins the Swarm. Null
  /// from a backend that does not send it.
  final String? generation;

  /// How they joined: `domain` when they were added automatically for their
  /// email's domain. Null otherwise and from an older server. Read as the
  /// desktop's model reads it; the phone does not show it yet.
  final String? joinedVia;
  bool get canWrite => role == 'owner' || role == 'collaborator';
}

/// The name an email's prefix makes: lowercased, only the characters a
/// username takes, never too short. Unnumbered; [superTabUsernames] numbers
/// it. Desktop's `superTabDefaultUsername`, byte for byte.
String superTabDefaultUsername(String email) {
  var prefix = email
      .split('@')
      .first
      .toLowerCase()
      .replaceAll(RegExp(r'[^a-z0-9._-]'), '')
      .replaceFirst(RegExp(r'^[._-]+'), '');
  if (prefix.length > 30) prefix = prefix.substring(0, 30);
  if (prefix.isEmpty) return 'user';
  return prefix.length < 2 ? '${prefix}1' : prefix;
}

/// [people], each with their username: the one the server sent, else (an
/// older server, which sends none) their email prefix numbered (`ken2`) after
/// the people before them, as Desktop names them.
List<SuperTabPerson> superTabUsernames(List<SuperTabPerson> people) {
  final taken = {for (final p in people) ?p.chosenUsername};
  return List.unmodifiable([
    for (final person in people)
      if (person.chosenUsername != null)
        person
      else
        SuperTabPerson._named(person, () {
          final root = superTabDefaultUsername(person.email);
          var name = root;
          for (var n = 2; taken.contains(name); n++) {
            name = '$root$n';
          }
          taken.add(name);
          return name;
        }()),
  ]);
}

class SuperTabAgent {
  SuperTabAgent.fromJson(Map<String, dynamic> row)
    : id = _text(row, 'id'),
      hasProjectId = row['projectId'] != null,
      // A person's one Buddy reads every project they read: it belongs to none,
      // as on the desktop (spec 2026-10-31-one-buddy-per-swarm).
      projectId =
          row['projectId'] as String? ??
          (row['buddyScope'] == 'swarm' ? '' : 'lead'),
      buddyScope = row['buddyScope'] as String?,
      buddyNarrow = row['buddyNarrow'] == true,
      name = _text(row, 'name'),
      displayName = row['displayName'] as String?,
      machineId = _text(row, 'machineId'),
      harnessId = _text(row, 'harnessId'),
      contributorId = _text(row, 'contributorId'),
      machineOwnerId =
          row['machineOwnerId'] as String? ?? _text(row, 'contributorId'),
      role = row['role'] as String?,
      kind = row['kind'] as String?,
      chatId = row['chatId'] as String?,
      myAgent = row['myAgent'] as bool?,
      roleId = row['roleId'] as String?,
      roleName = row['roleName'] as String?,
      buddyOf = switch (row['buddyOf']) {
        {'personId': final String person} => person,
        _ => null,
      },
      // Read as the desktop does.
      buddySession = SuperTabBuddySessionOf.fromJson(row['buddySession']),
      limitedUntil = DateTime.tryParse(row['limitedUntil'] as String? ?? ''),
      alerting = List.unmodifiable(
        (row['alerting'] as List?)?.whereType<String>() ?? const <String>[],
      ),
      switchRequest = row['switchRequest'] is Map
          ? Map.unmodifiable(superTabMap(row['switchRequest']))
          : null,
      gridModel = row['gridModel'] as String?,
      modelRequest = switch (row['modelRequest']) {
        {'id': final String id} && final Map request => (
          id: id,
          gridModel: request['gridModel'] as String?,
          name: request['name'] as String?,
        ),
        _ => null,
      },
      profileId = row['profileId'] as String?,
      avatar = SuperTabAvatarPicture.fromJson(row['avatar']),
      downSince = DateTime.tryParse(row['downSince'] as String? ?? ''),
      workDecision = switch (row['workDecision']) {
        final String decision when _workDecisions.contains(decision) =>
          decision,
        _ => null,
      },
      crewRole = switch (row['crew']) {
        {'role': final String role} when role.isNotEmpty => role,
        _ => null,
      },
      crewLane = switch (row['crew']) {
        {'lane': final String lane} => lane,
        _ => null,
      },
      crewAsleep = row['asleep'] != null,
      crewAsleepSince = switch (row['asleep']) {
        {'since': final num since} => DateTime.fromMillisecondsSinceEpoch(
          since.toInt(),
        ),
        _ => null,
      },
      crewMoving = row['movedTo'] != null,
      confidential = row['confidential'] == true,
      configuration = Map.unmodifiable(superTabMap(row['configuration']));

  /// `swarm` for a person's one Buddy for the whole Swarm, as the desktop's model reads it; null otherwise.
  final String? buddyScope;

  /// Whether that Buddy reads only a narrowed set of projects (desktop model); not drawn on the phone yet.
  final bool buddyNarrow;

  final String id, projectId, name, machineId, harnessId, contributorId;

  /// What it is and where its person talks to it (Swarm v3, backend #4116), read as the desktop's model reads them.
  final String? kind, chatId;

  /// Whether it is in the reader's My agents (backend agentKind.ts inMyAgents, task #4192), read as the desktop's model
  /// reads it. Null from an older backend.
  final bool? myAgent;

  /// Set by its contributor or its project's Lead; null draws its pattern.
  final SuperTabAvatarPicture? avatar;

  /// Until when routing skips it: its machine saw a usage limit on its screen
  /// (spec/2026-10-23-lead-sees-agent-terminal.md). Null when none was seen.
  final DateTime? limitedUntil;

  /// What its machine is alerting about now (backend terminal.ts): `prompt`
  /// while it waits at a prompt in its terminal, gone once that is answered.
  final List<String> alerting;

  /// A Product Manager's switch to another engine or account that is asked for
  /// and not yet done (backend `switchRequest`), as the desktop's model reads
  /// it; null otherwise. While set, the PM reads "Switching…" and Switch PM…
  /// is not offered (swarm_switch_pm.dart).
  final Map<String, dynamic>? switchRequest;

  /// The model on the Swarm's grid it runs on; null on its own subscription
  /// (backend Agent.gridModel), as the desktop's model reads it. The phone
  /// draws no model picker yet (task #2354 is Desktop and web first).
  final String? gridModel;

  /// A person's switch of their Buddy's model that is asked for and not yet
  /// done (backend buddyModel.ts `modelRequest`); null otherwise. A null
  /// [gridModel] there is the way back to their subscription.
  final ({String id, String? gridModel, String? name})? modelRequest;

  /// The account on its machine it runs in; `default` when none is chosen.
  /// Null until the backend reports it: the engine's default account. As the
  /// desktop's model reads it; Switch PM marks it Current.
  final String? profileId;

  /// Since when its machine has reported its session gone, or its host confirmed a stop (backend machines.ts). Null
  /// while it runs.
  final DateTime? downSince;

  /// What its project's Lead decided once its work was over (backend
  /// model.ts `workDecision`): `awaiting` a decision, kept (`keep`) for more
  /// work, or `stop`ped. Null while it has not finished any.
  final String? workDecision;

  static const _workDecisions = {'awaiting', 'keep', 'stop'};

  /// Its role in its project's crew, the agents the Swarm keeps alive (backend crew.ts, task #3397), as the desktop's model
  /// reads it; null when not crew.
  final String? crewRole;

  /// The lane a crew member works in (backend, cli, desktop, mobile or docs); null for none.
  final String? crewLane;

  /// A crew member put to sleep on purpose (task #3398): its session is closed and nothing reopens it.
  final bool crewAsleep;

  /// Since when it sleeps (backend crewKeep.ts `asleep.since`), as the desktop's model reads it (task #3412). Null when
  /// awake, or when the server sent no time.
  final DateTime? crewAsleepSince;

  /// A crew member on its way to another machine (backend `movedTo`, task #3398), as the desktop's model reads it.
  final bool crewMoving;

  /// The account whose computer runs it; a contributor may run agents on a computer another account shared with them.
  final String machineOwnerId;

  /// Its session read private chats: a Product Manager, now or before, or an agent in a private chat. Only the person
  /// whose computer runs it may watch it, but every member watches the current Product Manager, view only
  /// (backend projects.ts `watchClosed`, terminal_unavailable.dart `superTabTerminalPrivate`).
  final bool confidential;
  // Keep the legacy default for callers while allowing group-based roster ownership.
  final bool hasProjectId;
  final String? displayName;
  // Absent until the backend sends one; an agent without a role is a Builder.
  final String? role;
  final String? roleId;

  /// The role the project's document gives it; null from a backend before project instructions.
  final String? roleName;

  /// A person's private agent for one project (spec: Buddies, 10-28); it
  /// never takes work. The backend gives it no role, only its person.
  bool get isBuddy => buddyOf != null;

  /// The person whose Buddy it is; null for any other agent.
  final String? buddyOf;

  /// Set on a Buddy's thread session (desktop model.dart); null otherwise.
  final SuperTabBuddySessionOf? buddySession;
  final Map<String, dynamic> configuration;
  String get engine => configuration['engine'] as String? ?? '';
}

/// A thread session's thread and starting sequence (desktop model.dart).
class SuperTabBuddySessionOf {
  const SuperTabBuddySessionOf(this.thread, this.from, [this.projectId]);
  final String thread;
  final int from;

  /// The project a session of a person's one Buddy chat works in; null for a
  /// plain session and every older project chat's.
  final String? projectId;

  static SuperTabBuddySessionOf? fromJson(Object? value) {
    if (value is! Map) return null;
    final json = superTabMap(value);
    final thread = json['thread'];
    if (thread is! String || thread.isEmpty) return null;
    final from = json['from'];
    final project = json['projectId'];
    return SuperTabBuddySessionOf(
      thread,
      from is num ? from.toInt() : 0,
      project is String && project.isNotEmpty ? project : null,
    );
  }
}

/// One live or starting thread session of a Buddy chat (desktop model.dart).
class SuperTabBuddySession {
  SuperTabBuddySession.fromJson(Map<String, dynamic> json)
    : thread = json['thread'] is String ? json['thread'] as String : '',
      startId = json['startId'] is String ? json['startId'] as String : '',
      agentId = json['agentId'] is String ? json['agentId'] as String : null,
      at = json['at'] is num ? (json['at'] as num).toInt() : 0;
  final String thread, startId;
  final String? agentId;
  final int at;
}

class SuperTabTask {
  SuperTabTask.fromJson(Map<String, dynamic> row)
    : goal = _text(row, 'goal'),
      changes = _text(row, 'changes'),
      constraints = _text(row, 'constraints'),
      owns = List.unmodifiable((row['owns'] as List).cast<String>());

  final String goal, changes, constraints;
  final List<String> owns;
}

class SuperTabConversation {
  SuperTabConversation.fromJson(Map<String, dynamic> row)
    : id = _text(row, 'id'),
      // A group from before projects belongs to the first; a person's one
      // Buddy chat for the Swarm belongs to none (spec
      // 2026-10-31-one-buddy-per-swarm).
      projectId =
          row['projectId'] as String? ??
          (row['kind'] == 'swarm-buddy' ? '' : 'lead'),
      kind = row['kind'] as String?,
      buddyOwnerId = row['buddyOwnerId'] as String?,
      buddyName = row['buddyName'] as String?,
      buddyDefault = row['buddyDefault'] == true,
      paused = SuperTabPause.read(row['paused']),
      proposal = SuperTabProposalCard.read(row['proposal']),
      buddySessions = List.unmodifiable(
        (row['buddySessions'] is List ? row['buddySessions'] as List : const [])
            .whereType<Map>()
            .map((json) => SuperTabBuddySession.fromJson(superTabMap(json)))
            .where((session) => session.thread.isNotEmpty),
      ),
      number = (row['number'] as num?)?.toInt(),
      title = _text(row, 'title'),
      leadId = row['leadId'] as String?,
      agentIds = List.unmodifiable((row['agentIds'] as List).cast<String>()),
      archived = row['archived'] == true,
      dormant = row['dormant'] == true,
      // A Buddy chat names no audience: its person alone reads it.
      audience =
          (row['kind'] == 'buddy' || row['kind'] == 'swarm-buddy') &&
              row['buddyOwnerId'] is String
          ? List.unmodifiable([row['buddyOwnerId'] as String])
          : row['audience'] is Map
          ? List.unmodifiable([
              for (final person
                  in superTabMap(row['audience'])['people'] as List? ??
                      const [])
                if (person is Map && person['id'] is String) person['id'],
            ])
          : null,
      checks = _list(
        row['checks'] ?? const [],
        (check) => Map<String, dynamic>.unmodifiable(check),
      ),
      pullRequestUrls = List.unmodifiable(
        (row['pullRequestUrls'] as List?)?.whereType<String>() ??
            const <String>[],
      ),
      cards = SuperTabCards.fromJson(row['cards']),
      reviewOf = row['reviewOf'] as String?,
      step = row['step'] as String?,
      brief = _text(row, 'brief'),
      task = row['task'] is Map
          ? SuperTabTask.fromJson(superTabMap(row['task']))
          : null,
      lastMessageSequence = (row['lastMessageSequence'] as num?)?.toInt() ?? 0,
      requesterId = row['requesterId'] as String?,
      releasing = row['releasing'] is List
          ? List.unmodifiable((row['releasing'] as List).whereType<String>())
          : null,
      pullRequestChecks = row['pullRequestChecks'] is Map
          ? Map.unmodifiable({
              for (final MapEntry(:key, :value)
                  in (row['pullRequestChecks'] as Map).entries)
                if (key is String && value is String) key: value,
            })
          : const {},
      releasedTags = row['released'] is Map && row['released']['tags'] is List
          ? List.unmodifiable(
              (row['released']['tags'] as List).whereType<String>(),
            )
          : const [],
      shippedAt = row['shippedAt'] is num
          ? DateTime.fromMillisecondsSinceEpoch(
              (row['shippedAt'] as num).toInt(),
            )
          : null,
      queueRank = (row['queueRank'] as num?)?.toDouble(),
      priority = row['priority'] as String?,
      handOutLane = row['handOutLane'] is String
          ? row['handOutLane'] as String
          : null,
      notBefore = DateTime.tryParse(row['notBefore'] as String? ?? ''),
      lastMainSequence = (row['lastMainSequence'] as num?)?.toInt(),
      lastPersonSequence = (row['lastPersonSequence'] as num?)?.toInt() ?? 0,
      reactionSeq = (row['reactionSeq'] as num?)?.toInt() ?? 0,
      changedAt = row['changedAt'] is num
          ? DateTime.fromMillisecondsSinceEpoch(
              (row['changedAt'] as num).toInt(),
              isUtc: true,
            )
          : null,
      assignment = row['assignment'] == null
          ? null
          : Map.unmodifiable(superTabMap(row['assignment'])),
      liveness = row['liveness'] is Map
          ? Map.unmodifiable(superTabMap(row['liveness']))
          : null,
      leadAction = row['leadAction'] is Map
          ? Map.unmodifiable(superTabMap(row['leadAction']))
          : null;
  final String id, projectId, title, brief;

  /// What the backend calls it apart from a workgroup: `buddy` for a person's
  /// chat with their Buddy. A `leads` one, the removed Product Managers'
  /// conversation, is in no read ([SuperTabSnapshot.fromJson]).
  final String? kind;
  bool get isBuddyChat => kind == 'buddy' || kind == 'swarm-buddy';

  /// A person's one Buddy chat for the whole Swarm (spec
  /// 2026-10-31-one-buddy-per-swarm): in no project, keyed by the empty id.
  bool get isSwarmBuddyChat => kind == 'swarm-buddy';

  /// The person a Buddy chat belongs to; only they read it.
  final String? buddyOwnerId;

  /// The name a Buddy chat's person chose for their Buddy, kept while no
  /// Buddy runs; null for the default (backend buddies.ts renameBuddy).
  final String? buddyName;

  /// Read as the desktop's model reads them (Board Phase 2, #3820); the phone draws them with #3821.
  final bool buddyDefault;
  final SuperTabPause? paused;
  final SuperTabProposalCard? proposal;

  /// A Buddy chat's live or starting thread sessions (desktop model.dart).
  final List<SuperTabBuddySession> buddySessions;

  /// The live or starting session answering [thread], if any.
  SuperTabBuddySession? sessionFor(String thread) =>
      buddySessions.where((s) => s.thread == thread).firstOrNull;
  final SuperTabTask? task;
  final int? number;

  /// The person who asked for this task; null on a conversation that is no
  /// task, and from a server that does not say.
  final String? requesterId;

  /// When it shipped (its first Done); null until it has, and from a server
  /// that does not say.
  final DateTime? shippedAt;

  /// The parts a merged task still waits on for a verified release; null
  /// when it is not on the server's release list (the desktop's model reads
  /// it for its board; the phone carries it as the desktop does).
  final List<String>? releasing;

  /// Each linked pull request's check state as the server's PR watch last read it, by URL: `green`, `red` or `running`
  /// (backend pullRequestEvents.ts checksStateOf, task #3827). Read as the desktop does; the phone draws no board yet.
  final Map<String, String> pullRequestChecks;

  /// The release tags that carried it to people, once they have (backend releases.ts `released`); empty before. Read as the
  /// desktop does; the phone draws no board yet.
  final List<String> releasedTags;

  /// Its place in its project's shared Next up and the day before which it
  /// may not start, as Desktop's Tasks view reads them (task #2569); read here
  /// for the phone's Tasks view to come.
  final double? queueRank;
  final DateTime? notBefore;

  /// A task's priority, `P0` to `P3`, as the server keeps it (backend
  /// taskPriority.ts, task #3117); null on a step, a chat and a task from
  /// before it. Read here for the phone's Tasks view to come.
  final String? priority;

  /// The lane the crew dispatch hands this task out in (backend read/views.ts
  /// `handOutLane`, task #3400; desktop model.dart). Null when no lane owns it,
  /// on a chat or a step, and from an older server.
  final String? handOutLane;
  String get label => number == null ? title : '#$number $title';
  final String? leadId;
  final List<String> agentIds;
  final bool archived;

  /// A private conversation's people, who read it with the project's Lead
  /// and nobody else; null for a conversation the project shares.
  final List<String>? audience;

  /// Out of the Swarm's active groups: archived, or finished and quiet for a
  /// day. Read on demand; a new message brings it back.
  final bool dormant;

  /// Listed with the project's closed groups, not its active ones.
  bool get closed => archived || dormant;
  final List<Map<String, dynamic>> checks;

  /// Persisted links may be absent on older backends; loaded messages still supply links.
  final List<String> pullRequestUrls;

  /// Its messages drawn as live cards (swarm_live_card.dart); none from an
  /// older backend.
  final SuperTabCards cards;

  /// A review group's reviewed group; null for any other conversation.
  final String? reviewOf;

  /// A step of the task [reviewOf] names, by the name its project's
  /// instructions give it (task steps design); null for a task, and for a
  /// linked task opened before steps.
  final String? step;
  final int lastMessageSequence;

  /// Its newest message in the main stream: a reply only in its thread
  /// leaves it. Null from a backend before threads, or before this
  /// conversation's first message since.
  final int? lastMainSequence;

  /// Its newest main-stream message from a person, not a system row (backend
  /// parts/commit.ts): what the desktop's sidebar bolds a row by (#2427). The
  /// phone reads it as the desktop does; its own unread rule is unchanged. 0
  /// before a person's first message since that backend.
  final int lastPersonSequence;

  /// The newest message that makes it unread, as the desktop's
  /// `SuperTabController.unread` counts it: a reply only in its thread does
  /// not, as it is not in the chat.
  int get mainSequence => lastMainSequence ?? lastMessageSequence;

  /// Moves whenever a reaction here is added or taken back (backend
  /// reactions.ts): the messages shown are read again for their counts.
  final int reactionSeq;

  /// When it last changed, a message included: its part's `changedAt`,
  /// which the phone's reader adds to what it read
  /// ([SuperTabParts.groupChangedAt]), as no state names it. Null where it
  /// is not known: a state read some other way, or a Home kept from before.
  final DateTime? changedAt;
  final Map<String, dynamic>? assignment;

  /// Whether its task waits on purpose or is stuck, as the server last found
  /// it (`state`, `why`, `since`, `personId`); absent while it is working,
  /// and from older backends. Read as the desktop's model reads it
  /// (desktop_parity_test); the phone shows none of it yet.
  final Map<String, dynamic>? liveness;

  /// The Product Manager's last action on its task (`kind`, `at`); read as
  /// [liveness] is.
  final Map<String, dynamic>? leadAction;
}

/// The zone a project's day is read in when its digest names none (backend
/// costs/reflection.ts `DEFAULT_TIME_ZONE`).
const superTabDefaultTimeZone = 'Asia/Ho_Chi_Minh';

class SuperTabProject {
  SuperTabProject.fromJson(Map<String, dynamic> row)
    : id = _text(row, 'id'),
      name = _text(row, 'name'),
      ownerId = _text(row, 'ownerId'),
      leadConversationId = _text(row, 'leadConversationId'),
      skillMode = row['skillMode'] == 'default' ? 'default' : 'orchestration',
      coordinatorName = row['coordinatorName'] as String?,
      instructionsRevision =
          (row['instructionsRevision'] as num?)?.toInt() ?? 0,
      notesRevision = (row['notesRevision'] as num?)?.toInt() ?? 0,
      githubRevision = (row['githubRevision'] as num?)?.toInt() ?? 0,
      isPrivate = row['visibility'] == 'private',
      memberIds = [
        for (final member in row['members'] as List? ?? const [])
          superTabMap(member)['id'] as String,
      ],
      _memberGenerations = {
        for (final member in row['members'] as List? ?? const [])
          superTabMap(member)['id'] as String:
              superTabMap(member)['generation'] as String?,
      },
      updateMinutes = (row['updateMinutes'] as num?)?.toInt() ?? 5,
      timeZone = switch (row['digest']) {
        {'timeZone': final String zone} when zone.isNotEmpty => zone,
        _ => superTabDefaultTimeZone,
      },
      status = SuperTabProjectStatus.read(row['status']),
      repository = row['repository'] is Map
          ? Map.unmodifiable(superTabMap(row['repository']))
          : null,
      repositoryCreation = row['repositoryCreation'] is Map
          ? Map.unmodifiable(superTabMap(row['repositoryCreation']))
          : null,
      leadWaiting = {
        for (final entry in row['leadWaiting'] as List? ?? const [])
          if (entry is Map && entry['id'] is String) entry['id'] as String,
      },
      boardMode = row['boardMode'] == true,
      canChatIds = List.unmodifiable(
        (row['canChat'] as List? ?? const []).whereType<String>(),
      ),
      deciderId = row['decider'] is String ? row['decider'] as String : null;
  final String id, name, ownerId, leadConversationId;

  /// The Board way of working (#3819), read as the desktop's model reads it; the phone draws it with #3821.
  final bool boardMode;
  final List<String> canChatIds;
  final String? deciderId;

  /// Whether [personId] may write in its chat: anyone who may write, while it is not on the Board.
  bool canChat(String personId, {bool swarmOwner = false}) =>
      !boardMode ||
      swarmOwner ||
      personId == ownerId ||
      canChatIds.contains(personId);

  /// Whether [personId] may set P0 and pause or resume any task: its owner, the Swarm's owner and its decider.
  bool canSteer(String personId, {bool swarmOwner = false}) =>
      swarmOwner || personId == ownerId || personId == deciderId;

  /// The zone its day is read in, read as the desktop's model reads it (its
  /// digest's, else [superTabDefaultTimeZone]); the phone shows no lanes yet.
  final String timeZone;

  /// The person's messages the server keeps for this project's Lead: a
  /// Personal Swarm's chat with none, whose Lead their computer starts
  /// (backend leadStart.ts). Empty from a server before it.
  final Set<String> leadWaiting;

  /// Read as the desktop's model reads it; the phone starts no agents.
  final String skillMode;

  /// What this project calls its coordinator; null from a backend before project instructions.
  final String? coordinatorName;
  final int instructionsRevision, notesRevision;

  /// Moves when its repository's GitHub access may have changed (someone
  /// allowed it, or the app was installed); 0 from a backend before it (task
  /// #2316). Read as the desktop's model reads it; the phone reads no GitHub
  /// access.
  final int githubRevision;

  /// Whether the backend keeps an instruction document for it.
  bool get hasInstructions => coordinatorName != null;
  final bool isPrivate;
  final List<String> memberIds;

  /// Each member's Swarm membership when they were added: who left the Swarm
  /// and joined again is not a member until added again.
  final Map<String, String?> _memberGenerations;

  /// Whether [person] is a member at their membership now, as the server
  /// checks (`canReadProject`).
  bool hasMember(SuperTabPerson person) =>
      _memberGenerations.containsKey(person.id) &&
      _memberGenerations[person.id] == person.generation;
  final int updateMinutes;

  /// The project's status card text, read as the desktop's model reads it
  /// (`SuperTabProjectStatusCard`); the phone shows it in the project menu's
  /// Status sheet.
  final SuperTabProjectStatus? status;
  final Map<String, dynamic>? repository;

  /// New project's New repository for it (task #3373): what was asked
  /// (`owner`, `name`, `private`, `by`, `at`) and how GitHub's sign-in came
  /// back (`state`: waiting, created, taken, refused, failed or cancelled,
  /// with `repositoryUrl`, `reachable` and `reason`). Null from a server
  /// before it, and for a project nobody asked one for.
  final Map<String, dynamic>? repositoryCreation;
}

/// A project's status card text, as the desktop's model reads it
/// (`../desktop/lib/super_tabs/model.dart`).
// Board Phase 2 (#3817, #3819), as the desktop's model.dart reads it.
DateTime? _epoch(Object? value) =>
    value is num ? DateTime.fromMillisecondsSinceEpoch(value.toInt()) : null;

String? _words(Object? value) =>
    value is String && value.trim().isNotEmpty ? value : null;

/// A Board card's proposal (#3817): what was proposed and by whom, the PM's decision, and its questions.
class SuperTabProposalCard {
  SuperTabProposalCard._(Map row)
    : text = _words(row['text']) ?? '',
      goal = _words(row['goal']),
      why = _words(row['why']),
      doneWhen = _words(row['doneWhen']),
      createdAt = _epoch(row['createdAt']),
      senderIds = List.unmodifiable([
        for (final sender in row['senders'] as List? ?? const [])
          if (sender is Map && sender['personId'] is String)
            sender['personId'] as String,
      ]),
      decision = SuperTabProposalDecision.read(row['decision']),
      questions = List.unmodifiable([
        for (final q in row['questions'] as List? ?? const [])
          ?SuperTabProposalQuestion.read(q),
      ]),
      mergedInto = _words(row['mergedInto']),
      overdue = row['overdue'] == true;

  static SuperTabProposalCard? read(Object? value) =>
      value is Map ? SuperTabProposalCard._(value) : null;

  final String text;
  final String? goal, why, doneWhen;
  final DateTime? createdAt;

  /// The people who agreed to it, first the one who proposed it.
  final List<String> senderIds;
  final SuperTabProposalDecision? decision;
  final List<SuperTabProposalQuestion> questions;

  /// The card it was merged into as a duplicate: it is no longer on the Board.
  final String? mergedInto;

  /// Waiting on the PM longer than the project's limit (spec Design, Failure).
  final bool overdue;

  /// The question still waiting for its answer, if any.
  SuperTabProposalQuestion? get openQuestion =>
      questions.where((q) => !q.answered).firstOrNull;

  /// Whether it became a task: accepted, or reshaped into the version the PM will do.
  bool get becameTask => switch (decision?.kind) {
    'accept' || 'reshape' => true,
    _ => false,
  };
}

/// The PM's decision on a proposal: `accept`, `reshape`, `later` (until [revisitAt]) or `no`, with its reason.
class SuperTabProposalDecision {
  const SuperTabProposalDecision({
    required this.kind,
    this.reason,
    this.revisitAt,
  });

  static SuperTabProposalDecision? read(Object? value) {
    if (value is! Map) return null;
    final kind = value['kind'];
    const kinds = {'accept', 'reshape', 'later', 'no'};
    if (kind is! String || !kinds.contains(kind)) return null;
    return SuperTabProposalDecision(
      kind: kind,
      reason: _words(value['reason']),
      revisitAt: _epoch(value['revisitAt']),
    );
  }

  final String kind;
  final String? reason;
  final DateTime? revisitAt;
}

/// A question the PM asked on a card, of one person, with the answer it takes by [deadline] if none comes.
class SuperTabProposalQuestion {
  const SuperTabProposalQuestion({
    required this.id,
    required this.personId,
    required this.question,
    required this.defaultAnswer,
    required this.deadline,
    required this.answered,
    this.requiresConsent = false,
  });

  static SuperTabProposalQuestion? read(Object? value) {
    if (value is! Map) return null;
    final (id, person, question) = (
      value['id'],
      value['personId'],
      value['question'],
    );
    final deadline = _epoch(value['deadline']);
    if (id is! String ||
        person is! String ||
        question is! String ||
        deadline == null) {
      return null;
    }
    return SuperTabProposalQuestion(
      id: id,
      personId: person,
      question: question,
      defaultAnswer: _words(value['defaultAnswer']) ?? '',
      deadline: deadline,
      answered: value['answer'] is Map,
      requiresConsent: value['requiresConsent'] == true,
    );
  }

  final String id, personId, question, defaultAnswer;
  final DateTime deadline;
  final bool answered, requiresConsent;
}

/// A paused task (#3819): who paused it, when, and the reason they gave, if any.
class SuperTabPause {
  const SuperTabPause({required this.by, required this.at, this.reason});

  static SuperTabPause? read(Object? value) {
    if (value is! Map || value['by'] is! String) return null;
    final at = switch (value['at']) {
      final num ms => DateTime.fromMillisecondsSinceEpoch(ms.toInt()),
      final String iso => DateTime.tryParse(iso)?.toLocal(),
      _ => null,
    };
    if (at == null) return null;
    final reason = value['reason'];
    return SuperTabPause(
      by: value['by'] as String,
      at: at,
      reason: reason is String && reason.trim().isNotEmpty ? reason : null,
    );
  }

  final String by;
  final DateTime at;
  final String? reason;
}

class SuperTabProjectStatus {
  const SuperTabProjectStatus({required this.text, this.at, this.by});

  static const maxText = 2000;

  static SuperTabProjectStatus? read(Object? value) {
    if (value is! Map) return null;
    final text = value['text'];
    if (text is! String || text.trim().isEmpty) return null;
    final at = value['at'];
    final by = value['by'];
    return SuperTabProjectStatus(
      text: text.length > maxText ? text.substring(0, maxText) : text,
      at: at is String ? DateTime.tryParse(at) : null,
      by: by is String ? by : null,
    );
  }

  final String text;
  final DateTime? at;
  final String? by;
}

class SuperTabSnapshot {
  SuperTabSnapshot.fromJson(Map<String, dynamic> row)
    : id = _text(row, 'id'),
      name = _text(row, 'name'),
      ownerId = _text(row, 'ownerId'),
      paused = row['paused'] == true,
      project = row['project'] == null
          ? null
          : Map.unmodifiable(superTabMap(row['project'])),
      people = superTabUsernames(_list(row['people'], SuperTabPerson.fromJson)),
      agents = _list(row['agents'], SuperTabAgent.fromJson),
      machines = _list(
        row['machines'] ?? const [],
        (m) => Map<String, dynamic>.unmodifiable(m),
      ),
      // The Product Managers' (Leads) conversation is removed (Dee, 10-31): a
      // server from before that still sends it has it listed and opened
      // nowhere here.
      conversations = List.unmodifiable(
        _list(
          row['conversations'],
          SuperTabConversation.fromJson,
        ).where((c) => c.kind != 'leads' && c.id != row['leadsConversationId']),
      ),
      invitations = _list(
        row['invitations'],
        (row) => Map<String, dynamic>.unmodifiable(row),
      ),
      _starts = Map.unmodifiable({
        for (final start
            in row['starts'] is List ? row['starts'] as List : const [])
          if (start case {'id': final String id})
            id: (
              harnessId: start['harnessId'] as String?,
              error: start['error'] as String?,
            ),
      }),
      startEfforts = Map.unmodifiable({
        for (final start
            in row['starts'] is List ? row['starts'] as List : const [])
          if (start case {
            'harnessId': final String harness,
            'request': {'effort': final String effort},
          })
            harness: effort,
      }),
      localModels = SuperTabLocalModels.read(row['localModels']),
      removedMachines = [
        for (final id in row['removedMachines'] as List? ?? const [])
          if (id is String) id,
      ],
      threadSessions = row['threadSessions'] == true,
      sessionsFromChat = row['sessionsFromChat'] == true,
      swarmBuddy = row['swarmBuddy'] == true,
      buddyCap = (row['buddyCap'] as num?)?.toInt(),
      autoJoin = row['autoJoin'] == true,
      mentionsWaiting = (row['mentionsWaiting'] as num?)?.toInt() ?? 0,
      mentionsDigest = row['mentionsDigest'] as String?,
      pulses = SuperTabPulse.readAll(row['pulse']),
      _releaseTimes = {
        if (row['releaseTimes'] case final Map projects)
          for (final MapEntry(key: project, value: times) in projects.entries)
            if (project is String && times is Map)
              project: {
                for (final MapEntry(key: part, value: at) in times.entries)
                  if (part is String && at is num) part: at.toInt(),
              },
      },
      decisionsWaiting = (row['decisionsWaiting'] as num?)?.toInt() ?? 0,
      decisionsDigest = row['decisionsDigest'] as String?,
      promptsWaiting = List.unmodifiable([
        for (final wait in row['promptsWaiting'] as List? ?? const [])
          if (wait case {
            'agentId': final String agentId,
            'conversationId': final String conversationId,
          })
            (agentId: agentId, conversationId: conversationId),
      ]),
      activityDigest = row['activityDigest'] as String?,
      remindersDigest = row['remindersDigest'] as String?,
      chatSettings = Map.unmodifiable({
        if (row['chatSettings'] case final Map settings)
          for (final MapEntry(:key, :value) in settings.entries)
            if (key is String && value is String) key: value,
      }),
      teamAccounts = row['teamAccounts'] != false,
      readMarks = Map.unmodifiable({
        if (row['readMarks'] case final Map marks)
          for (final MapEntry(:key, :value) in marks.entries)
            if (key is String && value is num) key: value.toInt(),
      }),
      buddiesEnabled = row['buddies'] == true,
      threadMarks = Map.unmodifiable({
        if (row['threadMarks'] case final Map marks)
          for (final MapEntry(key: id, value: threads) in marks.entries)
            if (id is String && threads is Map)
              id: Map<String, int>.unmodifiable({
                for (final MapEntry(:key, :value) in threads.entries)
                  if (key is String && value is num) key: value.toInt(),
              }),
      }),
      buddyStarts = List.unmodifiable([
        for (final start
            in row['starts'] is List ? row['starts'] as List : const [])
          if (start case {'request': {'buddyOf': Map _}})
            Map<String, dynamic>.unmodifiable(superTabMap(start)),
      ]) {
    if (row['version'] != 1) {
      throw const FormatException('Update Harness to open this Swarm.');
    }
    projects = _list(
      row['projects'] ??
          [
            {
              'id': 'lead',
              'name': name,
              'ownerId': ownerId,
              'leadConversationId': 'lead',
              'visibility': 'public',
              'members': <Object>[],
              'updateMinutes': 5,
              if (project != null) 'repository': project,
            },
          ],
      SuperTabProject.fromJson,
    );
  }
  final String id, name, ownerId;
  final Map<String, dynamic>? project;
  final bool paused;

  /// The Swarm's Buddies setting: off unless its owner turned it on, and off
  /// from a backend before Buddies.
  final bool buddiesEnabled;

  /// The starts of Buddies, oldest first: a Buddy's add is under way while
  /// its start has neither a harness nor an error.
  final List<Map<String, dynamic>> buddyStarts;
  final List<SuperTabPerson> people;
  final List<SuperTabAgent> agents;
  final List<Map<String, dynamic>> machines;
  final List<SuperTabConversation> conversations;
  late final List<SuperTabProject> projects;
  final List<Map<String, dynamic>> invitations;

  /// Each agent start's outcome so far, by its id: the harness it made, or
  /// why it failed (backend AgentStart); null for a start this read does not
  /// hold. Read as the desktop reads it (desktop_parity_test.dart).
  ({String? harnessId, String? error})? startOf(String id) => _starts[id];
  final Map<String, ({String? harnessId, String? error})> _starts;

  /// The effort each started agent's start asked for, by harness id. Empty where the starts are not read (a view
  /// kept on this device leaves them out).
  final Map<String, String> startEfforts;

  /// The Local models add-on, once the owner has turned it on; null before.
  final SuperTabLocalModels? localModels;

  /// Whether this Swarm's server takes a thread reply's New session: true only
  /// where it says so (backend read/contract.ts `threadSessions`). Read as the
  /// desktop reads it (desktop_parity_test.dart); the Buddy chat's thread reply
  /// box offers New session by it (swarm_buddy_sessions.dart).
  final bool threadSessions;

  /// The reader's own machines they took out of this Swarm: an automatic add
  /// leaves them out (backend model.ts removedMachines). Empty from an older
  /// backend.
  final List<String> removedMachines;

  /// Whether that server also takes New session on a top-level message in a
  /// Buddy chat (read/contract.ts `sessionsFromChat`); false from an older one.
  final bool sessionsFromChat;

  /// One Buddy per person for the whole Swarm (backend one-Buddy stack), as the desktop's model reads it; the phone
  /// does not draw it yet.
  final bool swarmBuddy;

  /// How many Buddies a person may have (#3818); its presence says the server makes several. Null from one that
  /// makes one.
  final int? buddyCap;

  /// People at the owner's email domain are added automatically (head
  /// `autoJoin`, every member reads it): someone who leaves is not added
  /// back. Read as the desktop's model reads it; the phone does not show it
  /// yet.
  final bool autoJoin;

  /// The reader's tags still waiting for them, Swarm-wide; 0 from a backend
  /// before tags (spec 2026-10-24-lead-mentions.md).
  final int mentionsWaiting;

  /// Which tags wait, as a digest that moves when they change though the
  /// count may not; null from a backend before it (superTabs/mentions.ts).
  final String? mentionsDigest;

  /// Each project's board pulse by project id (backend superTabs/pulse.ts,
  /// read `derived.pulse`); empty from a server before it.
  final Map<String, SuperTabPulse> pulses;

  /// [projectId]'s board pulse; null where the server sent none, and the
  /// board draws no strip.
  SuperTabPulse? pulseOf(String projectId) => pulses[projectId];

  /// When each release part of [projectId] may next open, in ms: 0 is now (backend releases.ts nextReleaseAt, task #3827).
  Map<String, int> releaseTimesOf(String projectId) =>
      _releaseTimes[projectId] ?? const {};
  final Map<String, Map<String, int>> _releaseTimes;

  /// Decisions asked of the reader and not yet answered, Swarm-wide; 0 from a
  /// backend before decisions (backend superTabs/decisions.ts).
  final int decisionsWaiting;

  /// Which decisions wait, as a digest that moves when they change though the
  /// count may not; null from a backend before it (superTabs/decisions.ts).
  final String? decisionsDigest;

  /// The task agents at a prompt in their terminals that wait for the reader,
  /// as the backend chose them (superTabs/promptWaits.ts, task #3029); empty
  /// from a backend before it.
  final List<({String agentId, String conversationId})> promptsWaiting;

  /// Which of the reader's Activity rows are unread, as a digest (backend superTabs/activity.ts); null from a backend
  /// before it. Read as the desktop's model reads it; the phone shows no Activity yet.
  final String? activityDigest;

  /// Which reminders the reader has set and when each is due, as a digest that moves when one is set, replaced or
  /// cleared; null from a backend before reminders (superTabs/reminders.ts). Read as the desktop's is; the phone
  /// shows no reminders yet.
  final String? remindersDigest;

  /// The reader's own notification setting by conversation, `all`, `mentions` or `muted` (backend chatSettings.ts).
  /// Read as the desktop's model reads it; the phone does not apply it yet.
  final Map<String, String> chatSettings;

  /// False only where the server does not try Harness Team accounts yet
  /// (backend read/contract.ts `teamAccounts`), as on the desktop.
  final bool teamAccounts;

  /// The reader's own read marks kept on the server (backend readMarks.ts): the newest message sequence read, by
  /// conversation, on any of their devices. Never another person's.
  final Map<String, int> readMarks;

  /// The reader's own thread marks kept on the server (backend readMarks.ts): by conversation, the newest message
  /// sequence read in each thread, by its root, on any of their devices. Empty from a backend before them.
  final Map<String, Map<String, int>> threadMarks;

  // Built on first use: a read is never changed, and lookups run per row on
  // every build.
  late final _conversationsById = _byId(conversations, (c) => c.id);
  late final _agentsById = _byId(agents, (a) => a.id);
  late final _projectsById = _byId(projects, (p) => p.id);
  late final _projectsByLead = <String, SuperTabProject>{
    for (final p in projects.reversed)
      ?conversation(p.leadConversationId)?.leadId: p,
  };

  SuperTabConversation? conversation(String id) => _conversationsById[id];
  SuperTabAgent? agent(String id) => _agentsById[id];
  SuperTabProject? projectById(String id) => _projectsById[id];

  SuperTabProject? projectFor(String conversationId) {
    final group = conversation(conversationId);
    return group == null ? null : projectById(group.projectId);
  }

  bool isProjectLead(String conversationId) =>
      projects.any((p) => p.leadConversationId == conversationId);

  SuperTabProject? leadProjectForAgent(String agentId) =>
      _projectsByLead[agentId];

  bool isLead(String agentId) => leadProjectForAgent(agentId) != null;

  /// What [projectId] calls its coordinator: its `coordinatorName`, or [kDefaultCoordinatorName] from a backend
  /// that names none.
  String coordinatorNameOf(String projectId) =>
      projectById(projectId)?.coordinatorName ?? kDefaultCoordinatorName;

  /// The role [agentId] goes by, and its badge: the role the project's document gives it, or, from a backend before
  /// project instructions, its kind's (Product Manager/PM, Reviewer/Rev, Engineer/Dev). Null for an unknown agent and
  /// a Buddy, which has no role.
  ({String name, String badge})? roleOf(String agentId) {
    final agent = this.agent(agentId);
    if (agent == null || agent.isBuddy) return null;
    final name = agent.roleName?.trim() ?? '';
    if (name.isNotEmpty) return (name: name, badge: superTabRoleBadge(name));
    if (isLead(agentId)) return (name: 'Product Manager', badge: 'PM');
    if (agent.role == 'reviewer') return (name: 'Reviewer', badge: 'Rev');
    return (name: 'Engineer', badge: 'Dev');
  }

  String? leadProtectionReason(String agentId) {
    final project = leadProjectForAgent(agentId);
    if (project == null) return null;
    return '${agentName(agentId)} is the ${coordinatorNameOf(project.id)} of project ${project.name}. Delete the project first.';
  }

  String agentName(String id, {String fallback = 'Agent'}) {
    final found = agent(id);
    return found?.displayName ?? found?.name ?? fallback;
  }

  /// [machineId]'s contribution to this Swarm, if it has one.
  Map<String, dynamic>? pool(String machineId) =>
      machines.where((m) => m['machineId'] == machineId).firstOrNull;

  /// The Mac a Harness Team account's pool is part of: the machine its pool names as `hostMachineId` (stamped by the
  /// backend), while that Mac is in this Swarm too, from the same person (docs/plans/2026-10-24-swarm-team-account.md).
  /// Null for every other pool, a machine used only for agents included.
  String? _macOf(Map<String, dynamic>? team) {
    final host = team?['hostMachineId'];
    if (host is! String || host == team!['machineId']) return null;
    final mac = pool(host);
    return mac != null &&
            mac['hostMachineId'] == null &&
            mac['contributorId'] == team['contributorId']
        ? host
        : null;
  }

  /// Every Harness Team account's pool in [machineId]'s row: one, or more once the account was set up again and its old
  /// pool is still listed (backend superTabs/machines.ts `teamPoolsOf`). The backend changes them with the Mac.
  List<Map<String, dynamic>> teamPoolsOf(String machineId) => [
    for (final m in machines)
      if (_macOf(m) == machineId) m,
  ];

  /// The one of them that runs teammates' work on the Mac: not being removed, and the last to report (backend
  /// superTabs/machines.ts `teamPoolOf`). Null when there is none.
  Map<String, dynamic>? teamPoolOf(String machineId) {
    num reported(Map<String, dynamic> m) => switch (m['observation']) {
      {'receivedAt': final num at} => at,
      _ => -1,
    };
    Map<String, dynamic>? best;
    for (final m in teamPoolsOf(machineId)) {
      if (m['removal'] != null) continue;
      // Removed (`harness team remove` deletes its machine): the server reads a live account never so, and the Mac is a
      // Mac without one again, which its owner can set up from its row (local Team account run, 2026-10-28).
      if (m['teamWork'] case {'code': 'TEAM_ACCOUNT_REQUIRED'}) continue;
      if (best == null || reported(m) >= reported(best)) best = m;
    }
    return best;
  }

  /// The pool whose reading [accountId] sees for the machine row [machineId]: the Mac's Harness Team account for
  /// everyone but the Mac's own contributor, since it runs their agents, also while the owner is away from the Mac; the
  /// machine's own pool otherwise. The Machines view reads a machine by this one rule.
  Map<String, dynamic>? readingPoolOf(String machineId, String? accountId) {
    final own = pool(machineId), team = teamPoolOf(machineId);
    final contributor =
        own?['contributorId'] as String? ??
        agents
            .where((a) => placeOf(a.machineId) == machineId)
            .firstOrNull
            ?.contributorId;
    return team != null && contributor != accountId ? team : own;
  }

  /// The machine [machineId] is shown as in this Swarm, one row per computer: the Mac, for its Harness Team account
  /// while that Mac is in the Swarm too; [machineId] itself otherwise.
  String placeOf(String machineId) => _macOf(pool(machineId)) ?? machineId;

  /// Whether more than one person can start work here: teammates' agents are a question only then.
  bool get hasTeammates => people.where((p) => p.role != 'viewer').length > 1;

  // Resolve people shown in chat from the same identity as the roster.
  // Recorded labels remain the fallback when a person or agent has left.
  String authorName(SuperTabMessage message) => message.fromAgent
      ? agentName(message.authorId, fallback: message.authorName)
      : people.where((p) => p.id == message.authorId).firstOrNull?.shownName ??
            superTabPersonName(message.authorName);
}

/// The Swarm's Local models add-on (docs/plans/2026-10-23-swarm-local-models.md): its grid, whether it is on, and what the
/// owner's computer last reported about setting the grid up (`ready` null until it has).
class SuperTabLocalModels {
  const SuperTabLocalModels({
    required this.grid,
    required this.enabled,
    this.ready,
    this.error,
  });

  static SuperTabLocalModels? read(Object? value) {
    if (value is! Map || value['grid'] is! String) return null;
    return SuperTabLocalModels(
      grid: value['grid'] as String,
      enabled: value['enabled'] == true,
      ready: value['ready'] is bool ? value['ready'] as bool : null,
      error: value['error'] is String ? value['error'] as String : null,
    );
  }

  final String grid;
  final bool enabled;
  final bool? ready;
  final String? error;
}

/// One model the Swarm can start Builders on now, as a machine's fresh reading says: on the Swarm's grid (`local`, a
/// member's engine; `api`, an API a member shares), usable from any machine; or shared with the machine's owner and
/// offered by them (`shared`), usable on that machine alone.
typedef SuperTabLocalModelRow = ({
  String grid,
  String model,
  String name,
  String machine,
  String kind,
});

/// Whether [pool] is a Harness Team account's: stamped with the Mac it runs on (`hostMachineId`), whether or not that
/// Mac is still in the Swarm, or read as signed in as a Team account (`sessionKind`), as the backend tells them
/// (superTabs/machines.ts).
bool superTabTeamAccountPool(Map<String, dynamic> pool) =>
    switch (pool['hostMachineId']) {
      final String host when host.isNotEmpty => true,
      _ => false,
    } ||
    switch (pool['observation']) {
      {'sessionKind': 'team'} => true,
      _ => false,
    };

/// Every model the Swarm can use now, once each, from the machines' fresh readings (backend `MACHINE_FRESH_MS`). With
/// [lentBy], only those of the machines that person lends the Swarm: never a teammate's, nor a Harness Team account's
/// ([superTabTeamAccountPool]), which runs teammates' work.
List<SuperTabLocalModelRow> superTabLocalModelRows(
  SuperTabSnapshot? snapshot, {
  required DateTime now,
  Duration freshFor = const Duration(seconds: 45),
  String? lentBy,
}) {
  final local = snapshot?.localModels;
  if (local == null || !local.enabled) return const [];
  final rows = <SuperTabLocalModelRow>[];
  for (final pool in snapshot!.machines) {
    if (lentBy != null &&
        (pool['contributorId'] != lentBy || superTabTeamAccountPool(pool))) {
      continue;
    }
    final observation = pool['observation'];
    if (observation is! Map) continue;
    final at = observation['receivedAt'];
    if (at is! num ||
        now.difference(DateTime.fromMillisecondsSinceEpoch(at.toInt())) >
            freshFor) {
      continue;
    }
    for (final m
        in observation['localModels'] is List
            ? observation['localModels'] as List
            : const []) {
      // Still starting (the grid does not list it yet): not usable by the Swarm now.
      if (m is! Map ||
          m['grid'] is! String ||
          m['model'] is! String ||
          m['starting'] == true) {
        continue;
      }
      final grid = m['grid'] as String, model = m['model'] as String;
      if (rows.any((r) => r.grid == grid && r.model == model)) continue;
      rows.add((
        grid: grid,
        model: model,
        name: m['name'] is String ? m['name'] as String : model,
        machine: pool['name'] as String? ?? 'A machine',
        kind: m['kind'] is String
            ? m['kind'] as String
            : grid == local.grid
            ? 'local'
            : 'shared',
      ));
    }
  }
  return rows;
}

/// One model a machine serves on the Swarm's grid, as its last reading says.
typedef SuperTabServedModel = ({String model, String name});

/// The models [pool]'s reading says it serves on [grid]. A reading older than [freshFor] says nothing (backend
/// `MACHINE_FRESH_MS`), as the route reads it.
List<SuperTabServedModel> superTabServedModels(
  Map<String, dynamic>? pool,
  String grid, {
  required DateTime now,
  Duration freshFor = const Duration(seconds: 45),
}) {
  final observation = pool?['observation'];
  if (observation is! Map) return const [];
  final at = observation['receivedAt'];
  if (at is! num ||
      now.difference(DateTime.fromMillisecondsSinceEpoch(at.toInt())) >
          freshFor) {
    return const [];
  }
  return [
    for (final m
        in observation['localModels'] is List
            ? observation['localModels'] as List
            : const [])
      if (m is Map &&
          m['grid'] == grid &&
          m['model'] is String &&
          m['starting'] != true)
        (
          model: m['model'] as String,
          name: m['name'] is String
              ? m['name'] as String
              : m['model'] as String,
        ),
  ];
}

class SuperTabRouteChoice {
  const SuperTabRouteChoice(this.id, this.title);
  final String id, title;
}

/// The routing decision a Lead message reports: who got the task and why.
class SuperTabRoute {
  SuperTabRoute._(
    this.decisionId,
    this.via,
    this.p,
    this.why,
    this.pick,
    this.alternatives,
  );
  static SuperTabRoute? fromSource(Map<String, dynamic> s) {
    final pick = s['pick'];
    final decisionId = s['decisionId'];
    if (s['kind'] != 'route' ||
        decisionId is! String ||
        pick is! Map ||
        pick['id'] is! String ||
        pick['title'] is! String) {
      return null;
    }
    final via = s['via'];
    final why = s['why'];
    final alternatives = s['alternatives'];
    return SuperTabRoute._(
      decisionId,
      via is String ? via : 'order',
      s['p'] is num ? (s['p'] as num).toDouble() : null,
      why is String ? why : '',
      SuperTabRouteChoice(pick['id'] as String, pick['title'] as String),
      [
        if (alternatives is List)
          for (final a in alternatives)
            if (a is Map && a['id'] is String && a['title'] is String)
              SuperTabRouteChoice(a['id'] as String, a['title'] as String),
      ],
    );
  }

  /// The reason for the task. An older backend's quality-floor flag and
  /// policy-order fallback are not read: nothing is refused for a floor.
  final String decisionId, via, why;
  final double? p;
  final SuperTabRouteChoice pick;
  final List<SuperTabRouteChoice> alternatives;
}

/// A file sent with a message. The chat never loads [url] by itself.
class SuperTabAttachment {
  SuperTabAttachment.fromJson(Map<String, dynamic> row)
    : id = _text(row, 'id'),
      name = _text(row, 'name'),
      mime = _text(row, 'mime'),
      size = (row['size'] as num).toInt(),
      url = _text(row, 'url'),
      // Read defensively: a field of the wrong type reads as absent, never as
      // a failed row.
      link = row['link'] is String ? row['link'] as String : null,
      unlinked = row['unlinked'] == true,
      expiresAt = row['expiresAt'] is num
          ? (row['expiresAt'] as num).toInt()
          : null,
      voice = SuperTabVoice.read(row['voice']),
      width = _positive(row['width']),
      height = _positive(row['height']),
      thumb = SuperTabThumb.read(row['thumb']);

  /// [url] is the address the file was stored with, on the attachments CDN:
  /// what an older server hands out, and what stops opening once the bucket
  /// is private.
  final String id, name, mime, url;
  final int size;

  /// A short-lived signed link to the file (backend fileLinks.ts), made for
  /// this read; null from an older server, or when none could be signed.
  /// Opened in place of [url] whenever there is one (swarm_file_links.dart).
  final String? link;

  /// The server could not sign a link this time: [url] is never opened then,
  /// a fresh link is asked for first (it may sign now).
  final bool unlinked;

  /// When [link] stops opening, in epoch milliseconds.
  final int? expiresAt;

  /// What makes this file a voice message, drawn as one
  /// (swarm_voice_bubble.dart); null for any other file.
  final SuperTabVoice? voice;

  /// A picture's size as it is shown, and the small copy the backend made of
  /// it at upload (superTabs/thumbnails.ts): the chat draws [thumb] and the
  /// full-screen viewer opens the original. Null for any other file, a picture
  /// sent before thumbnails, and from an older backend.
  final int? width, height;
  final SuperTabThumb? thumb;

  /// The kinds the backend serves to be seen in place; every other kind is
  /// served as a download.
  bool get isImage => const {
    'image/png',
    'image/jpeg',
    'image/gif',
    'image/webp',
  }.contains(mime);
}

int? _positive(Object? value) =>
    value is num && value == value.toInt() && value > 0 ? value.toInt() : null;

/// The thumbnail of a picture: linked in the same read as the original, so
/// whoever may open the original may open it and nobody else.
class SuperTabThumb {
  const SuperTabThumb({
    required this.url,
    required this.width,
    required this.height,
    required this.size,
    this.link,
    this.expiresAt,
    this.unlinked = false,
  });

  /// [row] as a thumbnail, or null when any part of it does not read: the
  /// picture is then drawn from the original.
  static SuperTabThumb? read(Object? row) {
    if (row is! Map) return null;
    final width = _positive(row['width']),
        height = _positive(row['height']),
        size = _positive(row['size']);
    if (row['url'] is! String ||
        width == null ||
        height == null ||
        size == null) {
      return null;
    }
    return SuperTabThumb(
      url: row['url'] as String,
      width: width,
      height: height,
      size: size,
      link: row['link'] is String ? row['link'] as String : null,
      expiresAt: row['expiresAt'] is num
          ? (row['expiresAt'] as num).toInt()
          : null,
      unlinked: row['unlinked'] == true,
    );
  }

  final String url;
  final int width, height, size;

  /// Its short-lived signed link, as [SuperTabAttachment.link] is the original's.
  final String? link;
  final int? expiresAt;

  /// The backend could not sign it this time: the original is drawn.
  final bool unlinked;
}

/// A voice message's clip, as the backend read it before it was sent
/// (backend superTabs/voiceMessages.ts): its words are the message's text.
class SuperTabVoice {
  const SuperTabVoice({
    required this.length,
    required this.waveform,
    required this.transcribed,
    this.overLimit = false,
  });

  /// The tallest bar of [waveform].
  static const barMax = 31;

  /// A voice that does not read as one is none: the file still shows, as a
  /// file.
  static SuperTabVoice? read(Object? row) {
    if (row is! Map) return null;
    final ms = row['durationMs'], bars = row['waveform'];
    final transcribed = row['transcribed'];
    if (ms is! num || bars is! List || transcribed is! bool) return null;
    return SuperTabVoice(
      length: Duration(milliseconds: ms.toInt()),
      waveform: List.unmodifiable([
        for (final bar in bars) bar is num ? bar.toInt().clamp(0, barMax) : 0,
      ]),
      transcribed: transcribed,
      overLimit: row['failure'] == 'limit',
    );
  }

  final Duration length;

  /// How loud each slice of the clip is, 0 to [barMax].
  final List<int> waveform;

  /// Whether its words were heard; without them the message's text is empty.
  final bool transcribed;

  /// It has no words because its sender's daily voice limit was used.
  final bool overLimit;
}

/// A message's files. A row that does not read is left out, so one bad row
/// cannot hide the page of messages it came in.
List<SuperTabAttachment> _attachments(Object? rows) => List.unmodifiable([
  if (rows is List)
    for (final row in rows) ?_tryAttachment(row),
]);

SuperTabAttachment? _tryAttachment(Object? row) {
  try {
    return SuperTabAttachment.fromJson(superTabMap(row));
  } catch (_) {
    return null;
  }
}

/// Messages in the order a conversation shows them: by sequence, then id, as
/// the backend pages them (messages from before the parts migration can share
/// a sequence).
int superTabMessageOrder(SuperTabMessage a, SuperTabMessage b) {
  final bySequence = a.sequence.compareTo(b.sequence);
  return bySequence != 0 ? bySequence : a.id.compareTo(b.id);
}

/// Where a conversation's older history continues: the message a page ended
/// on (docs/design/2026-10-26-swarm-state-parts.md, section 4.6).
class SuperTabPage {
  const SuperTabPage(this.sequence, this.id);
  SuperTabPage.of(SuperTabMessage message) : this(message.sequence, message.id);

  /// The backend's `next`, or null at the start of the conversation.
  static SuperTabPage? read(Object? next) => switch (next) {
    {'sequence': final num sequence, 'id': final String id} => SuperTabPage(
      sequence.toInt(),
      id,
    ),
    null => null,
    _ => throw const FormatException('Invalid Swarm page.'),
  };

  final int sequence;
  final String id;
  Map<String, dynamic> toJson() => {'sequence': sequence, 'id': id};
}

/// Optional timing/hold fields keep messages from older backends readable.
class SuperTabDelivery {
  SuperTabDelivery.fromJson(Map<String, dynamic> row)
    : id = row['id'] as String?,
      agentId = row['agentId'] as String? ?? '',
      status = row['status'] as String? ?? '',
      holdReason = row['holdReason'] as String?,
      holdSince = _date(row['holdSince']),
      claimFailingSince = _date(row['claimFailingSince']),
      claimFailures = (row['claimFailures'] as num?)?.toInt(),
      deliveredAt = _date(row['deliveredAt']),
      answeredAt = _date(row['answeredAt']),
      updatedAt = _date(row['updatedAt']);
  final String? id, holdReason;
  final String agentId, status;

  /// Since when the backend's claims of this delivery fail, and how many have
  /// (prod 10-30, v1.3.71). Null from an older backend, and once a claim works.
  final DateTime? claimFailingSince;
  final int? claimFailures;
  final DateTime? holdSince, deliveredAt, answeredAt, updatedAt;

  static DateTime? _date(Object? value) =>
      value is String ? DateTime.tryParse(value) : null;
  bool get pending => status == 'queued' || status == 'claimed';
  bool get delivered => status == 'delivered' || status == 'confirmed';

  // One line cannot promise arrival while another recipient still waits, and
  // one agent's cancelled copy is no Not sent while another got the message
  // (10-30): Not sent only when no recipient got it.
  int get receiptOrder => switch (status) {
    'uncertain' => 0,
    'queued' || 'claimed' => 1,
    'delivered' || 'confirmed' => 2,
    'answered' => 3,
    'cancelled' => 4,
    _ => 5,
  };
}

/// What a page says about one thread (backend threads.ts): the line under its
/// root, and who it marks unread for. Read as the desktop's model reads it
/// (desktop_parity_test); the phone draws the line, not yet who it is unread
/// for.
class SuperTabThread {
  SuperTabThread.fromJson(Map<String, dynamic> row)
    : id = _text(row, 'id'),
      ask = row['ask'] as String?,
      replies = (row['replies'] as num).toInt(),
      lastSequence = (row['lastSequence'] as num).toInt(),
      lastAt = DateTime.tryParse(row['lastAt'] as String? ?? ''),
      authors = List.unmodifiable(
        (row['authors'] as List? ?? const []).map(superTabMap),
      ),
      people = List.unmodifiable(
        (row['people'] as List? ?? const []).whereType<String>(),
      );
  final String id;

  /// Where the ask at its root stands (backend threads.ts).
  final String? ask;

  /// What its root's row says after the time: a Buddy's proposal nobody has
  /// answered yet; null for any other message. A task's state is no tag: its
  /// agent reacts 👀 and ✅ on the row instead (anh Dee, 11-04, task #2925),
  /// so an older server's On it and Shipped draw nothing.
  String? get askTag => ask == 'proposal' ? '✋ Proposal' : null;
  final int replies, lastSequence;
  final DateTime? lastAt;

  /// The newest distinct reply authors, newest first: the first wrote the
  /// last reply.
  final List<Map<String, dynamic>> authors;

  /// People who wrote in the thread or were tagged in it.
  final List<String> people;
}

/// The source kinds of a task's root in the project chat.
const _taskRootKinds = {'task-line', 'buddy-proposal'};

/// What a task's root posted before #2867 reads ahead of its title. Stored rows
/// keep it, so this stays for as long as rows from before 2026-11-04 are kept.
const _oldTaskRootPrefix = "Let's build: ";

String _messageText(Map<String, dynamic> row) {
  final text = _text(row, 'text');
  return _taskRootKinds.contains(
            superTabMap(row['source'] ?? const {})['kind'],
          ) &&
          text.startsWith(_oldTaskRootPrefix)
      ? text.substring(_oldTaskRootPrefix.length)
      : text;
}

class SuperTabMessage {
  SuperTabMessage.fromJson(Map<String, dynamic> row)
    : id = _text(row, 'id'),
      conversationId = _text(row, 'conversationId'),
      text = _messageText(row),
      replyTo = row['replyTo'] as String?,
      thread = row['thread'] as String?,
      alsoInChat = row['alsoInChat'] == true,
      buddySession = row['buddySession'] == true,
      sequence = (row['sequence'] as num).toInt(),
      author = Map.unmodifiable(superTabMap(row['author'])),
      source = Map.unmodifiable(superTabMap(row['source'] ?? const {})),
      createdAt = DateTime.tryParse(row['createdAt'] as String? ?? ''),
      editedAt = DateTime.tryParse(row['editedAt'] as String? ?? ''),
      deletedAt = DateTime.tryParse(row['deletedAt'] as String? ?? ''),
      attachments = _attachments(row['attachments']),
      reactions = List.unmodifiable(
        SuperTabReactionCount.listFromJson(row['reactions']),
      ),
      mentions = List.unmodifiable(
        (row['mentions'] as List?)?.whereType<String>() ?? const <String>[],
      ),
      deliveries = _list(
        row['deliveries'] ?? const [],
        (d) => Map<String, dynamic>.unmodifiable(d),
      );
  final String id, conversationId, text;
  final String? replyTo;

  /// The root of this message's thread: its own id for a top-level message,
  /// null for one written before threads (its replies stay inline quotes).
  final String? thread;

  /// A thread reply also shown in the conversation's main stream.
  final bool alsoInChat;

  /// A reply in a Buddy thread session's thread (desktop model.dart).
  final bool buddySession;

  /// The line the server writes in a thread when its session ends.
  bool get sessionEnded => source['kind'] == 'buddy-session-ended';

  /// Why its session ended, for [sessionEnded] rows: `ended`, `idle`,
  /// `stopped` or `failed`.
  String? get sessionEndReason =>
      sessionEnded ? source['reason'] as String? : null;
  bool get threadReply => thread != null && thread != id;

  /// Whether the main stream lists it: a thread reply only when also sent.
  bool get inMainStream => !threadReply || alsoInChat;
  final int sequence;
  final Map<String, dynamic> author;
  final Map<String, dynamic> source;
  final DateTime? createdAt;

  /// When its author last changed its text; null for one never edited
  /// (backend messageEdits.ts). No earlier text is kept anywhere.
  final DateTime? editedAt;

  /// When its author deleted it: kept only as the root of a thread with
  /// replies, its text then the backend's "This message was deleted.", with
  /// no files and no reactions. One without replies leaves the pages.
  final DateTime? deletedAt;

  bool get deleted => deletedAt != null;
  final List<SuperTabAttachment> attachments;
  final List<SuperTabReactionCount> reactions;

  /// The people a Lead tagged in this message, by person id.
  final List<String> mentions;
  final List<Map<String, dynamic>> deliveries;
  // Preserve the recorded identity for history and for removed agents. Views
  // with a current roster resolve the visible name through Snapshot.authorName.
  String get authorName =>
      (fromAgent ? author['displayName'] as String? : null) ??
      author['name'] as String? ??
      'Unknown';
  String get authorId => author['id'] as String? ?? '';
  bool get fromAgent => author['kind'] == 'agent';
  bool get fromTerminal => source['kind'] == 'native';

  /// What was typed into an agent's terminal, a scheduled prompt too: no chat
  /// row (Ken 11-04, task #2849; the desktop's). Its answer still is one.
  bool get terminalPrompt => fromTerminal && source['phase'] == 'prompt';

  /// A terminal's recording gap: no chat row and nothing unread, since it gives
  /// a person nothing to do (Dee 11-05, task #3127). The server keeps it for
  /// diagnosis, and a required recovery still reaches the coordinator.
  bool get terminalGap => fromTerminal && source['phase'] == 'gap';
  SuperTabRoute? get route => SuperTabRoute.fromSource(source);
  bool get routeOverride => source['kind'] == 'route-override';

  /// A line the backend posted for an instructions save: no chat row and
  /// nothing unread, since it gives a person nothing to do (Dee 11-05, task
  /// #3165). The backend posts none since #3132; the History keeps every
  /// revision.
  bool get instructionsSave => source['kind'] == 'instructions';

  /// A task's root the server posted in its person's name (plain chat, #2294):
  /// theirs to read, not their own writing, so it reads nothing before it and
  /// is unread for them as anyone else's message is.
  bool get postedForAuthor => _taskRootKinds.contains(source['kind']);

  /// The agent a "waiting at a prompt" note is about; null for any other row.
  String? get promptAlertAgentId =>
      source['kind'] == 'terminal-alert' && source['alert'] == 'prompt'
      ? source['agentId'] as String?
      : null;

  /// The Product Manager a usage-limit note is about; null for any other row
  /// (desktop model.dart).
  String? get leadLimitAgentId =>
      source['kind'] == 'terminal-alert' &&
          source['alert'] == 'limit' &&
          source['lead'] == true
      ? source['agentId'] as String?
      : null;

  /// A note the backend writes about a terminal: a Lead's typing, or an alert.
  bool get terminalEvent =>
      source['kind'] == 'terminal-input' || source['kind'] == 'terminal-alert';
  String? get terminalNote {
    if (!fromTerminal) return null;
    final phase = source['phase'];
    if (phase == 'gap') return 'Terminal recording interrupted';
    final operator =
        superTabMap(source['operator'] ?? const {})['name'] as String?;
    return phase == 'prompt' && operator != null
        ? 'Terminal input · session opened by $operator'
        : 'Terminal answer';
  }

  SuperTabDelivery? get receiptDelivery {
    final rows = deliveries.map(SuperTabDelivery.fromJson).toList();
    rows.sort((a, b) => a.receiptOrder.compareTo(b.receiptOrder));
    return rows.firstOrNull;
  }
}

/// The `remote` a daemon reports for a project: `host/owner/repo`, already
/// without credentials or transport (the CLI's `canonicalRepository`). A port
/// there may be SSH's, so only a plain host is read as an HTTPS address.
final _canonicalRemote = RegExp(
  r'^(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}/\S+$',
  caseSensitive: false,
);

/// A remote may contain a developer's embedded credential. Never share it.
/// Contributed machines clone this address, so a daemon's canonical remote
/// becomes the HTTPS URL that Harness's GitHub project source also clones.
String? superTabRepositoryUrl(String? remote) {
  if (remote == null || remote.isEmpty) return null;
  if (remote.startsWith('git@') && !remote.contains('://')) return remote;
  final address = _canonicalRemote.hasMatch(remote)
      ? 'https://$remote'
      : remote;
  final uri = Uri.tryParse(address);
  if (uri == null ||
      uri.host.isEmpty ||
      !['https', 'http', 'ssh', 'git'].contains(uri.scheme)) {
    return null;
  }
  if (uri.userInfo.isNotEmpty &&
      !(uri.scheme == 'ssh' && uri.userInfo == 'git')) {
    return null;
  }
  return address;
}