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.

61.9 KB
Raw Blame
/// Data models mirroring the backend/web types.
library;

import 'package:flutter/foundation.dart' show immutable, listEquals;

import 'agent_activity.dart';
import 'runtime_model_name.dart';
import 'agent_git_context.dart';

enum MachineAuthMode { managed, remote, self, provider }

enum ConnectionStatus { disconnected, connecting, connected, reconnecting }

/// Current SSO identity returned by GET /api/auth/me.
class CurrentUserProfile {
  final String? id;
  final String? name;
  final String email;
  final String? avatarUrl;

  const CurrentUserProfile({
    this.id,
    this.name,
    required this.email,
    this.avatarUrl,
  });

  const CurrentUserProfile.local()
    : id = null,
      name = 'Local session',
      email = 'local terminal',
      avatarUrl = null;

  factory CurrentUserProfile.fromMe(Map<String, dynamic> response) {
    final rawUser = response['user'];
    if (rawUser is! Map) {
      throw const FormatException('missing user profile');
    }
    final user = Map<String, dynamic>.from(rawUser);
    final email = user['email'];
    if (email is! String || email.trim().isEmpty) {
      throw const FormatException('missing user email');
    }
    final rawName = user['name'];
    final rawAvatar = response['avatarUrl'];
    return CurrentUserProfile(
      id: user['id'] is String ? user['id'] as String : null,
      name: rawName is String && rawName.trim().isNotEmpty
          ? rawName.trim()
          : null,
      email: email.trim(),
      avatarUrl: rawAvatar is String && rawAvatar.trim().isNotEmpty
          ? rawAvatar.trim()
          : null,
    );
  }

  String get displayName => name ?? email;

  String get initials {
    final source = (name ?? email).trim();
    if (source.isEmpty) return '?';
    final words = source.split(RegExp(r'\s+')).where((word) => word.isNotEmpty);
    final chars = words.take(2).map((word) => word[0].toUpperCase()).join();
    return chars.isEmpty ? '?' : chars;
  }
}

/// A view-only invitation. It never contains a full machine credential.
class SharedHarness {
  const SharedHarness({
    required this.id,
    required this.agentId,
    required this.name,
    this.engine,
    required this.expiresAt,
    this.ownerPublicKey,
  });
  final String id, agentId, name;
  final String? engine;
  final DateTime expiresAt;
  final String? ownerPublicKey;
  factory SharedHarness.fromJson(Map<String, dynamic> j) => SharedHarness(
    id: j['id'] as String,
    agentId: j['agentId'] as String,
    name: j['name'] as String,
    engine: j['engine'] as String?,
    expiresAt: DateTime.parse(j['expiresAt'] as String),
    ownerPublicKey: j['ownerPublicKey'] as String?,
  );
}

/// Control-plane machine (GET /api/machines).
/// Two spellings of the same machine or computer id.
///
/// The backend stores a computer id with its dashes stripped
/// (`d11a1f3bca2a44e9…`) while `~/.harness/computer-id` — which is what the
/// daemon serves under while signed out, and therefore what a tile made then is
/// keyed by — keeps them (`d11a1f3b-ca2a-44e9-…`). The same id, written two
/// ways, and a plain `==` between them never matches. Anything comparing an id
/// that crossed that boundary has to come through here.
bool sameMachineId(String a, String b) =>
    a.replaceAll('-', '').toLowerCase() == b.replaceAll('-', '').toLowerCase();

/// A whole machine another account shares with this one (backend lib/machineAccess.ts): its owner
/// named this account's address ([via] `email`), or shared it with everyone at their domain and this
/// account added it ([via] `domain`, [added]). This account is a guest there: a space of its own, its
/// own harnesses on the owner's plans, nothing of the owner's (docs/plans/2026-10-19-guest-machine-sharing-plan.md);
/// unlike [Machine.isShared], one harness shared to watch.
class MachineShare {
  final String ownerName;
  final String ownerEmail;
  final String via;
  final bool added;

  const MachineShare({
    required this.ownerName,
    required this.ownerEmail,
    required this.via,
    required this.added,
  });

  bool get viaDomain => via == 'domain';

  factory MachineShare.fromJson(Map<String, dynamic> j) => MachineShare(
    ownerName: j['ownerName'] as String? ?? '',
    ownerEmail: j['ownerEmail'] as String? ?? '',
    via: j['via'] == 'domain' ? 'domain' : 'email',
    added: j['added'] == true,
  );

  /// Who shared it, as a person reads it: their name, or their address.
  String get owner => ownerName.isNotEmpty ? ownerName : ownerEmail;
}

class Machine {
  final String machineId;

  /// Legacy fixture-only field. Production `/api/machines` no longer exposes machine API keys.
  final String apiKey;
  final String? computerId;
  final MachineAuthMode authMode;
  final String? engine;
  final String? name;
  final String? hostname;
  final bool isShared;
  final String? ownerName;
  final List<SharedHarness> sharedHarnesses;
  final String? status;

  /// Set when another account shares this whole machine with this one; null for the account's own.
  final MachineShare? machineShare;

  /// How its computer signed in on its last connect, as the machine list says
  /// (`team` for a Harness Team account, `computer` otherwise, null when an
  /// older backend sends none).
  final String? sessionKind;

  const Machine({
    required this.machineId,
    this.apiKey = '',
    this.computerId,
    required this.authMode,
    this.engine,
    this.name,
    this.hostname,
    this.isShared = false,
    this.ownerName,
    this.sharedHarnesses = const [],
    this.status,
    this.machineShare,
    this.sessionKind,
  });

  /// A Harness Team account's machine: the account's, but its daemon signs in
  /// with a team session, which the server never lets act as the person. The
  /// person's own Swarm requests never go through it.
  bool get isTeamAccount => sessionKind == 'team';

  /// Another account's machine, shared with this one: this account is a guest there, with its own space and
  /// harnesses; the machine is managed (renamed, removed, shared on) by its owner alone.
  bool get isSharedMachine => machineShare != null;

  String get displayName => (name != null && name!.isNotEmpty)
      ? name!
      : 'machine-${machineId.length > 8 ? machineId.substring(0, 8) : machineId}';

  /// What the machine list says about this computer being up — `null` when it
  /// says a word neither side has agreed on, which is not the same as "down".
  ///
  /// This is the ONE signal that speaks for a machine we have never reached:
  /// our own socket goes to the local daemon, so its being up says nothing
  /// about whether the far end answered. Kept on the model rather than in
  /// `AppNotifier` because the box reads it too, and two copies of a word list
  /// are two chances to disagree about what "stopped" means.
  bool? get reportedOnline => switch (status?.trim().toLowerCase()) {
    'running' || 'online' || 'connected' || 'ready' => true,
    'offline' ||
    'stopped' ||
    'disconnected' ||
    'unreachable' ||
    'error' ||
    'failed' => false,
    _ => null,
  };

  factory Machine.fromJson(Map<String, dynamic> j) => Machine(
    machineId: j['machineId'] as String,
    apiKey: j['apiKey'] as String? ?? '',
    computerId: j['computerId'] as String?,
    authMode: MachineAuthMode.values.firstWhere(
      (m) => m.name == j['authMode'],
      orElse: () => MachineAuthMode.managed,
    ),
    engine: j['engine'] as String?,
    name: j['name'] as String?,
    hostname: j['hostname'] as String?,
    isShared: j['shared'] == true,
    ownerName: j['ownerName'] as String?,
    sharedHarnesses: [
      for (final row in j['shares'] as List? ?? const [])
        SharedHarness.fromJson(Map<String, dynamic>.from(row as Map)),
    ],
    status: j['status'] as String?,
    machineShare: j['share'] is Map
        ? MachineShare.fromJson(Map<String, dynamic>.from(j['share'] as Map))
        : null,
    sessionKind: j['sessionKind'] as String?,
  );

