harnery 0.31.6 → 0.32.0

package/src/commands/agents.ts

@@ -30,6 +30,12 @@ import type { Command } from "commander";
 import type { EmitContext, HarneryProgramContext } from "../commander.ts";
 import { coordBinPath } from "../core/agents/coord-bin.ts";
 import { readStreamTailBounded } from "../core/agents/events/consume.ts";
+import {
+  checkGitFinalization,
+  formatGitFinalizationFailure,
+  type GitFinalizationResult,
+  readSessionWriteClaims,
+} from "../core/agents/finalization.ts";
 import {
   emitCanonical,
   type Heartbeat,
@@ -40,6 +46,7 @@ import {
   resolveOwnerBySessionEnv,
   resolveOwnerWithSource,
 } from "../core/agents/index.ts";
+import { buildSuggestedName } from "../core/agents/state/heartbeat-writer.ts";
 import { coordFreshnessSeconds, resolveBinName } from "../core/config.ts";
 import { type RemoteMachine, readRemoteMachines } from "../core/presence/index.ts";
 import { registerContextCommand } from "./context.ts";
@@ -221,13 +228,17 @@ export function registerAgentsCommand(
     .command("status")
     .description("End-of-turn status box (name + session age + files held + peer count)")
     .option("--json", "JSON output instead of the box")
+    .option(
+      "--end-turn",
+      "Treat this as the turn's closing status: issue the box only when this session's held paths are committed and their repositories are pushed",
+    )
     .option(
       "--session-id <id>",
       "Lookup heartbeat by session_id directly, bypassing the ppid walk. " +
         "Use this when calling from a hook (the hook's process tree may not lead back to Claude Code's session pid). " +
         "The Stop hook payload includes session_id; pass it through.",
     )
-    .action((opts: { json?: boolean; sessionId?: string }) => {
+    .action((opts: { endTurn?: boolean; json?: boolean; sessionId?: string }) => {
       runStatus(opts);
     });
 
@@ -343,7 +354,7 @@ export function registerAgentsCommand(
     )
     .option(
       "--timeout <dur>",
-      "Give up after this duration; suffix s/m/h/d (e.g. 30s, 5m, 1h). Bare integer = minutes. Default 60m.",
+      "Give up after this duration; suffix s/m/h/d is required (e.g. 30s, 5m, 1h). Default 60m.",
       "60m",
     )
     .option("--poll-secs <n>", "Poll interval in seconds (default 5)", "5")
@@ -381,8 +392,8 @@ export function registerAgentsCommand(
   cmd
     .command("health")
     .description(
-      "One-screen coord-layer health rollup: heal events, schema validity, " +
-        "commit-guard activity, council activity, anomalies. Designed for " +
+      "One-screen coord-layer health rollup: heal events, council activity, " +
+        "zombie detection, and anomalies. Designed for " +
         "daily glance + dashboard ingestion. Reads .harnery/.",
     )
     .option("--since <window>", "Window (Nh | Nd). Default: 24h.", "24h")
@@ -397,7 +408,7 @@ export function registerAgentsCommand(
       "Adapter wiring probe: ppid chain, comm names, pid-map anchor, sample payload paths. " +
         "With --replay-samples, also replays every checked-in sample payload against the live " +
         "adapter in an isolated sandbox to catch adapter / payload-shape drift. " +
-        "Complements heal-events (drift telemetry). Id: claude_code | cursor.",
+        "Complements heal-events (drift telemetry). Id: claude-code | cursor.",
     )
     .option("--json", "JSON envelope output")
     .option(
@@ -552,12 +563,23 @@ function registerIdentityCommands(parent: Command): void {
       "--session-id <id>",
       "Bind the heartbeat with this session_id directly, bypassing the ppid walk.",
     )
-    .action((target: string, opts: { json?: boolean; sessionId?: string }) => {
-      runIdentityAssume(target, opts);
-    });
+    .option(
+      "--force-ancestor",
+      "Allow assuming a persona this session's fork lineage descends from " +
+        "(default: refused, because a fork's inherited transcript asserting that " +
+        "name is not a role handoff).",
+    )
+    .action(
+      (target: string, opts: { json?: boolean; sessionId?: string; forceAncestor?: boolean }) => {
+        runIdentityAssume(target, opts);
+      },
+    );
 }
 
-function runIdentityAssume(target: string, opts: { json?: boolean; sessionId?: string }): void {
+function runIdentityAssume(
+  target: string,
+  opts: { json?: boolean; sessionId?: string; forceAncestor?: boolean },
+): void {
   if (opts.json) emit.config({ format: "json" });
   const root = monorepoRoot();
   if (!root) {
@@ -578,7 +600,9 @@ function runIdentityAssume(target: string, opts: { json?: boolean; sessionId?: s
     process.exit(1);
   }
   try {
-    const result = assumeIdentity(root, owner, target);
+    const result = assumeIdentity(root, owner, target, {
+      forceAncestor: opts.forceAncestor ?? false,
+    });
     emit.data({
       ...result,
       display_name: displayAgentName(result.name),
@@ -879,7 +903,7 @@ function runWhoami(opts: { json?: boolean }): void {
     task: hb.task ?? null,
     turn_summary: hb.turn_summary ?? null,
     turn_summary_updated_at: hb.turn_summary_updated_at ?? null,
-    platform: hb.platform ?? "claude_code",
+    platform: hb.platform ?? "claude-code",
   };
 
   emit.data({ ...row, resolution_source: resolved.source, note: SUBAGENT_NOTE });
@@ -977,7 +1001,7 @@ function runList(opts: { all?: boolean; stale?: boolean; json?: boolean }): void
         task: h.task ?? null,
         turn_summary: h.turn_summary ?? null,
         turn_summary_updated_at: h.turn_summary_updated_at ?? null,
-        platform: h.platform ?? "claude_code",
+        platform: h.platform ?? "claude-code",
       });
       continue;
     }
@@ -1002,7 +1026,7 @@ function runList(opts: { all?: boolean; stale?: boolean; json?: boolean }): void
       task: h.task ?? null,
       turn_summary: h.turn_summary ?? null,
       turn_summary_updated_at: h.turn_summary_updated_at ?? null,
-      platform: h.platform ?? "claude_code",
+      platform: h.platform ?? "claude-code",
     });
   }
 
@@ -1030,7 +1054,7 @@ function runList(opts: { all?: boolean; stale?: boolean; json?: boolean }): void
         task: a.task ?? null,
         turn_summary: a.turn_summary ?? null,
         turn_summary_updated_at: null,
-        platform: a.platform ?? "claude_code",
+        platform: a.platform ?? "claude-code",
         machine: rm.machine,
       });
     }
@@ -1495,15 +1519,13 @@ function runSetTask(task: string, opts?: { sessionId?: string }): void {
     process.exit(1);
   }
 
-  // Snapshot BEFORE the mutation: a heartbeat that has never carried a task
-  // has no `task_updated_at` stamp (setTask always stamps it, even on a clear),
-  // so its absence is the "focus never declared this session" signal — i.e. the
-  // first set-task of the session. That's the natural moment to also hand the
-  // operator a session name built from the same declaration (one source of
-  // truth: the focus you declare names the session). Distinct from task===""
-  // (a deliberate clear), which carries a stamp and does NOT re-trigger.
+  // Snapshot BEFORE the mutation: the writer stamps `suggested_session_name`
+  // on the session's first NON-EMPTY declaration (one source of truth: the
+  // focus you declare names the session). A bare clear never consumes the
+  // naming window, and subagent/workflow kinds are never named — see
+  // heartbeat-writer.setTask. This call is the naming call exactly when the
+  // stamp appears across the mutation.
   const priorHb = readHeartbeat(myOwner);
-  const firstOfSession = !priorHb?.task_updated_at;
 
   // Heartbeat mutation goes through agent-coord (atomic temp+rename).
   const helper = agentCoordOrExit(root);
@@ -1520,46 +1542,47 @@ function runSetTask(task: string, opts?: { sessionId?: string }): void {
   }
 
   const hb = readHeartbeat(myOwner);
+
+  // The naming call: the mutation just stamped `suggested_session_name` for
+  // the first time. `first_of_session: true` means exactly "this call produced
+  // the session name" — it is never true with a null name (an empty first
+  // declaration or a `--session-id` relay both keep the window open instead).
+  const suggestedName =
+    !priorHb?.suggested_session_name && hb?.suggested_session_name
+      ? hb.suggested_session_name
+      : null;
+  const firstOfSession = suggestedName !== null;
+
   emitCanonical({
     type: "state.task_set",
     owner: myOwner,
     session: hb?.session_id ?? myOwner,
     adapter: normalizeAdapter(hb?.platform),
-    data: { task, cleared: !task || task.length === 0 },
+    data: {
+      task,
+      cleared: !task || task.length === 0,
+      first_of_session: firstOfSession,
+      suggested_session_name: suggestedName,
+    },
   });
 
-  // On the first focus declaration of a session, surface a suggested session
-  // name for the operator to set as their adapter tab title. Read the result
-  // (`suggested_session_name`) and reproduce it in a fenced code block so the
-  // UI's Copy button hands over the exact string. null on every later call.
-  const built =
-    firstOfSession && !opts?.sessionId ? buildSuggestedName(hb?.name ?? "unknown", [task]) : null;
-
   emit.data({
     instance_id: myOwner,
     name: hb?.name ?? null,
     task: hb?.task ?? null,
     cleared: !task || task.length === 0,
     first_of_session: firstOfSession,
-    suggested_session_name: built?.suggestedName ?? null,
+    suggested_session_name: suggestedName,
+    // Right-time instruction: the UserPromptSubmit nudge fires before the name
+    // exists; this result is the moment the model holds the string.
+    ...(suggestedName
+      ? {
+          note: "Reproduce suggested_session_name verbatim, by itself, in a fenced code block at the top of your reply — the operator copies it as the session/tab title.",
+        }
+      : {}),
   });
 }
 
-/**
- * Build the copy-pasteable session name from the coord identity + the agent's
- * description parts. Pure (no coord-state reads) so it's unit-testable; collapses
- * internal whitespace and trims. Returns null when the description is empty.
- */
-export function buildSuggestedName(
-  agentName: string,
-  descriptionParts: string[],
-): { suggestedName: string; description: string } | null {
-  const description = descriptionParts.join(" ").replace(/\s+/g, " ").trim();
-  if (!description) return null;
-  const name = agentName?.trim() || "unknown";
-  return { suggestedName: `Agent ${name} - ${description}`, description };
-}
-
 function runSuggestName(
   descriptionParts: string[],
   opts: { json?: boolean; sessionId?: string },
@@ -1624,7 +1647,7 @@ function runSuggestName(
   process.stdout.write(`${suggestedName}\n`); // lint-ok-emission: chat-paste path
 }
 
-function runStatus(opts: { json?: boolean; sessionId?: string }): void {
+function runStatus(opts: { endTurn?: boolean; json?: boolean; sessionId?: string }): void {
   const root = monorepoRoot();
   if (!root) {
     emit.error({
@@ -1656,20 +1679,23 @@ function runStatus(opts: { json?: boolean; sessionId?: string }): void {
     process.exit(1);
   }
 
-  // Stamp .last_status_at = NOW. The verdict path reads state.status_checked
-  // canonical events (emitted below), but the legacy heartbeat field is still
-  // populated for back-compat with consumers reading v1 directly. The stamp
-  // goes through agent-coord (atomic write).
-  try {
-    const helper = agentCoordOrExit(root);
-    spawnSync(helper, ["stamp-status-call", myOwner], {
-      encoding: "utf8",
-      timeout: 2000,
-      ...coordHelperOpts(root),
+  let finalization: GitFinalizationResult | null = null;
+  if (opts.endTurn) {
+    const history = readSessionWriteClaims(root, hb.instance_id, hb.session_id ?? myOwner);
+    const touchedPaths = [...new Set([...(hb.files_touched ?? []), ...history.paths])];
+    finalization = checkGitFinalization(root, touchedPaths, {
+      claimHistoryComplete: history.complete,
     });
-  } catch {
-    /* non-fatal */
+    if (!finalization.ok) {
+      emit.error({
+        code: "git_not_finalized",
+        message: formatGitFinalizationFailure(finalization, resolveBinName(root)),
+      });
+      process.exitCode = 1;
+      return;
+    }
   }
+
   emitCanonical({
     type: "state.status_checked",
     owner: myOwner,
@@ -1677,6 +1703,7 @@ function runStatus(opts: { json?: boolean; sessionId?: string }): void {
     adapter: normalizeAdapter(hb.platform),
     data: {
       format: opts.json ? "json" : "box",
+      git_finalization_checked: opts.endTurn === true,
       agent_count: 0, // computed below, not yet available here; Phase 5 verdict reads owner-scope only
       included_self: true,
     },
@@ -1784,6 +1811,7 @@ function runStatus(opts: { json?: boolean; sessionId?: string }): void {
     context_window: ctxUsage?.window ?? null,
     timestamp_iso: new Date().toISOString(),
     timestamp_local: timeStr,
+    ...(finalization ? { finalization } : {}),
   };
 
   if (opts.json) {
@@ -2154,13 +2182,12 @@ function readCanonicalEventsInWindow(root: string, cutoffMs: number): CanonicalE
   return out;
 }
 
-/** adapter ("claude-code") → legacy platform label ("claude_code") so the
- * existing formatPlatformLabel rendering keeps working unchanged. */
+/** Normalize adapter event data into the heartbeat platform value. */
 function adapterToPlatform(adapter: string | undefined): string {
-  if (adapter === "claude-code") return "claude_code";
+  if (adapter === "claude-code") return "claude-code";
   if (adapter === "cursor") return "cursor";
   if (adapter === "codex") return "codex";
-  return "claude_code";
+  return "claude-code";
 }
 
 /** Project a canonical health.* event into the HealEvent shape the aggregators
@@ -2387,14 +2414,6 @@ interface HealthReport {
     by_platform: Record<string, number>;
     top_agents: Array<{ agent: string; count: number }>;
   };
-  schema_invalid: { count: number; samples: string[] };
-  commit_guards: {
-    blocked: number;
-    bypassed: number;
-    suppressed: number;
-    edit_blocked: number;
-    shell_candidates: number;
-  };
   councils: {
     active: number;
     archived_in_window: number;
@@ -2736,18 +2755,7 @@ function runHealth(opts: { since: string; json?: boolean }): void {
 
   // Coordination telemetry reads from the canonical events.ndjson stream.
   // Heals come from health.*; council window-activity from council.*. The
-  // commit-guard + schema-invalid counters below have NO canonical equivalent
-  // yet. Their future home is the decision.* events (defined in schema.ts, not
-  // yet wired). Until then they report 0 (fields kept for output-shape
-  // compatibility).
   const heal: HealEvent[] = [];
-  const schemaInvalid = 0;
-  const schemaSamples: string[] = [];
-  const commitBlocked = 0;
-  const commitBypassed = 0;
-  const commitSuppressed = 0;
-  const editBlocked = 0;
-  const shellCandidates = 0;
   let councilAdvanced = 0;
   let councilClosed = 0;
   let councilArchived = 0;
@@ -2865,12 +2873,6 @@ function runHealth(opts: { since: string; json?: boolean }): void {
 
   // Anomaly detection.
   const anomalies: string[] = [];
-  if (schemaInvalid > 0) {
-    const sampleList = schemaSamples.slice(0, 3).join(", ");
-    anomalies.push(
-      `HEARTBEAT_SCHEMA_INVALID fired ${schemaInvalid}x; heartbeat shape failed validation${sampleList ? ` (samples: ${sampleList})` : ""}`,
-    );
-  }
   for (const { agent, count } of healTopAgents) {
     if (count >= 5) {
       anomalies.push(
@@ -2937,14 +2939,6 @@ function runHealth(opts: { since: string; json?: boolean }): void {
       by_platform: healByPlatform,
       top_agents: healTopAgents,
     },
-    schema_invalid: { count: schemaInvalid, samples: schemaSamples },
-    commit_guards: {
-      blocked: commitBlocked,
-      bypassed: commitBypassed,
-      suppressed: commitSuppressed,
-      edit_blocked: editBlocked,
-      shell_candidates: shellCandidates,
-    },
     councils: {
       active: activeCouncils,
       archived_in_window: councilArchived,
@@ -2988,17 +2982,6 @@ function renderHealthBox(report: HealthReport): void {
   const topHealer = report.heal_events.top_agents[0];
   const topHealerStr = topHealer ? `${topHealer.agent} x${topHealer.count}` : "(none)";
 
-  const guardParts: string[] = [];
-  if (report.commit_guards.blocked > 0) guardParts.push(`blocked ${report.commit_guards.blocked}`);
-  if (report.commit_guards.bypassed > 0)
-    guardParts.push(`bypassed ${report.commit_guards.bypassed}`);
-  if (report.commit_guards.suppressed > 0)
-    guardParts.push(`suppressed ${report.commit_guards.suppressed}`);
-  if (report.commit_guards.edit_blocked > 0)
-    guardParts.push(`edit-blocked ${report.commit_guards.edit_blocked}`);
-  if (report.commit_guards.shell_candidates > 0)
-    guardParts.push(`shell ${report.commit_guards.shell_candidates}`);
-
   const councilParts: string[] = [`${report.councils.active} active`];
   if (report.councils.advanced_in_window > 0)
     councilParts.push(`${report.councils.advanced_in_window} advanced`);
@@ -3035,8 +3018,6 @@ function renderHealthBox(report: HealthReport): void {
         ? "0"
         : `${report.zombies.count} (${report.zombies.samples.join(", ")})`,
     ],
-    ["schema invalid", String(report.schema_invalid.count)],
-    ["commit guards", guardParts.length ? guardParts.join(", ") : "0"],
     ["councils", councilParts.join(", ")],
     ["anomalies", report.anomalies.length === 0 ? "(clean)" : `${report.anomalies.length} flagged`],
   ];
@@ -3070,10 +3051,10 @@ function runAdapterProbe(
   if (opts.json) emit.config({ format: "json" });
 
   const adapter = id.trim();
-  if (adapter !== "claude_code" && adapter !== "cursor") {
+  if (adapter !== "claude-code" && adapter !== "cursor") {
     emit.error({
       code: "bad_adapter",
-      message: "adapter id must be claude_code or cursor",
+      message: "adapter id must be claude-code or cursor",
     });
     process.exit(1);
   }
@@ -3293,7 +3274,7 @@ function replayAdapterSamples(
     stopFailure: "stop-failure",
     StopFailure: "stop-failure",
   };
-  const adapterFlag = adapter === "claude_code" ? "claude-code" : adapter;
+  const adapterFlag = adapter;
 
   const sandbox = mkdtempSync(join(tmpdir(), "harn-adapter-probe-"));
   const results: SampleReplayResult[] = [];
@@ -3430,13 +3411,13 @@ function collectPath(value: string, prev: string[]): string[] {
   return [...prev, value];
 }
 
-/** Parse "30", "30s", "5m", "1h", "2d" → ms. Bare integer defaults to minutes (back-compat). */
+/** Parse "30s", "5m", "1h", "2d" into milliseconds. */
 function parseDurationToMs(input: string): number | null {
-  const match = input.trim().match(/^(\d+)([smhd]?)$/i);
+  const match = input.trim().match(/^(\d+)([smhd])$/i);
   if (!match) return null;
   const n = Number.parseInt(match[1], 10);
   if (!Number.isFinite(n) || n <= 0) return null;
-  const unit = (match[2] || "m").toLowerCase();
+  const unit = match[2].toLowerCase();
   const mult: Record<string, number> = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
   return n * mult[unit];
 }

package/src/commands/browse-session.ts

@@ -0,0 +1,245 @@
+import type { Readable } from "node:stream";
+import type { Command } from "commander";
+import type { EmitContext } from "../commander.ts";
+import type { BrowserSessionLocator } from "../lib/browser/client.ts";
+import {
+  BROWSER_SESSION_MAX_FILL_BYTES,
+  BrowserSessionError,
+  sendBrowserSessionRequest,
+} from "../lib/browser/session-control.ts";
+
+interface ControlFileOpts {
+  controlFile: string;
+}
+
+interface LocatorOpts extends ControlFileOpts {
+  selector?: string;
+  role?: string;
+  name?: string;
+  label?: string;
+  text?: string;
+  partial?: boolean;
+}
+
+export function registerBrowseSessionCommand(program: Command, emit: EmitContext): void {
+  const session = program
+    .command("browse-session")
+    .description("Control an opted-in headed browse session through an owner-only descriptor");
+
+  session
+    .command("status")
+    .requiredOption("--control-file <path>", "Owner-only session descriptor")
+    .action((opts: ControlFileOpts) => runAction(emit, opts.controlFile, "status", {}));
+
+  addLocatorOptions(
+    session
+      .command("inspect")
+      .description("Inspect sanitized text, controls, focus, and active-tab state")
+      .requiredOption("--control-file <path>", "Owner-only session descriptor"),
+  ).action((opts: LocatorOpts) => {
+    const locator = parseLocatorOptions(opts, false);
+    return runAction(emit, opts.controlFile, "inspect", locator ? { locator } : {});
+  });
+
+  session
+    .command("screenshot")
+    .requiredOption("--control-file <path>", "Owner-only session descriptor")
+    .requiredOption("--out <path>", "New PNG path in an existing directory")
+    .action((opts: ControlFileOpts & { out: string }) =>
+      runAction(emit, opts.controlFile, "screenshot", { out: opts.out }),
+    );
+
+  session
+    .command("tabs")
+    .requiredOption("--control-file <path>", "Owner-only session descriptor")
+    .action((opts: ControlFileOpts) => runAction(emit, opts.controlFile, "tabs", {}));
+
+  session
+    .command("select-tab")
+    .requiredOption("--control-file <path>", "Owner-only session descriptor")
+    .requiredOption("--index <n>", "Stable session-local tab index", parseIndex)
+    .action((opts: ControlFileOpts & { index: number }) =>
+      runAction(emit, opts.controlFile, "select_tab", { index: opts.index }),
+    );
+
+  session
+    .command("open-tab <url>")
+    .requiredOption("--control-file <path>", "Owner-only session descriptor")
+    .action((url: string, opts: ControlFileOpts) =>
+      runAction(emit, opts.controlFile, "open_tab", { url }),
+    );
+
+  session
+    .command("close-tab")
+    .requiredOption("--control-file <path>", "Owner-only session descriptor")
+    .requiredOption("--index <n>", "Stable session-local tab index", parseIndex)
+    .action((opts: ControlFileOpts & { index: number }) =>
+      runAction(emit, opts.controlFile, "close_tab", { index: opts.index }),
+    );
+
+  session
+    .command("goto <url>")
+    .requiredOption("--control-file <path>", "Owner-only session descriptor")
+    .action((url: string, opts: ControlFileOpts) =>
+      runAction(emit, opts.controlFile, "goto", { url }),
+    );
+
+  session
+    .command("reload")
+    .requiredOption("--control-file <path>", "Owner-only session descriptor")
+    .action((opts: ControlFileOpts) => runAction(emit, opts.controlFile, "reload", {}));
+
+  addLocatorOptions(
+    session
+      .command("click")
+      .requiredOption("--control-file <path>", "Owner-only session descriptor"),
+  ).action((opts: LocatorOpts) =>
+    runAction(emit, opts.controlFile, "click", { locator: parseLocatorOptions(opts, true) }),
+  );
+
+  addLocatorOptions(
+    session
+      .command("fill")
+      .description("Fill one strict locator with a value read once from standard input")
+      .requiredOption("--control-file <path>", "Owner-only session descriptor"),
+  ).action(async (opts: LocatorOpts) => {
+    const value = await readFillValue(process.stdin);
+    return runAction(emit, opts.controlFile, "fill", {
+      locator: parseLocatorOptions(opts, true),
+      value,
+    });
+  });
+
+  session
+    .command("press <key>")
+    .requiredOption("--control-file <path>", "Owner-only session descriptor")
+    .action((key: string, opts: ControlFileOpts) =>
+      runAction(emit, opts.controlFile, "press", { key }),
+    );
+
+  addLocatorOptions(
+    session
+      .command("wait")
+      .requiredOption("--control-file <path>", "Owner-only session descriptor"),
+  ).action((opts: LocatorOpts) =>
+    runAction(emit, opts.controlFile, "wait", { locator: parseLocatorOptions(opts, true) }),
+  );
+
+  session
+    .command("close")
+    .requiredOption("--control-file <path>", "Owner-only session descriptor")
+    .action((opts: ControlFileOpts) => runAction(emit, opts.controlFile, "close", {}));
+}
+
+function addLocatorOptions(command: Command): Command {
+  return command
+    .option("--selector <css>", "CSS locator")
+    .option("--role <role>", "Accessible role locator")
+    .option("--name <name>", "Accessible name used with --role")
+    .option("--label <text>", "Associated label locator")
+    .option("--text <text>", "Visible text locator")
+    .option("--partial", "Allow partial accessible-name, label, or text matching");
+}
+
+export function parseLocatorOptions(opts: LocatorOpts, required: true): BrowserSessionLocator;
+export function parseLocatorOptions(
+  opts: LocatorOpts,
+  required: false,
+): BrowserSessionLocator | undefined;
+export function parseLocatorOptions(
+  opts: LocatorOpts,
+  required: boolean,
+): BrowserSessionLocator | undefined {
+  const forms = [opts.selector, opts.role, opts.label, opts.text].filter(
+    (value): value is string => value !== undefined,
+  );
+  if (forms.length === 0) {
+    if (!required) {
+      if (opts.name !== undefined || opts.partial) {
+        throw new BrowserSessionError(
+          "invalid_locator",
+          "--name and --partial require a locator form.",
+        );
+      }
+      return undefined;
+    }
+    throw new BrowserSessionError(
+      "invalid_locator",
+      "Choose exactly one locator: --selector, --role, --label, or --text.",
+    );
+  }
+  if (forms.length !== 1) {
+    throw new BrowserSessionError(
+      "invalid_locator",
+      "Choose exactly one locator: --selector, --role, --label, or --text.",
+    );
+  }
+  if (opts.name !== undefined && opts.role === undefined) {
+    throw new BrowserSessionError("invalid_locator", "--name is valid only with --role.");
+  }
+  if (opts.selector !== undefined) {
+    if (opts.partial) {
+      throw new BrowserSessionError("invalid_locator", "--partial is not valid with --selector.");
+    }
+    return { kind: "selector", value: opts.selector, partial: false };
+  }
+  if (opts.role !== undefined) {
+    return {
+      kind: "role",
+      value: opts.role,
+      ...(opts.name === undefined ? {} : { name: opts.name }),
+      partial: Boolean(opts.partial),
+    };
+  }
+  if (opts.label !== undefined) {
+    return { kind: "label", value: opts.label, partial: Boolean(opts.partial) };
+  }
+  return { kind: "text", value: opts.text!, partial: Boolean(opts.partial) };
+}
+
+export async function readFillValue(input: Readable): Promise<string> {
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of input) {
+    const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+    size += bytes.length;
+    if (size > BROWSER_SESSION_MAX_FILL_BYTES) {
+      throw new BrowserSessionError("fill_too_large", "Fill input exceeds the 64 KiB limit.");
+    }
+    chunks.push(bytes);
+  }
+  const value = Buffer.concat(chunks)
+    .toString("utf8")
+    .replace(/\r?\n$/, "");
+  if (value.length === 0) {
+    throw new BrowserSessionError("fill_empty", "Fill input from standard input was empty.");
+  }
+  return value;
+}
+
+async function runAction(
+  emit: EmitContext,
+  controlFile: string,
+  action: Parameters<typeof sendBrowserSessionRequest>[1],
+  args: Record<string, unknown>,
+): Promise<void> {
+  try {
+    emit.data(await sendBrowserSessionRequest(controlFile, action, args));
+  } catch (error) {
+    if (error instanceof BrowserSessionError) {
+      emit.error({ code: error.code, message: error.message });
+      emit.setExitCode(1);
+      return;
+    }
+    emit.error({ code: "browser_session_failed", message: "Browser session command failed." });
+    emit.setExitCode(1);
+  }
+}
+
+function parseIndex(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) {
+    throw new BrowserSessionError("invalid_index", "Tab index must be a non-negative integer.");
+  }
+  return parsed;
+}