@zgeoff/atc 2.12.0 → 2.13.0

package/src/agents/make-claude-headless-runner.ts

@@ -0,0 +1,46 @@
+import type { HeadlessRunEvents, HeadlessRunner } from './agent-adapter';
+import type { ClaudeHeadlessRunRequest } from './build-claude-query-options';
+
+/**
+ * Runs one headless turn through the Claude CLI; the daemon command supplies
+ * the Agent SDK implementation, and tests supply a recorder.
+ */
+export type ClaudeHeadlessRun = (
+  opts: ClaudeHeadlessRunRequest,
+  hooks: HeadlessRunEvents,
+) => { readonly stop: () => void };
+
+/**
+ * Where and how a Claude CLI headless turn runs: the binary, the permission
+ * mode its adapter resolved, the mod folder, and, for a gateway, the
+ * settings file that carries its backend. The folder and file are written
+ * on first use.
+ */
+interface ClaudeHeadlessTarget {
+  readonly claudeBin: string;
+  readonly permissionMode: string;
+  readonly pluginDir: () => string;
+  readonly settings?: () => string;
+}
+
+/**
+ * Turns the Claude CLI's headless run into the neutral runner the daemon
+ * calls. Every headless turn runs under the permission mode its adapter
+ * resolved for the agent's sessions.
+ */
+export function makeClaudeHeadlessRunner(
+  run: ClaudeHeadlessRun,
+  target: ClaudeHeadlessTarget,
+): HeadlessRunner {
+  return (opts, hooks) =>
+    run(
+      {
+        ...opts,
+        claudeBin: target.claudeBin,
+        permissionMode: target.permissionMode,
+        pluginDir: target.pluginDir(),
+        ...(target.settings === undefined ? {} : { settings: target.settings() }),
+      },
+      hooks,
+    );
+}

package/src/agents/plan-pasted-line-input.ts

@@ -0,0 +1,22 @@
+import type { TerminalInputModes } from './agent-adapter';
+
+const PASTE_START = '\u001B[200~';
+const PASTE_END = '\u001B[201~';
+
+/**
+ * Pastes a line into a TUI that tells a paste from typing, then submits it
+ * with a carriage return as its own write. Such a TUI takes a newline inside
+ * a burst of input as part of the text, so a line typed with its newline
+ * stays unsent in the composer. Between bracketed paste markers the whole
+ * text is one paste event, newlines included, and the carriage return after
+ * the closing marker is a separate Enter key event however the two writes
+ * arrive. Paste markers inside the text are dropped, so the text can neither
+ * end the paste early nor start one of its own. A TUI that has not turned
+ * bracketed paste on gets the text unmarked, and may still read both writes
+ * as one burst.
+ */
+export function planPastedLineInput(text: string, modes: TerminalInputModes): readonly string[] {
+  const unmarked = text.replaceAll(PASTE_START, '').replaceAll(PASTE_END, '');
+
+  return modes.bracketedPaste ? [`${PASTE_START}${unmarked}${PASTE_END}`, '\r'] : [unmarked, '\r'];
+}

package/src/agents/plan-typed-line-input.ts

@@ -0,0 +1,8 @@
+/**
+ * Types a line the way a terminal user does: the text and a newline in one
+ * write. A TUI that reads input a line at a time takes the newline as the
+ * submit key.
+ */
+export function planTypedLineInput(text: string): readonly string[] {
+  return [`${text}\n`];
+}

package/src/agents/resolve-claude-permission-mode.ts

@@ -0,0 +1,13 @@
+import { findClaudePermissionMode } from './find-claude-permission-mode';
+
+/**
+ * The permission mode a Claude CLI agent's headless turns run in: the mode
+ * its configuration sets, else auto, since no human is at a terminal to
+ * answer a prompt.
+ */
+export function resolveClaudePermissionMode(
+  args: readonly string[],
+  settings: Readonly<Record<string, unknown>> | undefined,
+): string {
+  return findClaudePermissionMode(args, settings) ?? 'auto';
+}

package/src/{daemon/start-headless-run.ts → agents/start-claude-headless-run.ts}

@@ -1,36 +1,8 @@
-import type { AgentSessionID } from '../shared/agent-session-id';
-import { socketPath } from '../shared/config';
+import { truncateSummary } from '../daemon/truncate-summary';
 import { isCompiledBinary } from '../shared/is-compiled-binary';
 import { isRecord } from '../shared/report';