  Machine copyWith({String? name}) => Machine(
    machineId: machineId,
    apiKey: apiKey,
    computerId: computerId,
    authMode: authMode,
    engine: engine,
    name: name ?? this.name,
    hostname: hostname,
    isShared: isShared,
    ownerName: ownerName,
    sharedHarnesses: sharedHarnesses,
    status: status,
    machineShare: machineShare,
    sessionKind: sessionKind,
  );
}

/// Whether an agent on a Local model can search the web, as the daemon decided when it built the
/// launch (`grid.webSearch` on the agent frame).
///
/// Three words, each a different fact for the person reading the picker: `on` needs no sentence;
/// `unavailable` means the daemon could not obtain the web-tools configuration this time (an
/// outdated CLI, no sign-in) and moving the agent again may fix it; `unsupported` means the engine
/// cannot take the tools on this machine at all (Pi has no MCP client; Hermes under a
/// system-managed install), and nothing about the model changes that.
enum GridWebSearch {
  on,
  unavailable,
  unsupported;

  /// The one sentence shown for a degraded status, or null when there is nothing to say.
  String? get sentence => switch (this) {
    GridWebSearch.on => null,
    GridWebSearch.unavailable => 'Web search unavailable',
    GridWebSearch.unsupported => 'Web search not supported by this engine',
  };

  /// The wire word, or null for anything else — an older daemon sends no field, and a newer one
  /// might send a fourth word this build should neither print verbatim nor guess at.
  static GridWebSearch? fromWire(Object? raw) => switch (raw) {
    'on' => GridWebSearch.on,
    'unavailable' => GridWebSearch.unavailable,
    'unsupported' => GridWebSearch.unsupported,
    _ => null,
  };
}

/// Data-plane agent (RPC agents_list).
/// Where a forked agent came from — see [Agent.forkedFrom].
class ForkedFrom {
  final String agentId;
  final String name;

  const ForkedFrom({required this.agentId, required this.name});

  static ForkedFrom? fromJson(Object? raw) {
    if (raw is! Map) return null;
    final agentId = raw['agentId'];
    if (agentId is! String || agentId.isEmpty) return null;
    final name = raw['name'];
    return ForkedFrom(
      agentId: agentId,
      name: name is String && name.isNotEmpty ? name : 'a harness',
    );
  }
}

/// Display-only fallbacks; never send these to a CLI as a user rename.
const kUntitledPane = 'Untitled Pane';
final _automaticHarnessName = RegExp(
  r'^(?:(?:harness|agent)-[1-9]\d*|.+ harness \d{1,2}-\d{1,2} \d{1,2}:\d{2}(?::\d{2})?)$',
);

bool isAutomaticHarnessName(String name) =>
    _automaticHarnessName.hasMatch(name);

/// Only measurements confirmed by this harness's own tool receipts.
class AgentOutputStats {
  const AgentOutputStats({
    this.linesAdded,
    this.linesRemoved,
    this.pullRequestsCreated,
    this.updatedAt,
  });
  final int? linesAdded, linesRemoved, pullRequestsCreated;
  final DateTime? updatedAt;
  bool get hasEdits => linesAdded != null && linesRemoved != null;
  bool get isEmpty => !hasEdits && pullRequestsCreated == null;
  static AgentOutputStats? fromJson(Object? value) {
    if (value is! Map) return null;
    int? count(Object? n) =>
        n is int && n >= 0 && n <= 9007199254740991 ? n : null;
    final added = count(value['linesAdded']),
        removed = count(value['linesRemoved']);
    final stats = AgentOutputStats(
      linesAdded: removed == null ? null : added,
      linesRemoved: added == null ? null : removed,
      pullRequestsCreated: count(value['pullRequestsCreated']),
      updatedAt: value['updatedAt'] is String
          ? DateTime.tryParse(value['updatedAt'] as String)
          : null,
    );
    return stats.isEmpty ? null : stats;
  }

  @override
  bool operator ==(Object other) =>
      other is AgentOutputStats &&
      linesAdded == other.linesAdded &&
      linesRemoved == other.linesRemoved &&
      pullRequestsCreated == other.pullRequestsCreated &&
      updatedAt == other.updatedAt;
  @override
  int get hashCode =>
      Object.hash(linesAdded, linesRemoved, pullRequestsCreated, updatedAt);
}

/// What a cloud agent's frame says beyond an agent's usual one (CLI
/// lib/cloudAgents.ts `CloudFrameBlock`): where it runs, where it is, what it
/// is doing, its links at its maker (the session, a pull request) and how many
/// messages its conversation holds, which the chat pane reads again when it moves.
class AgentCloud {
  final String place;

  /// `starting`, `working`, `needs_input`, `idle`, `failed` or `stopped`.
  final String state;
  final String? activity;
  final List<({String label, String url})> links;
  final int messages;

  const AgentCloud({
    required this.place,
    required this.state,
    this.activity,
    this.links = const [],
    this.messages = 0,
  });

  bool get working => state == 'working' || state == 'starting';

  /// The pull request among its links, for the footer; null with none.
  ({String label, String url})? get pullRequest {
    for (final link in links) {
      if (RegExp(r'^https://github\.com/[^/]+/[^/]+/pull/\d+$')
          .hasMatch(link.url))
        return link;
    }
    return null;
  }

  static AgentCloud fromJson(Object? raw) {
    final j = raw is Map ? raw : const {};
    String? text(Object? value, int max) =>
        value is String && value.trim().isNotEmpty
        ? (value.length > max ? value.substring(0, max) : value)
        : null;
    final links = <({String label, String url})>[];
    if (j['links'] is List) {
      for (final link in j['links'] as List) {
        if (link is! Map) continue;
        final label = text(link['label'], 80), url = text(link['url'], 2048);
        if (label != null && url != null && url.startsWith('https://')) {
          links.add((label: label, url: url));
        }
      }
    }
    const states = {
      'starting',
      'working',
      'needs_input',
      'idle',
      'failed',
      'stopped',
    };
    final state = j['state'];
    final messages = j['messages'];
    return AgentCloud(
      place: text(j['place'], 80) ?? 'The cloud',
      state: state is String && states.contains(state) ? state : 'idle',
      activity: text(j['activity'], 200),
      links: links,
      messages: messages is int && messages >= 0 ? messages : 0,
    );
  }
}

class Agent {
  final AgentActivity? activity;
  final String id;
  final String? sessionId;
  final String name;

  /// What the agent is on, in its own words — the transcript's title as the
  /// daemon cleaned it, null when it has none or it is the name already. A
  /// search finds an agent by this before it finds one by a recap.
  final String? title;
  final String? engine;
  final String? engineDisplayName;
  final String? engineIconHint;
  final String? codexHome;

  /// The Claude account folder (`CLAUDE_CONFIG_DIR`) this agent runs in; null for the default account.
  final String? claudeHome;

  /// Model observed in this session by the daemon, when available. Independent
  /// of [gridModel], which determines subscription versus local-model routing.
  final String? modelName;

  /// Effort reported with [modelName], never inferred from a model default.
  final String? modelEffort;

  /// [modelName] as the engine names it (`claude-opus-5-5`), for a launch.
  final String? modelId;

  /// The grid model this agent is CURRENTLY running on, or null for its own vendor login.
  ///
  /// Read by the daemon off the live process on every discovery, never bookkept — so it is the
  /// truth even for an agent someone re-pointed by hand. Null is a real answer, not a missing one.
  final String? gridModel;

  /// Whether the agent can search the web on that model, or null when the daemon said nothing —
  /// an agent on its own login, an older daemon, or a grid agent it merely discovered. Decided by
  /// the daemon when it built the launch and carried on every frame, so it is right after a
  /// reconnect or a restart without anything being replayed.
  final GridWebSearch? gridWebSearch;

  /// Where [gridModel] is served — the endpoint the engine was handed (a grid's relay, or a saved
  /// API such as `https://openrouter.ai/api`). Null with no [gridModel], or from an older daemon.
  final String? gridBaseUrl;

  /// How the daemon's picture has the grid this agent's model is on (`grid.state`), or null when
  /// it did not say — an agent on its own login, or an older daemon. Asleep or waking is what puts
  /// the "Starting up…" chip on its pane between a message and the first answer.
  final GridSectionState? gridState;

  /// Why the agent's model will not answer right now (`grid.note`), or null when nothing is wrong.
  final GridNote? gridNote;
  final String? parentAgentId;

  /// `agent` when another agent started this harness, wherever that agent
  /// runs; null when the person did (cli lib/agentFrame.ts `startedBy`).
  final String? startedBy;

  /// Started by the Swarm: by an agent, from no harness on this machine, as
  /// the CLI tells one (superTabs/inCore/adoption.ts `swarmStarted`). Every
  /// Buddy is one.
  bool get startedBySwarm => startedBy == 'agent' && parentAgentId == null;
  final AgentProject? project;
  final AgentGitContext? gitContext;
  AgentProject? get displayProject =>
      gitContext?.displayProject(project) ?? project;

  /// The CLI's transcript/hook activity time, not its registry refresh time.
  final DateTime? lastActivityAt;
  final DateTime? createdAt;
  final bool closeSupported;

  /// Whether a person chose [name] (the daemon's `nameChosen`: they renamed the
  /// agent), as against the name it was created with or the engine's session
  /// title. Null from a daemon that does not say; only a true one is sent to
  /// the Swarm (task #2920).
  final bool? nameChosen;
  final String? closePlanState;
  final String? closePlanDetail;

  /// When a person last opened or focused this harness in ANY client, as the
  /// owning daemon recorded it (`lastOpenedAt`, stamped by `agent_update
  /// {opened: true}`). Null when never opened, or from a daemon that predates
  /// the field.
  final DateTime? lastOpenedAt;

  /// Cached conversation usage reported by this agent's owning machine.
  final int? tokensUsed;
  final DateTime? tokensUpdatedAt;
  final AgentOutputStats? outputStats;
  bool get hasMonitorStats =>
      tokensUsed != null || (outputStats != null && !outputStats!.isEmpty);
  final String status;
  final String launchState;
  final String? launchError;
  final String? launchDetail;
  final bool terminalAvailable;
  final String? terminalUnavailableReason;

  /// The domain-specific harness this agent was created from (`autonomous/autonomous-circuit`), or
  /// null for a plain engine. [engine] stays the BASE engine the process actually runs —
  /// a DSH is a decoration on the session, never a second engine (see the DSH spec in
  /// `store/spec/README.md`). Everything a person sees keys off this when it is set.
  final String? dsh;

  /// The harness's display name as the daemon read it off the manifest. Lets a DSH this
  /// build has never heard of still show its own name rather than its id.
  final String? dshName;

  /// The URL of the harness's viewer for this agent, served on the agent's machine, or null
  /// when there is none (yet). A change means the viewer pane must navigate.
  final String? viewerUrl;

  /// Why this remote viewer could not be forwarded, including old-daemon update guidance.
  final String? viewerError;

  /// What the harness's viewer pane is called — the shared viewer's own name ("3D Viewer"), or
  /// the harness's name and "Viewer" for one it ships ("Marp Viewer") — as the daemon worked it
  /// out. Null from an older daemon or with no viewer; see [PaneGrid] for what stands in.
  final String? viewerName;

  /// The harness's last verdict on this workspace, or null when it has not written one.
  final AgentVerdict? verdict;

  /// The agent this one was forked from (`agent_fork`), or null for every
  /// other agent. Carries the source's name as it was at the fork, because the
  /// source may be renamed or gone by the time the badge is read.
  final ForkedFrom? forkedFrom;

  /// Whether the daemon can fork this agent (`agent_fork`), as it said on the
  /// frame; null from a daemon that predates the field — then the engine
  /// decides (see [canFork]).
  final bool? forkable;

  /// How much a Pause of this harness can promise to bring back, as the daemon
  /// reports it (`lib/resumeCapability.ts`): `shell`, `conversation` or
  /// `fresh`. Null from a daemon that predates the field — see
  /// [canPauseAndResume] for what this build assumes then.
  final String? resumeMode;

  /// The permission mode this agent was launched in (`plan`, `readOnly`, …),
  /// as the daemon recorded it; null from a daemon that predates the field, a
  /// row from before the choice existed, or an agent Harness did not launch.
  /// Read for Clone (⌘⇧N), so another of this one opens in the same mode.
  final String? permissionMode;

  /// Whether its permission prompts were bypassed at launch; null when
  /// unrecorded (see [permissionMode]) — then a clone uses the default.
  final bool? bypassPermission;

  /// The engine's own named agent it was opened as (`agent_create`'s `agent`),
  /// or null for a general session.
  final String? namedAgent;

  /// A cloud agent's harness (`location: 'cloud'`): it runs on its maker's
  /// servers and has no terminal, so its pane is a chat pane. Null for every
  /// agent that runs on a computer (docs/design/2026-10-11-cloud-agents.md).
  final AgentCloud? cloud;

  /// Extra launch flags saved on the machine for this agent (a Buddy's `--chrome`), as words.
  /// Empty from an older daemon or an agent with none.
  final List<String> launchArgs;

  bool get isCloud => cloud != null;

  const Agent({
    this.activity,
    required this.id,
    this.sessionId,
    required this.name,
    this.title,
    this.engine,
    this.engineDisplayName,
    this.engineIconHint,
    this.codexHome,
    this.claudeHome,
    this.modelName,
    this.modelEffort,
    this.modelId,
    this.gridModel,
    this.gridWebSearch,
    this.gridBaseUrl,
    this.gridState,
    this.gridNote,
    this.parentAgentId,
    this.startedBy,
    this.project,
    this.gitContext,
    this.lastActivityAt,
    this.createdAt,
    this.closeSupported = false,
    this.nameChosen,
    this.closePlanState,
    this.closePlanDetail,
    this.lastOpenedAt,
    this.tokensUsed,
    this.tokensUpdatedAt,
    this.outputStats,
    this.status = 'active',
    this.launchState = 'ready',
    this.launchError,
    this.launchDetail,
    this.terminalAvailable = false,
    this.terminalUnavailableReason,
    this.dsh,
    this.dshName,
    this.viewerUrl,
    this.viewerError,
    this.viewerName,
    this.verdict,
    this.forkedFrom,
    this.forkable,
    this.resumeMode,
    this.permissionMode,
    this.bypassPermission,
    this.namedAgent,
    this.cloud,
    this.launchArgs = const [],
  });

  bool get isStopped => status == 'stopped';

  /// Whether this is still the session a close reviewed as [reviewed]: the
  /// same registration in the same conversation, or one that had no
  /// conversation when it was reviewed and has bound its first since.
  ///
  /// Codex binds none for its first seconds, so a pane closed just after it
  /// started was reviewed unbound and had bound one by the time the person
  /// pressed Stop. Read as a change, that Stop was answered "The session
  /// changed. Check it before closing." and the harness kept running (clean
  /// macOS VM, Desktop 1.2.65, Codex 0.162.1, 2026-10-12). The close still
  /// names the identity it reviewed, no conversation, and the daemon accepts
  /// that only from a harness still starting — not one resumed, typed into a
  /// terminal or older than a minute (cli `closeAgentService.ts` `matches`).
  /// A different conversation once one was bound is always a change.
  bool continuesSession(Agent reviewed) =>
      createdAt == reviewed.createdAt &&
      (sessionId == reviewed.sessionId ||
          (reviewed.sessionId?.isEmpty ?? true));