-import type { SessionID } from '../shared/session-id';
-import { buildHeadlessEnv } from './build-headless-env';
-import { resolveHeadlessExecutable } from './resolve-headless-executable';
-import { truncateSummary } from './truncate-summary';
-
-const PERMISSION_MODES = [
-  'default',
-  'acceptEdits',
-  'bypassPermissions',
-  'plan',
-  'auto',
-  'dontAsk',
-] as const;
-
-// The effort levels the Agent SDK accepts.
-const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'] as const;
-
-interface HeadlessRunOptions {
-  readonly claudeBin: string;
-  readonly cwd: string;
-  readonly prompt: string;
-  readonly resume?: AgentSessionID;
-  readonly permissionMode?: string;
-  readonly settings?: string;
-  readonly sessionID?: SessionID;
-  readonly pluginDir?: string;
-  readonly model?: string;
-  readonly effort?: string;
-}
+import { buildClaudeQueryOptions } from './build-claude-query-options';
+import type { ClaudeHeadlessRunRequest } from './build-claude-query-options';
 
 interface HeadlessRunHooks {
   readonly onOutput: (text: string) => void;
@@ -48,16 +20,14 @@ interface HeadlessRunHandle {
  * done (with the turn's whole result) or needs_you (errors, turn limits,
  * anything a human must look at).
  */
-export function startHeadlessRun(
-  opts: HeadlessRunOptions,
+export function startClaudeHeadlessRun(
+  opts: ClaudeHeadlessRunRequest,
   hooks: HeadlessRunHooks,
 ): HeadlessRunHandle {
   const controller = new AbortController();
 
   void (async () => {
     try {
-      const mode = PERMISSION_MODES.find((m) => m === opts.permissionMode);
-      const effort = EFFORT_LEVELS.find((level) => level === opts.effort);
       let stderrTail = '';
 
       // The SDK is the heaviest module in the daemon's graph, and only a
@@ -68,28 +38,11 @@ export function startHeadlessRun(
       const stream = sdk.query({
         prompt: opts.prompt,
         options: {
-          cwd: opts.cwd,
-          env: buildHeadlessEnv({
-            socketPath,
-            ...(opts.pluginDir === undefined ? {} : { pluginDir: opts.pluginDir }),
-            ...(opts.sessionID === undefined ? {} : { sessionID: opts.sessionID }),
-          }),
+          ...buildClaudeQueryOptions(opts, isCompiledBinary()),
           abortController: controller,
           stderr: (data: string) => {
             stderrTail = `${stderrTail}${data}`.slice(-2000);
           },
-          ...(opts.resume === undefined ? {} : { resume: opts.resume }),
-          ...(mode === undefined ? {} : { permissionMode: mode }),
-
-          // The session's own model and effort, so the turn runs as its
-          // terminal did.
-          ...(opts.model === undefined ? {} : { model: opts.model }),
-          ...(effort === undefined ? {} : { effort }),
-
-          // The same generated file the terminal spawn passes, so the turn
-          // runs against the session's own backend and instrumentation.
-          ...(opts.settings === undefined ? {} : { extraArgs: { settings: opts.settings } }),
-          ...resolveHeadlessExecutable(opts.claudeBin, isCompiledBinary()),
         },
       });
 

package/src/agents/write-atc-bridge.ts

@@ -1,7 +1,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { stateDir } from '../shared/config';
-import { ATC_BRIDGE_FILES } from './atc-bridge-files';
+import { buildATCBridgeFiles } from './build-atc-bridge-files';
 import { buildCLIArgv } from './build-cli-argv';
 
 /**
@@ -13,7 +13,7 @@ import { buildCLIArgv } from './build-cli-argv';
  * there.
  */
 export function writeATCBridge(dir: string = join(stateDir, 'atc-bridge')): string {
-  const files = { ...ATC_BRIDGE_FILES, 'hooks/atc-cli.ts': renderATCCLIModule(buildCLIArgv()) };
+  const files = buildATCBridgeFiles(buildCLIArgv());
 
   for (const [path, content] of Object.entries(files)) {
     const file = join(dir, path);
@@ -29,10 +29,6 @@ export function writeATCBridge(dir: string = join(stateDir, 'atc-bridge')): stri
   return dir;
 }
 
-function renderATCCLIModule(argv: readonly string[]): string {
-  return `export const ATC_CLI: readonly string[] = ${JSON.stringify(argv)};\n`;
-}
-
 function tryReadFileText(file: string): string | null {
   try {
     return readFileSync(file, 'utf8');

package/src/cli.ts

@@ -159,15 +159,17 @@ const main = defineCommand({
           const grok = await import('./agents/grok-adapter');
           const codex = await import('./agents/codex-adapter');
           const gateway = await import('./agents/gateway-adapter');
-          const headless = await import('./daemon/start-headless-run');
+          const headless = await import('./agents/start-claude-headless-run');
           const targets = await import('./daemon/build-execution-targets');
 
           // Test harnesses shrink the outbound queue to force overflow
           // deterministically; unset means the production default.
           const queueBytes = Number(process.env['ATC_QUEUE_BYTES']);
           const cfg = config.loadConfig();
+          const built = targets.buildExecutionTargets(cfg.targets);
+          const targetErrors = [...cfg.targetErrors, ...built.errors];
 
-          for (const error of cfg.targetErrors) {
+          for (const error of targetErrors) {
             const line =
               error.scope === 'config'
                 ? `${error.path} cannot be used (${error.problem}: ${error.detail}); every spawn is refused, local ones included, until it is fixed`
@@ -192,18 +194,12 @@ const main = defineCommand({
           // to it is refused. Tests pin it to 0 to reach the refusal at once.
           const graceOverride = Number(process.env['ATC_TAP_GRACE_MS']);
 
-          const claudeAdapter = new claude.ClaudeAdapter(cfg, (runOpts, hooks) =>
-            headless.startHeadlessRun({ ...runOpts, claudeBin: cfg.claudeBin }, hooks),
-          );
-
+          const claudeAdapter = new claude.ClaudeAdapter(cfg, headless.startClaudeHeadlessRun);
           const grokAdapter = new grok.GrokAdapter(cfg);
           const codexAdapter = new codex.CodexAdapter(cfg);
 
           const gatewayAdapters = cfg.gateways.map(
-            (entry) =>
-              new gateway.GatewayAdapter(entry, cfg, (runOpts, hooks) =>
-                headless.startHeadlessRun({ ...runOpts, claudeBin: entry.bin }, hooks),
-              ),
+            (entry) => new gateway.GatewayAdapter(entry, cfg, headless.startClaudeHeadlessRun),
           );
 
           let handle: Awaited<ReturnType<typeof daemon.startDaemon>>;
@@ -220,9 +216,9 @@ const main = defineCommand({
               legacyFleetPath: config.legacyFleetFile,
               pidPath: config.daemonPidFile,
               hooks: cfg.hooks,
-              targets: targets.buildExecutionTargets(cfg.targets),
+              targets: built.targets,
               defaultTarget: cfg.defaultTarget,
-              targetErrors: cfg.targetErrors,
+              targetErrors,
               principals: cfg.principals,
               restoreBootTimeoutMs,
               ...(Number.isFinite(graceOverride) && graceOverride >= 0

package/src/client/index.ts

@@ -2,6 +2,7 @@ import { match } from 'ts-pattern';
 import { createActor } from 'xstate';
 import type { AgentID } from '../agents/agent-adapter';
 import { countSessionStates, sortGroupedSessionViews, sortSessionViews } from '../daemon/sessions';
+import { DaemonError } from '../protocol/daemon-error';
 import type { EventMsg } from '../protocol/protocol';
 import { loadConfig } from '../shared/config';
 import { makeSingleFlight } from '../shared/make-single-flight';
@@ -20,6 +21,10 @@ import { ansi, cols, drawHelp, drawHome, drawOverlay, drawPicker, drawStatusBar,
 let overlaySelected = 0;
 let confirmKill = false;
 
+// The session whose forget waits on a confirm because it destroys the
+// session's host, or null.
+let confirmDestroyID: string | null = null;
+
 // The client's mirror of the daemon's fleet, kept fresh by events.
 let fleet: MirrorSession[] = [];
 
@@ -95,6 +100,36 @@ async function sendQuiet(m: string, p?: Readonly<Record<string, unknown>>) {
   } catch {}
 }
 
+// A kill the daemon refuses because forgetting the session destroys its
+// host asks once more before the forget.
+async function sendKill(sessionID: string) {
+  try {
+    await client.sendRequest('session.kill', { session: sessionID });
+  } catch (error) {
+    if (error instanceof DaemonError && error.code === 'confirmation_required') {
+      confirmDestroyID = sessionID;
+
+      if (service.getSnapshot().value === 'overlay') {
+        renderOverlay();
+      }
+    }
+  }
+}
+
+// Takes the confirm token the daemon offers and hands it straight back:
+// the operator already confirmed in the overlay.
+async function sendForget(sessionID: string) {
+  try {
+    const offered = await client.sendRequest('session.forget', { session: sessionID });
+
+    const confirmToken = offered['confirmToken'];
+
+    if (typeof confirmToken === 'string') {
+      await client.sendRequest('session.forget', { session: sessionID, confirmToken });
+    }
+  } catch {}
+}
+
 async function attach(sessionID: string) {
   service.send({ type: 'ATTACH', sessionID });
 
@@ -215,6 +250,7 @@ function renderOverlay() {
     agentMarks,
     selected: overlaySelected,
     confirmKill,
+    confirmDestroy: confirmDestroyID !== null,
     filter: overlayFilter,
     stale: daemonStale && !daemonRestarting,
     grouped: overlayGrouped,
@@ -225,6 +261,7 @@ function renderOverlay() {
 
 function openOverlay() {
   confirmKill = false;
+  confirmDestroyID = null;
   overlayFilter = null;
 
   const focusedIndex = pickOverlaySessions().findIndex((s) => s.id === focusedID);
@@ -510,7 +547,7 @@ function applyOverlayKey(buf: Buffer) {
 
   if (confirmKill) {
     if (buf[0] === 0x79 /* y */ && sel !== undefined) {
-      void sendQuiet('session.kill', { session: sel.id });
+      void sendKill(sel.id);
     }
 
     confirmKill = false;
@@ -520,6 +557,18 @@ function applyOverlayKey(buf: Buffer) {
     return;
   }
 
+  if (confirmDestroyID !== null) {
+    if (buf[0] === 0x79 /* y */) {
+      void sendForget(confirmDestroyID);
+    }
+
+    confirmDestroyID = null;
+
+    renderOverlay();
+
+    return;
+  }
+
   if (applyOverlayFilterKey(buf)) {
     return;
   }

package/src/client/ui.ts

@@ -196,6 +196,10 @@ export interface OverlayView {
   agentMarks: Readonly<Record<AgentID, string>>;
   selected: number;
   confirmKill: boolean;
+
+  // A kill the daemon refused because forgetting the session destroys its
+  // host waits on a second confirm.
+  confirmDestroy: boolean;
   filter: string | null;
   stale: boolean;
   grouped: boolean;
@@ -271,6 +275,10 @@ export function drawOverlay(view: OverlayView) {
     hint = formatKillConfirm(selected, view.sessions);
   }
 
+  if (view.confirmDestroy) {
+    hint = 'forget destroys its host and everything on it? y / n';
+  }
+
   rowsList.push(dimRow(width, hint), boxBottom(width));
 
   drawBox(rowsList);

package/src/daemon/build-execution-targets.ts

@@ -1,4 +1,5 @@
-import type { TargetConfig } from '../shared/collect-targets';
+import type { TargetConfig, TargetConfigError } from '../shared/collect-targets';
+import { buildImpProvider } from './build-imp-provider';
 import { buildTargetIdentity } from './build-target-identity';
 import type { ExecutionProvider } from './execution-provider';
 import { LocalPTYProvider } from './local-pty-provider';
@@ -19,16 +20,54 @@ export interface ExecutionTarget {
   readonly provider: ExecutionProvider | null;
 }
 
+/**
+ * The targets the daemon serves, and the problems with their entries that
+ * only the daemon's environment shows.
+ */
+export interface ExecutionTargetsBuild {
+  readonly targets: ExecutionTarget[];
+  readonly errors: TargetConfigError[];
+}
+
 /**
  * Builds one target per configured entry, in config order, each with a
- * provider of its kind when this daemon has one.
+ * provider of its kind when this daemon has one. An entry whose provider
+ * cannot start from `env` keeps no provider and adds a target error.
  */
-export function buildExecutionTargets(configs: readonly TargetConfig[]): ExecutionTarget[] {
-  return configs.map((config) => ({
-    id: config.id,
-    kind: config.provider,
-    options: config.options,
-    identity: buildTargetIdentity(config.provider, config.options),
-    provider: config.provider === 'local-pty' ? new LocalPTYProvider() : null,
-  }));
+export function buildExecutionTargets(
+  configs: readonly TargetConfig[],
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): ExecutionTargetsBuild {
+  const errors: TargetConfigError[] = [];
+
+  const targets = configs.map((config) => {
+    const built = buildProvider(config, env);
+
+    if (built.problem !== null) {
+      errors.push({ scope: 'target', target: config.id, problem: built.problem });
+    }
+
+    return {
+      id: config.id,
+      kind: config.provider,
+      options: config.options,
+      identity: buildTargetIdentity(config.provider, config.options),
+      provider: built.provider,
+    };
+  });
+
+  return { targets, errors };
+}
+
+function buildProvider(
+  config: TargetConfig,
+  env: Readonly<Record<string, string | undefined>>,
+): Readonly<{ provider: ExecutionProvider | null; problem: string | null }> {
+  if (config.provider === 'local-pty') {
+    return { provider: new LocalPTYProvider(), problem: null };
+  }
+
+  return config.provider === 'imp'
+    ? buildImpProvider(config.id, config.options, env)
+    : { provider: null, problem: null };
 }

package/src/daemon/build-imp-provider.ts

@@ -0,0 +1,68 @@
+import { ImpClientPort } from './imp-client-port';
+import { ImpProvider } from './imp-provider';
+
+/**
+ * The provider of an `imp` target, or the problem that keeps it from one.
+ * A problem never includes the token or any other environment value.
+ */
+export interface ImpProviderBuild {
+  readonly provider: ImpProvider | null;
+  readonly problem: string | null;
+}
+
+/**
+ * The provider of target `id` from its `imp` options: `url` is where impd
+ * listens, and `tokenEnv` holds the name of the daemon's environment
+ * variable that carries the token, so no credential sits in the config.
+ * `image`, `memoryMib`, `guestDir`, and `guestATC` pass through. No
+ * provider when `url` is missing, so the target lists and refuses every
+ * spawn. A `tokenEnv` that is not a non-empty string, or whose variable is
+ * unset or empty in `env`, is a problem and leaves no provider; a target
+ * without `tokenEnv` calls impd with no token.
+ */
+export function buildImpProvider(
+  id: string,
+  options: Readonly<Record<string, unknown>>,
+  env: Readonly<Record<string, string | undefined>> = process.env,
+): ImpProviderBuild {
+  const url = options['url'];
+  const tokenEnv = options['tokenEnv'];
+
+  if (typeof url !== 'string' || url === '') {
+    return { provider: null, problem: null };
+  }
+
+  if (tokenEnv !== undefined && (typeof tokenEnv !== 'string' || tokenEnv === '')) {
+    return {
+      provider: null,
+      problem: `target ${JSON.stringify(id)} must give tokenEnv as a non-empty string`,
+    };
+  }
+
+  const token = tokenEnv === undefined ? null : env[tokenEnv];
+
+  if (token === undefined || token === '') {
+    return {
+      provider: null,
+      problem: `target ${JSON.stringify(id)} reads its impd token from ${String(tokenEnv)}, which is unset or empty in the daemon's environment`,
+    };
+  }
+
+  const provider = new ImpProvider(new ImpClientPort({ url, token }), {
+    ...pickString(options, 'image'),
+    ...pickString(options, 'guestDir'),
+    ...pickString(options, 'guestATC'),
+    ...(typeof options['memoryMib'] === 'number' ? { memoryMib: options['memoryMib'] } : {}),
+  });
+
+  return { provider, problem: null };
+}
+
+function pickString(
+  options: Readonly<Record<string, unknown>>,
+  key: 'image' | 'guestDir' | 'guestATC',
+): Partial<Record<typeof key, string>> {
+  const value = options[key];
+
+  return typeof value === 'string' && value !== '' ? { [key]: value } : {};
+}

package/src/daemon/build-report-trail-entry.ts

@@ -5,14 +5,15 @@ import type { TrailEntry } from '../store/trail-entry';
 import type { NoteReport } from './parse-report';
 
 /**
- * The trail entry for one note a session reported, carrying its label and a
- * preview of its text.
+ * The trail entry for one note a session reported, carrying its label, a
+ * preview of its text, and the id its reporter gave it, when it gave one.
  */
 export function buildReportTrailEntry(
   sessionID: SessionID,
   agentSessionID: AgentSessionID | undefined,
   report: Readonly<NoteReport>,
   reportedAt: number,
+  reportID?: string,
 ): TrailEntry {
   return {
     at: reportedAt,
@@ -21,5 +22,6 @@ export function buildReportTrailEntry(
     kind: 'report',
     label: report.label,
     detail: truncateDetail(report.text),
+    ...(reportID === undefined ? {} : { reportID }),
   };
 }

package/src/daemon/build-scoped-context.ts

@@ -187,8 +187,11 @@ export function buildScopedContext(
     },
     writeSessionInput: (sessionID, data) =>
       canSee(sessionID) ? ctx.writeSessionInput(sessionID, data) : 'missing',
+    writeSessionLine: (sessionID, text) =>
+      canSee(sessionID) ? ctx.writeSessionLine(sessionID, text) : 'missing',
     ejectSession: (id, prompt) => (canSee(id) ? ctx.ejectSession(id, prompt) : 'missing'),
-    adoptSession: (id, cols, rows) => (canSee(id) ? ctx.adoptSession(id, cols, rows) : 'missing'),
+    adoptSession: (id, cols, rows) =>
+      canSee(id) ? ctx.adoptSession(id, cols, rows) : Promise.resolve('missing' as const),
     resizeSession: (client, sessionID, dims) =>
       canSee(sessionID) && ctx.resizeSession(client, sessionID, dims),
     readSessionRecord: (id) =>

package/src/daemon/build-session-lifecycle.ts

@@ -0,0 +1,52 @@
+/**
+ * A session's lifecycle as four layers, each owned by one actor:
+ *
+ * - `desired`: what the operator asked for. `run` keeps the harness
+ *   running, `sleep` keeps its host asleep with the harness inside it, and
+ *   `stop` leaves the harness ended.
+ * - `vm`: the host the harness runs on. `none` is the daemon's own machine,
+ *   which has no lifecycle of its own; `awake`, `asleep`, and `unknown` are
+ *   the last state the daemon saw of a remote host.
+ * - `harness`: the agent process. `suspended` is a process kept inside a
+ *   sleeping host, which a revive brings back as it was.
+ * - `attachment`: the daemon's own connection to the harness's output.
+ *   `local` is a harness in the daemon's process tree; `attached`,
+ *   `reattaching`, and `detached` follow the connection to a remote one.
+ */
+export interface SessionLifecycle {
+  readonly desired: 'run' | 'sleep' | 'stop';
+  readonly vm: 'none' | 'awake' | 'asleep' | 'unknown';
+  readonly harness: 'running' | 'suspended' | 'exited';
+  readonly attachment: 'local' | 'attached' | 'reattaching' | 'detached';
+}
+
+// The session facts the layers derive from.
+interface LifecycleFacts {
+  readonly desired: SessionLifecycle['desired'];
+  readonly vm: SessionLifecycle['vm'];
+  readonly attachment: SessionLifecycle['attachment'];
+
+  // Whether the harness is kept inside a sleeping host.
+  readonly suspended: boolean;
+  readonly hasHarness: boolean;
+  readonly kind: 'pty' | 'headless';
+  readonly state: 'running' | 'needs_you' | 'done' | 'exited';
+}
+
+/**
+ * Builds the four layers from a session's facts. The harness runs while the
+ * session holds a terminal or a live headless run. A harness without one is
+ * suspended while it is kept inside a sleeping host, and exited otherwise.
+ */
+export function buildSessionLifecycle(facts: Readonly<LifecycleFacts>): SessionLifecycle {
+  const running = facts.hasHarness || (facts.kind === 'headless' && facts.state !== 'exited');
+  let harness: SessionLifecycle['harness'] = 'exited';
+
+  if (running) {
+    harness = 'running';
+  } else if (facts.suspended && facts.vm === 'asleep') {
+    harness = 'suspended';
+  }
+
+  return { desired: facts.desired, vm: facts.vm, harness, attachment: facts.attachment };
+}