  /// Exact saved-conversation resume is currently implemented for these engines.
  bool get canResumeConversation =>
      (engine == 'claude' || engine == 'codex') &&
      sessionId?.isNotEmpty == true;

  /// Whether the Harnesses panel may pause this harness and bring it back.
  ///
  /// Every engine can, and the daemon says so per engine through [resumeMode]
  /// — a client that kept its own allow-list is how the two drifted, with
  /// engines the daemon would happily resume greyed out here for a year.
  /// What DIFFERS per engine is how much comes back, which
  /// [resumesFreshConversation] answers and the button's wording says.
  ///
  /// The fallback is for a daemon that predates the field: the old rule, so an
  /// older machine is never offered a Pause its CLI will refuse. `'terminal'`
  /// is `kTerminalEngine` (`widgets/engine_identity.dart`), spelled out for the
  /// same reason `'claude'`/`'codex'` are above: this is the model layer and
  /// does not reach into the widgets.
  bool get canPauseAndResume =>
      resumeMode != null || engine == 'terminal' || canResumeConversation;

  /// Whether resuming this harness opens a NEW conversation rather than the one
  /// it was paused in — either because the engine has no resume argv (`fresh`),
  /// or because nothing recorded a conversation to reopen. The button says so
  /// before it is pressed, and a resume that reports it is a success, not a
  /// failure.
  bool get resumesFreshConversation =>
      resumeMode == 'fresh' ||
      (resumeMode == 'conversation' && (sessionId?.isEmpty ?? true));

  /// Explicit names win. An automatic CLI label gives way to its session title.
  String get displayName => _automaticHarnessName.hasMatch(name)
      ? (title?.trim().isNotEmpty == true ? title!.trim() : kUntitledPane)
      : name;

  /// The engines whose sessions can be forked — natively (Claude Code's
  /// `--fork-session`, `codex fork`) or by a handoff message (OpenCode takes a
  /// first prompt). The daemon is the authority when it says (`forkable`);
  /// this is the answer for one that does not.
  static const forkableEngines = {'claude', 'codex', 'opencode'};

  /// Whether to offer Fork for this agent at all. Devin, Cursor and the rest
  /// can neither fork nor open with a message, so the button is not drawn
  /// rather than drawn and refused.
  bool get canFork => forkable ?? forkableEngines.contains(engine);

  /// Whether Clone (⌘⇧N) can open another of this agent — any engine, but not
  /// one on a grid: the frame carries the grid's model and never its launch
  /// key, so a clone would silently land on the engine's own login instead.
  bool get canClone => engine != null && gridModel == null;

  /// What to draw this agent AS: its harness when it has one, else its engine.
  String? get identityEngine => dsh ?? engine;

  /// The name that goes with [identityEngine], for an id this build has no picture of.
  String? get identityDisplayName => dsh != null ? dshName : engineDisplayName;

  factory Agent.fromJson(Map<String, dynamic> j) {
    final terminal = j['terminal'];
    final terminalMap = terminal is Map
        ? Map<String, dynamic>.from(terminal)
        : const <String, dynamic>{};
    final runtimes = terminalMap['runtimes'] is List
        ? terminalMap['runtimes'] as List
        : const [];
    final hasTmux = runtimes.any(
      (runtime) => runtime is Map && runtime['backend'] == 'tmux',
    );
    final advertisedAvailable = terminalMap['available'];
    final terminalAvailable = advertisedAvailable is bool
        ? advertisedAvailable
        : hasTmux;
    final launchRaw = j['launch'];
    final launch = launchRaw is Map
        ? Map<String, dynamic>.from(launchRaw)
        : const <String, dynamic>{};
    // `held`: the daemon will not start it yet, and says why, such as a
    // conversation another process may have open. Read as `ready` it showed
    // only its name over an empty pane ("Unavailable"), with no reason
    // (onboarding reopening a team's recent conversations, 2026-10-09).
    final launchState = switch (launch['state']) {
      'starting' => 'starting',
      'failed' => 'failed',
      'held' => 'held',
      _ => 'ready',
    };
    final grid = j['grid'] as Map<String, dynamic>?;
    final usage = j['tokenUsage'];
    final total = usage is Map ? usage['totalTokens'] : null;
    final validTokens = total is int && total >= 0 && total <= 9007199254740991;
    final model = runtimeModelDetails(
      j['selectedModel'],
      agentId: j['id'] as String,
      engine: _safeEngine(j['engine']),
    );
    return Agent(
      activity: AgentActivity.fromJson(j['activity']),
      id: j['id'] as String,
      sessionId: _safeLabel(j['sessionId']),
      name: j['name'] as String? ?? 'harness',
      title: _safeLabel(j['title']),
      engine: _safeEngine(j['engine']),
      engineDisplayName: _safeLabel(j['engineDisplayName']),
      engineIconHint: _safeLabel(j['engineIconHint']),
      codexHome: j['engine'] == 'codex' ? _safeCodexHome(j['codexHome']) : null,
      claudeHome: j['engine'] == 'claude'
          ? _safeCodexHome(j['claudeHome'])
          : null,
      modelName: model?.name,
      modelEffort: model?.effort,
      modelId: model?.id,
      gridModel: _safeLabel(grid?['model']),
      gridWebSearch: GridWebSearch.fromWire(grid?['webSearch']),
      gridBaseUrl: _safeUrl(grid?['baseUrl']),
      gridState: GridSectionState.parse(grid?['state']),
      gridNote: GridNote.fromWire(grid?['note']),
      parentAgentId: _safeLabel(j['parentAgentId'] ?? j['parentId']),
      startedBy: j['startedBy'] == 'agent' ? 'agent' : null,
      project: AgentProject.fromJson(j['project']),
      gitContext: AgentGitContext.fromJson(j['gitContext']),
      lastActivityAt: j['updatedAt'] is String
          ? DateTime.tryParse(j['updatedAt'] as String)
          : null,
      createdAt: j['createdAt'] is String
          ? DateTime.tryParse(j['createdAt'] as String)
          : null,
      closeSupported: j['closeSupported'] == true,
      nameChosen: j['nameChosen'] is bool ? j['nameChosen'] as bool : null,
      closePlanState:
          j['closePlan'] is Map &&
              const {'waiting', 'failed'}.contains(j['closePlan']['state'])
          ? j['closePlan']['state'] as String
          : null,
      closePlanDetail: j['closePlan'] is Map
          ? _safeDetail(j['closePlan']['detail'])
          : null,
      lastOpenedAt: j['lastOpenedAt'] is String
          ? DateTime.tryParse(j['lastOpenedAt'] as String)
          : null,
      tokensUsed: validTokens ? total : null,
      tokensUpdatedAt:
          validTokens && usage is Map && usage['updatedAt'] is String
          ? DateTime.tryParse(usage['updatedAt'] as String)
          : null,
      outputStats: AgentOutputStats.fromJson(j['outputStats']),
      status: (j['status'] as String?) ?? 'active',
      launchState: launchState,
      launchError: launchState == 'failed' ? _safeLabel(launch['error']) : null,
      launchDetail: launchState == 'failed' || launchState == 'held'
          ? _safeDetail(launch['detail'])
          : null,
      terminalAvailable: terminalAvailable,
      terminalUnavailableReason: terminalAvailable
          ? null
          : _safeLabel(terminalMap['reason']) ??
                'terminal unavailable (no verified terminal pane)',
      dsh: _safeDsh(j['dsh']),
      dshName: _safeLabel(j['dshName']),
      viewerUrl: _safeViewerUrl(j['viewerUrl']),
      viewerError: _safeDetail(j['viewerError']),
      viewerName: _safeLabel(j['viewerName']),
      verdict: AgentVerdict.fromJson(j['verdict']),
      forkedFrom: ForkedFrom.fromJson(j['forkedFrom']),
      forkable: j['forkable'] is bool ? j['forkable'] as bool : null,
      resumeMode: _safeResumeMode(j['resumeMode']),
      permissionMode: _safePermissionMode(j['permissionMode']),
      bypassPermission: j['bypassPermission'] is bool
          ? j['bypassPermission'] as bool
          : null,
      namedAgent: _safeNamedAgent(j['namedAgent']),
      cloud: j['location'] == 'cloud' ? AgentCloud.fromJson(j['cloud']) : null,
      launchArgs: j['launchArgs'] is List
          ? [
              for (final w in j['launchArgs'] as List)
                if (w is String) w,
            ]
          : const [],
    );
  }

  Agent copyWith({
    String? name,
    AgentGitContext? gitContext,
    String? status,
    bool? terminalAvailable,
    DateTime? lastOpenedAt,
    bool clearClosePlan = false,
  }) => Agent(
    activity: activity,
    id: id,
    sessionId: sessionId,
    name: name ?? this.name,
    title: title,
    engine: engine,
    engineDisplayName: engineDisplayName,
    engineIconHint: engineIconHint,
    codexHome: codexHome,
    claudeHome: claudeHome,
    modelName: modelName,
    modelEffort: modelEffort,
    modelId: modelId,
    gridModel: gridModel,
    gridWebSearch: gridWebSearch,
    gridBaseUrl: gridBaseUrl,
    gridState: gridState,
    gridNote: gridNote,
    parentAgentId: parentAgentId,
    startedBy: startedBy,
    project: project,
    gitContext: gitContext ?? this.gitContext,
    lastActivityAt: lastActivityAt,
    createdAt: createdAt,
    closeSupported: closeSupported,
    nameChosen: nameChosen,
    closePlanState: clearClosePlan ? null : closePlanState,
    closePlanDetail: clearClosePlan ? null : closePlanDetail,
    lastOpenedAt: lastOpenedAt ?? this.lastOpenedAt,
    tokensUsed: tokensUsed,
    tokensUpdatedAt: tokensUpdatedAt,
    outputStats: outputStats,
    status: status ?? this.status,
    launchState: launchState,
    launchError: launchError,
    launchDetail: launchDetail,
    terminalAvailable: terminalAvailable ?? this.terminalAvailable,
    terminalUnavailableReason: terminalUnavailableReason,
    dsh: dsh,
    dshName: dshName,
    viewerUrl: viewerUrl,
    viewerError: viewerError,
    viewerName: viewerName,
    verdict: verdict,
    forkedFrom: forkedFrom,
    forkable: forkable,
    resumeMode: resumeMode,
    permissionMode: permissionMode,
    bypassPermission: bypassPermission,
    namedAgent: namedAgent,
    cloud: cloud,
    launchArgs: launchArgs,
  );

  /// A mode id as `PERMISSION_MODES` spells them (`acceptEdits`, `readOnly`):
  /// one word. Not checked against this build's own list — the daemon that
  /// launched the agent is the authority, and it is the one that will read the
  /// id back on a clone.
  /// One of the daemon's three resume modes, or null for anything else — an
  /// older daemon that does not send it, or a newer one that grew a fourth
  /// this build has no wording for.
  static String? _safeResumeMode(Object? raw) =>
      raw is String && const {'shell', 'conversation', 'fresh'}.contains(raw)
      ? raw
      : null;

  static String? _safePermissionMode(Object? raw) =>
      raw is String && RegExp(r'^[A-Za-z]{1,32}$').hasMatch(raw) ? raw : null;

  /// The daemon's `AGENT_NAME_RE` (engineLaunch.ts): a flag value, never a path.
  static String? _safeNamedAgent(Object? raw) =>
      raw is String && RegExp(r'^[A-Za-z0-9_-]{1,64}$').hasMatch(raw)
      ? raw
      : null;

  /// `owner/name`, exactly the shape the DSH manifest schema allows and nothing else — the
  /// id names an install directory on the far machine and a picker tile here.
  static String? _safeDsh(Object? raw) {
    if (raw is! String || raw.isEmpty || raw.length > 129) return null;
    return RegExp(r'^[a-z0-9][a-z0-9-]{0,63}/[a-z0-9][a-z0-9-]{0,63}$')
            .hasMatch(raw)
        ? raw
        : null;
  }

  /// A loopback or plain http(s) URL the viewer pane may load. Anything else — a `file:`,
  /// a `javascript:`, a string with control characters — is dropped rather than navigated
  /// to, since this lands straight in a webview.
  static String? _safeViewerUrl(Object? raw) {
    if (raw is! String || raw.isEmpty || raw.length > 2048) return null;
    if (RegExp(r'[\x00-\x1f\x7f\s]').hasMatch(raw)) return null;
    final uri = Uri.tryParse(raw);
    if (uri == null || !uri.hasAuthority) return null;
    if (uri.scheme != 'http' && uri.scheme != 'https') return null;
    return raw;
  }

  static String? _safeEngine(Object? raw) {
    if (raw is! String || raw.isEmpty || raw.length > 64) return null;
    return RegExp(r'^[a-zA-Z0-9._-]+$').hasMatch(raw) ? raw : null;
  }

  // A profile folder as the agent's own machine spells it, which may not be this one's: `/…`, or `C:\…` on Windows (#4183).
  static String? _safeCodexHome(Object? raw) {
    if (raw is! String ||
        !(raw.startsWith('/') || RegExp(r'^[A-Za-z]:\\').hasMatch(raw)) ||
        raw.length > 4096 ||
        RegExp(r'[\x00-\x1f\x7f]').hasMatch(raw)) {
      return null;
    }
    return raw;
  }

  static String? _safeUrl(Object? raw) {
    if (raw is! String || raw.isEmpty || raw.length > 2048) return null;
    final uri = Uri.tryParse(raw);
    return uri != null && (uri.scheme == 'https' || uri.scheme == 'http')
        ? raw
        : null;
  }

  static String? _safeLabel(Object? raw) {
    if (raw is! String || raw.isEmpty) return null;
    return raw.length <= 80 ? raw : raw.substring(0, 80);
  }

  static String? _safeDetail(Object? raw) {
    if (raw is! String || raw.isEmpty) return null;
    final clean = raw.replaceAll(RegExp(r'[\u0000-\u001f\u007f]'), ' ').trim();
    if (clean.isEmpty) return null;
    return clean.length <= 500 ? clean : clean.substring(0, 500);
  }
}

/// A domain-specific harness's verdict on an agent's workspace, as the daemon read it off
/// `.harness/verdict.json` (see `store/spec/README.md`). Counts rather than the findings
/// themselves: the pane header has room for "3 errors", and the findings live in the
/// harness's own viewer.
enum AgentPhaseState { done, active, pending, failed }

/// One phase of a harness's work, as its verdict names it: where the agent is.
class AgentPhase {
  const AgentPhase({
    required this.id,
    required this.name,
    this.state = AgentPhaseState.pending,
    this.artifact,
  });

  final String id;
  final String name;
  final AgentPhaseState state;
  final String? artifact;

  @override
  bool operator ==(Object other) =>
      other is AgentPhase &&
      id == other.id &&
      name == other.name &&
      state == other.state &&
      artifact == other.artifact;

  @override
  int get hashCode => Object.hash(id, name, state, artifact);

  static AgentPhase? fromJson(Object? raw) {
    if (raw is! Map) return null;
    final name = AgentVerdict._safeText(raw['name'], 40);
    if (name == null || name.isEmpty) return null;
    final id = AgentVerdict._safeText(raw['id'], 40);
    final state = switch (raw['state']) {
      'done' => AgentPhaseState.done,
      'active' => AgentPhaseState.active,
      'failed' => AgentPhaseState.failed,
      _ => AgentPhaseState.pending,
    };
    return AgentPhase(
      id: id == null || id.isEmpty ? name.toLowerCase() : id,
      name: name,
      state: state,
      artifact: AgentVerdict._safeText(raw['artifact'], 1024),
    );
  }
}

@immutable
class AgentVerdict {
  const AgentVerdict({
    required this.ready,
    this.summary,
    this.errors = 0,
    this.warnings = 0,
    this.artifact,
    this.phases = const [],
    this.updatedAt,
  });

  /// The one machine fact: fab-ready, all gates passed, exam passed.
  final bool ready;

  /// One line for the header's tooltip.
  final String? summary;
  final int errors;
  final int warnings;

  /// Workspace-relative path of the primary thing to look at, when the harness named one.
  final String? artifact;

  /// Where the work is, in order — at most twelve; empty when the harness
  /// names no phases, and then the header draws no strip.
  final List<AgentPhase> phases;
  final DateTime? updatedAt;

  /// The phase under way, when one is.
  AgentPhase? get activePhase =>
      phases.where((p) => p.state == AgentPhaseState.active).firstOrNull;

  /// The one phase the header shows: the one under way, else the last one
  /// that has happened — done or failed — else nothing. A status, not a
  /// history: each new one replaces the last.
  AgentPhase? get currentPhase {
    final active = activePhase;
    if (active != null) return active;
    for (final phase in phases.reversed) {
      if (phase.state != AgentPhaseState.pending) return phase;
    }
    return null;
  }

  static AgentVerdict? fromJson(Object? raw) {
    if (raw is! Map) return null;
    final ready = raw['ready'];
    if (ready is! bool) return null;
    final updated = raw['updatedAt'];
    return AgentVerdict(
      ready: ready,
      summary: _safeText(raw['summary'], 200),
      errors: _safeCount(raw['errors']),
      warnings: _safeCount(raw['warnings']),
      artifact: _safeText(raw['artifact'], 1024),
      phases: _phases(raw['phases']),
      updatedAt: updated is String ? DateTime.tryParse(updated) : null,
    );
  }

  static List<AgentPhase> _phases(Object? raw) {
    if (raw is! List) return const [];
    return [for (final item in raw.take(12)) ?AgentPhase.fromJson(item)];
  }

  static int _safeCount(Object? raw) {
    if (raw is! num || raw.isNaN || raw < 0) return 0;
    return raw > 9999 ? 9999 : raw.toInt();
  }

  static String? _safeText(Object? raw, int max) {
    if (raw is! String) return null;
    final clean = raw.replaceAll(RegExp(r'[\u0000-\u001f\u007f]'), ' ').trim();
    if (clean.isEmpty) return null;
    return clean.length <= max ? clean : clean.substring(0, max);
  }

  @override
  bool operator ==(Object other) =>
      other is AgentVerdict &&
      other.ready == ready &&
      other.summary == summary &&
      other.errors == errors &&
      other.warnings == warnings &&
      other.artifact == artifact &&
      listEquals(other.phases, phases) &&
      other.updatedAt == updatedAt;

  @override
  int get hashCode => Object.hash(
    ready,
    summary,
    errors,
    warnings,
    artifact,
    Object.hashAll(phases),
    updatedAt,
  );
}

/// What the daemon answered when asked where a typed task belongs (⌘B).
///
/// `candidates` is the pick followed by EVERY other agent the daemon weighed — ranked where the router
/// ranked them, in rail order after that. Not a shortlist: when the router is unsure the right agent is
/// often the one it put fourth, and a picker that cannot show it leaves no way forward but Esc.
/// The window reads it only when `confidence` is too low to act on — the whole point of the number
/// being on the wire.
class RouteAnswer {
  const RouteAnswer({
    required this.agentId,
    required this.machineId,
    required this.name,
    required this.confidence,
    required this.reason,
    required this.candidates,
    this.weighed = 0,
    this.machines = 0,
    this.via = '',
  });

  final String agentId;

  /// Which computer the pick lives on. Names are for reading; this is what opens the pane.
  final String machineId;
  final String name;
  final double confidence;
  final String reason;
  final List<RouteCandidate> candidates;

  /// How many agents were weighed, and across how many computers.
  ///
  /// Shown WHILE the router thinks, because the question during those seconds is not "how long" — it is
  /// "did it even look at the agent I mean". The daemon caps the list it weighs, so this is the only
  /// place that can answer it.
  final int weighed;
  final int machines;

  /// 'model' when a classifier answered, 'heuristic' when name matching stood in for it, '' when the
  /// daemon did not say.
  ///
  /// Both land under the threshold BY DESIGN — an unsure model and a router that could not run must both
  /// stop and ask — which is exactly why the window needs to tell them apart: "not sure which agent" and
  /// "the router could not run" send a person to different next moves.
  final String via;

  /// True when nobody was picked at all — an empty machine, or a daemon that could not answer.
  bool get isEmpty => agentId.isEmpty;

  /// Read with `is`, never with `as`.
  ///
  /// `json['x'] as String?` does not answer null for a number — it THROWS, and this frame crosses a
  /// socket, so the shape is whatever the other end sent. An exception here surfaces as a palette
  /// spinner that never comes down, which is the one failure the person cannot act on. A malformed field
  /// has to read as "nobody was picked" instead.
  static RouteAnswer fromJson(Map<String, dynamic> json) => RouteAnswer(
    agentId: _str(json['agentId']),
    machineId: _str(json['machineId']),
    name: _str(json['name']),
    confidence: json['confidence'] is num
        ? (json['confidence'] as num).toDouble()
        : 0,
    reason: _str(json['reason']),
    weighed: json['weighed'] is num ? (json['weighed'] as num).toInt() : 0,
    machines: json['machines'] is num ? (json['machines'] as num).toInt() : 0,
    via: _str(json['via']),
    candidates: [
      for (final entry
          in (json['candidates'] is List
              ? json['candidates'] as List<dynamic>
              : const []))
        if (entry is Map<String, dynamic>) RouteCandidate.fromJson(entry),
    ],
  );
}

class RouteCandidate {
  const RouteCandidate({
    required this.agentId,
    required this.machineId,
    required this.name,
    required this.machine,
    required this.recent,
    this.engine = '',
    this.confidence = 0,
  });

  final String agentId;

  /// Which computer to open the pane on. Names are for reading; this is for acting.
  final String machineId;
  final String name;

  /// Which computer it runs on. The candidate list spans every machine, so two agents named "api" on two
  /// of them are the same row twice without this.
  final String machine;

  /// What that agent was last doing — the line under its name when the window has to ask.
  final String recent;

  /// Which CLI it runs on. The picker wears the same engine mark the rail does, so a row here and the
  /// same agent in the rail are recognisably one thing rather than two lists that happen to share names.
  final String engine;

  /// How well the router thought this one fits, 0..1. DISPLAY ONLY.
  ///
  /// Nothing is dispatched on it — the pick is [RouteAnswer.agentId] and the number that gates it is
  /// [RouteAnswer.confidence]. 0 means the router said nothing about this candidate, and the picker
  /// draws no bar rather than an empty one, because an empty bar reads as "no fit" and this is "no
  /// answer".
  final double confidence;

  static RouteCandidate fromJson(Map<String, dynamic> json) => RouteCandidate(
    agentId: _str(json['agentId']),
    machineId: _str(json['machineId']),
    name: _str(json['name']),
    machine: _str(json['machine']),
    recent: _str(json['recent']),
    engine: _str(json['engine']),
    confidence: json['confidence'] is num
        ? (json['confidence'] as num).toDouble().clamp(0, 1)
        : 0,
  );
}

String _str(Object? value) => value is String ? value : '';

/// How a checkout on no branch reports itself, `Detached 65281563`: the
/// daemon (cli/src/lib/agentProject.ts) and [LocalGitProjects] both say so.
const kDetachedBranchPrefix = 'Detached ';

/// Context reported by the owning daemon. Missing on older daemons.
class AgentProject {
  const AgentProject({
    required this.name,
    required this.cwd,
    this.root,
    this.remote,
    this.repository,
    this.branch,
    this.worktree = false,
    this.branchPending = false,
  });
  final String name;
  final String cwd;
  final String? root;
  final String? remote;

  /// The repository [remote] stands for when its host is an SSH alias
  /// (`gh-work/acme/api` is `github.com/acme/api`, cli agentProject.ts
  /// `aliasRepository`). Null when [remote] names its real host, and from an
  /// older daemon.
  final String? repository;
  final String? branch;

  /// In a linked worktree rather than the repository's own checkout.
  final bool worktree;

  /// [branch] still has the name Harness made up at Start; it is shown once
  /// the session's name replaces it.
  final bool branchPending;

  /// The folder as the person chose it: inside a Git checkout, a subfolder
  /// shows as itself and the checkout's root as its remote repository name
  /// (falling back to [name]), even
  /// when the checkout is a temporary worktree. Outside Git it is [name], the
  /// folder itself. The branch beside it is the repository's.
  String get label {
    final checkout = root;
    if (checkout == null) return name;
    String trimmed(String path) => path.replaceFirst(RegExp(r'[/\\]+$'), '');
    if (trimmed(checkout) == trimmed(cwd)) {
      final repository = remote == null
          ? ''
          : trimmed(remote!)
                .split('/')
                .last
                .replaceFirst(RegExp(r'\.git$', caseSensitive: false), '');
      return repository.isEmpty ? name : repository;
    }
    return cwd
            .split(RegExp(r'[/\\]'))
            .where((part) => part.isNotEmpty)
            .lastOrNull ??
        name;
  }

  /// On a commit rather than a branch: an agent reading or testing one.
  bool get detached => branch?.startsWith(kDetachedBranchPrefix) == true;

  /// The branch worth showing beside the folder: none while Harness's made-up
  /// name waits for the session's, and none on no branch at all.
  String? get shownBranch => branchPending || detached ? null : branch;

  /// The branch as a tooltip says it.
  String? get branchDetail => branch == null
      ? null
      : detached
      ? 'No branch: on commit ${branch!.substring(kDetachedBranchPrefix.length)}'
      : 'Branch: $branch';

  String identity(String machineId) =>
      remote != null ? 'repo:$remote' : 'folder:$machineId:${root ?? cwd}';

  @override
  bool operator ==(Object other) =>
      other is AgentProject &&
      name == other.name &&
      cwd == other.cwd &&
      root == other.root &&
      remote == other.remote &&
      repository == other.repository &&
      branch == other.branch &&
      worktree == other.worktree &&
      branchPending == other.branchPending;
  @override
  int get hashCode => Object.hash(
    name,
    cwd,
    root,
    remote,
    repository,
    branch,
    worktree,
    branchPending,
  );

  static AgentProject? fromJson(Object? raw) {
    if (raw is! Map) return null;
    String? field(String key, [int max = 4096]) {
      final v = raw[key];
      return v is String &&
              v.isNotEmpty &&
              v.length <= max &&
              !RegExp(r'[\x00-\x1f\x7f]').hasMatch(v)
          ? v
          : null;
    }

    final name = field('name', 256);
    final cwd = field('cwd');
    if (name == null || cwd == null) return null;
    return AgentProject(
      name: name,
      cwd: cwd,
      root: field('root'),
      remote: field('remote'),
      repository: field('repository'),
      branch: field('branch', 256),
      worktree: raw['worktree'] == true,
      branchPending: raw['branchPending'] == true,
    );
  }
}

/// One model the account's private harness grid can answer right now.
class GridModel {
  /// The id an engine is pointed at, verbatim from the grid.
  final String id;

  /// Which machine serves it. Display only, and empty when the grid does not say — on a private
  /// grid this is one of the user's own computers, which is the useful part of the answer.
  final String node;

  /// The grid it is served on — the section it was listed under. Null on an older daemon that
  /// sends only the own grid's list, which the retarget then targets as it always did.
  final String? grid;

  /// Set when every computer serving this row seems offline — see [GridModelUnavailable]. Null
  /// for every other row, and always from a daemon that predates it.
  final GridModelUnavailable? unavailable;

  const GridModel({
    required this.id,
    required this.node,
    this.grid,
    this.unavailable,
  });
}

/// Why a listed model will not answer, as the daemon labels a row (`unavailable`, sent only to a
/// client that asked with `rowState: true`).
///
/// Only `offline` is a reason this build knows: every computer serving the row read offline twice,
/// a minute apart. The row is labelled, never removed — the daemon may be wrong about a computer
/// that is merely asleep, and a move onto it is the person's call. A reason this build has not
/// heard of is no claim at all, the rule [GridSectionState] follows.
class GridModelUnavailable {
  /// The computer's name as the Machines list shows it.
  final String machine;

  /// When it was first read offline, or null when the daemon did not say.
  final DateTime? since;

  const GridModelUnavailable({required this.machine, this.since});

  static GridModelUnavailable? fromWire(Object? raw) {
    if (raw is! Map || raw['reason'] != 'offline') return null;
    final machine = Agent._safeLabel(raw['machine']);
    if (machine == null) return null;
    final since = raw['since'];
    return GridModelUnavailable(
      machine: machine,
      since: since is String ? DateTime.tryParse(since) : null,
    );
  }
}

/// What came of the last explicit wake of a section that did not end in models (`wakeOutcome`).
///
/// A wake that shows models leaves nothing — the section is simply awake with them. The daemon
/// keeps an outcome until a later read finds the section awake with a model, or ten minutes pass.
enum GridWakeOutcome {
  /// The section could not be started; it will start on the next message.
  notStarted,

  /// It started, and nobody is serving a model on it.
  nobodyServing;

  static GridWakeOutcome? parse(Object? raw) => switch (raw) {
    'not_started' => GridWakeOutcome.notStarted,
    'nobody_serving' => GridWakeOutcome.nobodyServing,
    _ => null,
  };
}

/// Why an agent's model will not answer right now, as the daemon notes it on the agent's frame
/// (`grid.note`): [GridNoteOffline] or [GridNoteNotServed].
///
/// Absent when there is nothing to say; the daemon re-pushes the agent when it clears, and never
/// notes an agent on Auto (no model).
sealed class GridNote {
  /// The model the agent is on, as the daemon named it in the note.
  final String model;

  const GridNote(this.model);

  /// Read defensively: a reason this build does not know, or a note missing the names its
  /// sentence needs, is no note at all.
  static GridNote? fromWire(Object? raw) {
    if (raw is! Map) return null;
    final model = Agent._safeLabel(raw['model']);
    if (model == null) return null;
    final machine = Agent._safeLabel(raw['machine']);
    return switch (raw['reason']) {
      'not_served' => GridNoteNotServed(model),
      'offline' when machine != null => GridNoteOffline(
        model,
        machine: machine,
      ),
      _ => null,
    };
  }
}

/// Every computer serving the agent's model seems offline.
final class GridNoteOffline extends GridNote {
  /// The computer, as the Machines list names it.
  final String machine;

  const GridNoteOffline(super.model, {required this.machine});
}

/// The latest list (an awake read, or the sleep record) no longer has the agent's model.
final class GridNoteNotServed extends GridNote {
  const GridNoteNotServed(super.model);
}

/// Which `grid` a machine would run, as its daemon reports beside the model list (`gridCli`).
///
/// `managed` is the runtime Harness itself carries and pins; `path` is one the person installed
/// (runnable, but not the pin); `missing` is nothing to run — the one value that changes what the
/// picker and the Local model dialog say, because an agent started on that machine would die on
/// its first `grid`. An older daemon sends no field, read as null: nothing is claimed either way.
enum GridCli {
  managed,
  path,
  missing;

  static GridCli? parse(Object? raw) => switch (raw) {
    'managed' => GridCli.managed,
    'path' => GridCli.path,
    'missing' => GridCli.missing,
    _ => null,
  };
}

/// What the daemon last learned about one grid, as it reports beside the section (`state`).
///
/// The daemon reads grids without waking them, so a section can describe a grid that is resting:
/// [asleep] keeps its last known models rather than blanking them, [unknown] is a read that failed
/// some other way (or none yet), and [waking] is reserved for a person asking it to start. An older
/// daemon sends no field, read as null: nothing is claimed either way, and the section draws as it
/// always did.
enum GridSectionState {
  awake,
  asleep,
  waking,
  unknown;

  static GridSectionState? parse(Object? raw) => switch (raw) {
    'awake' => GridSectionState.awake,
    'asleep' => GridSectionState.asleep,
    'waking' => GridSectionState.waking,
    'unknown' => GridSectionState.unknown,
    _ => null,
  };

  /// Asleep, or on its way up: a message sent now waits for it to start.
  bool get resting =>
      this == GridSectionState.asleep || this == GridSectionState.waking;
}

/// The picker's whole answer: which grid was asked, and what it offers.
///
/// One grid the machine is signed into, with what it serves. [own] marks the account's private
/// grid — the picker calls that one "Local"; a shared grid goes by its name.
class GridSection {
  final String name;
  final bool own;
  final List<GridModel> models;

  /// How the grid answered the daemon's last look — see [GridSectionState]. Null from an older
  /// daemon, which draws the section as it always was.
  final GridSectionState? state;

  /// When the grid was last seen awake, or null.
  final DateTime? seenAt;

  /// How old [models] is, in seconds, or null when nothing is known.
  final int? lastKnownAge;

  /// What came of the last explicit wake that showed no models — see [GridWakeOutcome]. Null
  /// otherwise, and always from a daemon that predates it.
  final GridWakeOutcome? wakeOutcome;

  const GridSection({
    required this.name,
    required this.own,
    required this.models,
    this.state,
    this.seenAt,
    this.lastKnownAge,
    this.wakeOutcome,
  });
}

/// `gridName` is null when the machine has no grid yet — told apart from "a grid with nothing on
/// it", because the two need different sentences in front of a person.
class GridModels {
  final String? gridName;
  final List<GridModel> models;

  /// Every grid the machine is signed into, own grid first, each with its live models — the
  /// picker's sections. Empty on an older daemon, which sends only [models] for the own grid; the
  /// picker then draws that one section as it always did.
  final List<GridSection> grids;

  /// The engines a Local model can be offered to at all, as the daemon on that machine names them
  /// (`localModelEngines`; the set of launch contracts in its `gridLaunch.ts`). Null when the
  /// daemon is older and sends no such list — read as "offer everything", the behaviour before.
  final Set<String>? localModelEngines;

  /// New-session model selections are understood by this daemon.
  final bool supportsModelLaunch;

  /// Which `grid` the machine would run — see [GridCli]. Null when the daemon is older and does
  /// not say, which claims nothing.
  final GridCli? gridCli;

  /// Did the machine ANSWER? False when the request failed — offline, timed out, or a daemon too
  /// old to know the call.
  ///
  /// Kept apart from `gridName == null` because the two mean opposite things to a person. "This
  /// account has no grid" is a fact worth acting on; "we could not ask" is not a fact about the
  /// account at all, and a UI that folds them together tells a signed-in user to sign in again.
  final bool reachable;

  const GridModels({
    required this.gridName,
    required this.models,
    this.grids = const [],
    this.localModelEngines,
    this.supportsModelLaunch = false,
    this.gridCli,
    this.reachable = true,
  });

  /// The daemon's `grid_models_list` reply — and the `grid_models_changed` push, which carries the
  /// same document — read defensively: the fields of an older or newer daemon are simply absent or
  /// ignored, never a failure. `reachable` is false only when the daemon answered with an `error`.
  factory GridModels.fromReply(Map<String, dynamic> reply) {
    List<GridModel> parseModels(Object? raw, {String? grid}) =>
        (raw is List ? raw : const <dynamic>[])
            .whereType<Map<String, dynamic>>()
            .map(
              (m) => GridModel(
                id: m['id'] is String ? m['id'] as String : '',
                node: m['node'] is String ? m['node'] as String : '',
                grid: grid,
                unavailable: GridModelUnavailable.fromWire(m['unavailable']),
              ),
            )
            .where((m) => m.id.isNotEmpty)
            .toList();
    final rawGrids = reply['grids'];
    final grids = (rawGrids is List ? rawGrids : const <dynamic>[])
        .whereType<Map<String, dynamic>>()
        .where((g) => g['name'] is String && (g['name'] as String).isNotEmpty)
        .map((g) {
          final name = g['name'] as String;
          final seen = g['seenAt'];
          final known = g['lastKnownAge'];
          return GridSection(
            name: name,
            own: g['own'] == true,
            models: parseModels(g['models'], grid: name),
            state: GridSectionState.parse(g['state']),
            seenAt: seen is String ? DateTime.tryParse(seen) : null,
            lastKnownAge: known is num && known.isFinite && known >= 0
                ? known.round()
                : null,
            wakeOutcome: GridWakeOutcome.parse(g['wakeOutcome']),
          );
        })
        .toList();
    final capable = reply['localModelEngines'];
    return GridModels(
      gridName: reply['gridName'] is String
          ? reply['gridName'] as String
          : null,
      models: parseModels(reply['models']),
      grids: grids,
      localModelEngines: capable is List
          ? capable.whereType<String>().map((e) => e.toLowerCase()).toSet()
          : null,
      gridCli: GridCli.parse(reply['gridCli']),
      supportsModelLaunch: reply['supportsModelLaunch'] == true,
      reachable: reply['error'] == null,
    );
  }

  /// The sections to draw: [grids] when the daemon sent them, else the own grid alone.
  List<GridSection> get sections => grids.isNotEmpty
      ? grids
      : [
          if (gridName != null)
            GridSection(name: gridName!, own: true, models: models),
        ];

  /// The machine could not be asked. Says nothing about the account, because nothing is known —
  /// including which engines it would have offered, or whether it has a `grid`.
  const GridModels.unreachable()
    : gridName = null,
      models = const [],
      grids = const [],
      localModelEngines = null,
      supportsModelLaunch = false,
      gridCli = null,
      reachable = false;

  /// Whether [engine] may be pointed at one of [models]: unknown engines are refused only when the
  /// daemon gave a list — a picker that guessed would refuse the wrong ones on an older daemon.
  bool canRunLocally(String? engine) {
    final capable = localModelEngines;
    if (capable == null) return true;
    final id = engine?.trim().toLowerCase();
    return id != null && capable.contains(id);
  }
}