@awebai/oats 0.22.8 → 0.22.9

package/bin/oats.mjs

@@ -31,7 +31,7 @@ import {
   resolveOatsConfig, resolveWorkMode, composeInstanceAgentsMd, parseYamlNested, assertSafeConfigValue, assertSafeConfigWriteKey, stripInternalAnnotations, withConfigFile, packagedInject, teamAgentRoots,
   findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, listCapabilityAgents, workspaceOf,
   ensureRoot, findRoot, findAgent, listAgents, listInstances, listAgentDefs, createAgent as coreCreateAgent,
-  spawnInstance, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, upsertLocalAgent, defaultRepo, RELATIONS,
+  spawnInstance, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upsertLocalAgent, defaultRepo, RELATIONS,
 } from "../lib/core.mjs";
 import {
   aggregateMissingRequirements, applyFromOasScope, beginRunJournal, discoverMigrationScopes, discoverOasScopes, discoverWorkspaceScopes, planFromOasScope,
@@ -39,7 +39,7 @@ import {
   assertNoSymlinkedParents, copyFileAtomic, writeFileAtomic,
   runRequirementInstall, selectConfigTemplate, validateConfigTemplate, writeAdoptedTemplate,
 } from "../lib/packages.mjs";
-import { attachArgv, checkRemote, forgetSnapshot, getServer, inspectRemote, listSnapshots, readServers, rosterGroups, routeCommand, targetOf, validateServer, writeServers, SERVERS_FILE } from "../lib/servers.mjs";
+import { attachArgv, checkRemote, forgetSnapshot, getServer, inspectRemote, startRemote, listSnapshots, readServers, rosterGroups, routeCommand, targetOf, validateServer, writeServers, SERVERS_FILE } from "../lib/servers.mjs";
 import { spawnSync as spawnSyncProc } from "node:child_process";
 
 const args = process.argv.slice(2);
@@ -2857,12 +2857,16 @@ async function sessionCmd() {
       return;
     }
     if (args[1] === "inspect") result = inspectInstanceSession(home);
-    else if (args[1] === "input") {
+    else if (args[1] === "start") {
+      const model = flag("model");
+      if (model === true) throw Object.assign(new Error("--model needs a model id; omit it to keep the recorded model"), { code: "E_BAD_ARGS" });
+      result = startInstanceSession(home, { model: model || undefined });
+    } else if (args[1] === "input") {
       const file = flag("text-file");
       if (file === true) throw Object.assign(new Error("--text-file needs a path"), { code: "E_BAD_ARGS" });
       if (!file && process.stdin.isTTY) throw Object.assign(new Error("provide --text-file or pipe input on stdin"), { code: "E_BAD_ARGS" });
       result = inputInstanceSession(home, readFileSync(file || 0, "utf8"));
-    } else throw Object.assign(new Error("usage: oats session inspect|input|attach --home /absolute/home [--text-file path] [--json]"), { code: "E_BAD_ARGS" });
+    } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start --home /absolute/home [--text-file path] [--model id] [--json]"), { code: "E_BAD_ARGS" });
     if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
   } catch (e) { cmdFail(e.code || "E_SESSION_FAILED", e.message); }
 }
@@ -3157,7 +3161,7 @@ function versionCmd() {
     // on it (an older CLI without the surface must fail closed with a
     // reason, not an argument error). `features`: kernel abilities a peer
     // must see before relying on them (retire-home: retire --home).
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "roster", "harvest"], features: ["retire-home"] }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, runtimes: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "roster", "harvest"], features: ["retire-home", "session-start"] }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3326,7 +3330,19 @@ function serverRouteCmd() {
       console.log(`${r.instance || r.home} on ${id}: ${r.present ? `present, ${r.state || "unknown"}` : "not present"}${r.backend ? ` (${r.backend})` : ""}`);
       return;
     }
-    if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect` and `session attach`; input runs on the execution host (the wake broker calls it there)");
+    if (args[1] === "start") {
+      const model = flag("model");
+      if (model === true) bail("E_BAD_ARGS", "--model needs a model id; omit it to keep the recorded model");
+      let out;
+      try { out = startRemote(id, { ...addr, model: model || undefined }); } catch (e) { bail(e.code || "E_SSH", e.message); }
+      if (out.stderr?.trim()) process.stderr.write(out.stderr.endsWith("\n") ? out.stderr : out.stderr + "\n");
+      if (JSON_MODE) { console.log(JSON.stringify(out.envelope, null, 2)); if (!out.envelope.ok) process.exit(1); return; }
+      if (!out.envelope.ok) die(`${id}: ${out.envelope.error?.message || "start failed"} (${out.envelope.error?.code || "E_REMOTE"})`);
+      const r = out.envelope.result;
+      console.log(`Started ${r.instance || r.home} on ${id} (${r.backend}${r.model ? `, model ${r.model}` : ""}, ${r.reused === "pane" ? "in its existing pane" : r.reused === "adopted" ? "adopted the pending session" : "new window"})`);
+      return;
+    }
+    if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect`, `session start` and `session attach`; input runs on the execution host (the wake broker calls it there)");
     let route;
     try { route = attachArgv(id, addr, { skipVersionCheck: args.includes("--print") }); }
     catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
@@ -3506,11 +3522,18 @@ Usage:
   oats session inspect|attach --server <id>  inspect (envelope) or attach a viewer (ssh PTY) for a
       --instance <name> | --home <abs>       remote instance over its saved route (--print shows
                                             attach); the server needs oats 0.22.2 or later
+  oats session start --server <id>           start a stopped remote instance in its existing home
+      --instance <name> | --home <abs>       over its saved route; the server must advertise
+      [--model <m>] [--json]                 session-start (oats 0.22.9 or later)
   oats create <name> [--local]               create an agent soul; --local = full
       [--description <d>] [--repo <r>]      soul under local-agents/ (uncommitted,
       [--work <mode>] [--runtime pi|claude|codex] gitignored; same memory + lifecycle)
       [--model <m>] [--yolo|--no-yolo] [--instructions-file <f>]
   oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
+  oats session start --home <absolute-home>  start a STOPPED instance again in its existing home
+      [--model <m>] [--json]                 (same identity, worktree, notes and launch env; no
+                                            spawn hooks); --model replaces the recorded model
+                                            for this and later starts; a live harness is refused
   oats spawn <agent> [--task <text>]         spawn an instance (tmux/Herdr; --no-launch
       [--purpose <slug>] [--repo <r>]       = scaffold only); --instructions-file/
       [--parent <instance>]                 --def-file creates a local agent;

package/docs/desktop-instance-start.md

@@ -0,0 +1,34 @@
+# Starting an existing instance
+
+An instance keeps its home, identity, work and notes when its harness stops.
+The Desktop roster is the place to return to it:
+
+- A running row opens its terminal.
+- A stopped row offers **Start…**. Clicking the row opens the same dialog.
+- The hierarchy's action popover offers **Start…** for a stopped instance.
+- An unknown status is shown as unknown, not as permission to launch another process.
+
+The Start dialog names the existing instance, runtime and host. Enter a model
+or leave the field blank to retain its recorded choice. Available local model
+suggestions are advisory; a model ID can also be typed. Start uses the saved
+briefing and state in a new harness conversation; it does not resume an old
+harness conversation ID. After the launch appears in the roster, Desktop
+opens the instance's terminal.
+
+If the instance is already running when the dialog checks, its action becomes
+**Open terminal**. A failed or timed-out start requires **Refresh status** before
+another attempt, because the launch may have succeeded before the reply was
+lost. Changing workspaces dismisses the dialog and prevents a delayed launch
+reply from opening a terminal in the wrong workspace.
+
+Desktop sends `POST /api/start/<instance>?ws=…&home=…` (and `server=…` for a
+remote instance). The backend resolves that exact roster identity and calls
+`oats session start --home <absolute-home> [--server <id>] [--model <model>] --json`.
+The installed CLI must advertise `session-start`; remote starting also needs
+the remote operation. The execution host checks the actual saved session
+before launch. Desktop does not scaffold a home or execute a launcher itself.
+
+Status collection reads each instance's recorded tmux socket and session,
+with one query per socket per collection. A launcher shell with a harness
+child remains running; a fallback shell or dead pane is stopped. Errors that
+prevent a reliable observation remain unknown. Herdr uses its saved target.

package/docs/execution-targets.md

@@ -117,8 +117,41 @@ oats session attach --home /absolute/instance
 oats session inspect --home /absolute/instance --json
 oats session input --home /absolute/instance --text-file /path/to/message --json
 printf '%s' 'Check your pending work.' | oats session input --home /absolute/instance --json
+oats session start --home /absolute/instance [--model <id>] --json
 ```
 
+`start` runs a STOPPED instance again in its existing home: same identity,
+worktree, notes and launch environment, no spawn hooks, no new home. It reuses
+the persisted launch command, on the recorded tmux session and socket or the
+recorded Herdr server, and records the new session target in the instance
+metadata and the independent lifecycle receipt (whose home and work
+fingerprints are untouched, so a later retire still preserves everything
+changed since the original spawn). `--model` replaces the recorded model for
+this and later starts by re-rendering the persisted command; a command shape
+OATS did not generate is refused rather than rewritten. A quarantined home or one whose self-retirement is in progress is refused (`E_INSTANCE_RETIRING`). A live harness is
+refused (`E_SESSION_RUNNING`); a fallback shell with no harness descendant
+and a dead pane restart in that exact pane, a missing window opens again, and
+a lost tmux server after a reboot is recreated on the recorded socket. A state
+that cannot be established refuses (`E_SESSION_UNKNOWN`). Every observation
+happens under a per-home guard, so two starts of one home serialize
+(`E_SESSION_START_BUSY`). Each launch retains `.oats-start-pending.json`
+with its target and unique id. The wrapper writes that id to
+`.oats-start-exited` only when the saved command returns. A shell without
+the matching exit marker is still starting and cannot be respawned by a
+second caller. This also covers shell-only harness initialization; it needs
+no background monitor. The next start reconciles the complete receipt before
+the ordinary metadata check: a
+target that is present is recorded and adopted; an exited target is reconciled
+before restarting, and an unobservable target or malformed receipt refuses
+and keeps the receipt. Recovery is idempotent for an already-recorded launch
+and never silently applies a new model to an
+already-running harness. A never-launched legacy Herdr home without a saved
+server endpoint requires that endpoint to be configured before it can start;
+it does not fall back to tmux.
+The start opens a new harness conversation on the instance's `TASK.md`; the
+instance resumes its work from its own `STATE.md`, as the knowledge protocol
+prescribes.
+
 `attach` is interactive and does not accept `--json`. It validates the saved
 endpoint on the execution host, then opens a Herdr terminal viewer or an
 isolated tmux session linked to that agent's window alone. Closing its terminal

package/docs/release-notes/v0.22.9.md

@@ -0,0 +1,100 @@
+# OATS v0.22.9
+
+A stopped instance can be started again in its existing home, from the CLI
+and from Desktop, with the model chosen at that moment; Desktop's running
+status and terminal attachment follow each instance's saved tmux socket.
+
+## Start a stopped instance in its existing home
+
+`oats session start --home <absolute-home> [--model <id>] [--json]` runs the
+instance's persisted launch command again in the same home: same identity,
+worktree, notes and launch environment, no spawn hooks, no new home. The
+command runs in the recorded tmux session on the recorded socket, or on the
+recorded Herdr server. A fallback shell with no harness descendant and a dead
+pane restart in that exact pane; a missing window opens again; a tmux server
+lost to a reboot is recreated on the recorded socket path. A live harness is
+refused (`E_SESSION_RUNNING`), a state that cannot be established is refused
+(`E_SESSION_UNKNOWN`, including permission failures, which are not treated as
+absence), and a quarantined home or one whose self-retirement is in progress
+is refused (`E_INSTANCE_RETIRING`). Nothing is started by any refusal.
+
+`--model` replaces the recorded model for this and later starts. The kernel
+re-renders the persisted command through a parser of the exact shapes spawn
+generates; an existing `--model` value is replaced in place, otherwise the
+pair is inserted after the harness binary, and every other token, including
+capability launch environment and arguments, is kept byte for byte. A command
+OATS did not generate, a duplicate or valueless `--model`, or a preference
+whose provider prefix is incompatible with the recorded runtime is refused
+rather than rewritten or silently defaulted. A runtime model id is passed
+through to the harness as given; the kernel does not validate it against a
+catalog. Omitting the model keeps the recorded one.
+
+The start opens a new harness conversation from the instance's saved briefing
+(`TASK.md`) and the instance resumes from its own `STATE.md`, as its
+knowledge protocol prescribes. It is not a native conversation resume.
+
+## Recovery and the duplicate guard
+
+Every observation a start makes happens under a per-home lock, so two starts
+of one home (a double click, two clients) serialize instead of both seeing
+"stopped" and allocating twice (`E_SESSION_START_BUSY`). The independent
+lifecycle receipt and the instance metadata are updated in that order, the
+receipt keeping its home and work fingerprints so a later retire still
+preserves everything changed since the original spawn.
+
+A per-launch receipt carrying a launch id and the actual target is written
+before the harness is launched (a Herdr start allocates its empty pane first)
+and is retained for the launch's lifetime, including after the metadata is
+recorded. The command wrapper writes a matching exit marker only when the
+saved command returns, so a start that observes only shells without that
+marker sees a launch still starting up, or a transient child such as the
+briefing being read, and refuses rather than mistaking it for a fallback
+shell; no background watcher or polling is involved. A start that launched
+but could not record its metadata leaves the receipt in place, and the next
+start reconciles it before the ordinary metadata check: a present target is
+recorded and adopted, an exited one is reconciled and restarted, and an
+unobservable target refuses and keeps the receipt. Recovery is idempotent
+through the launch id recorded in the metadata, so an attempt already
+recorded is not counted again. Every field of the receipt, the command, the
+model, the id, the timestamp and the target, is validated before any
+authority or metadata is touched; a malformed receipt refuses and is kept
+unchanged. A running adopted target never has a newly requested model applied
+silently; that start is refused and says so.
+
+## Desktop: start with model choice, and saved-socket status
+
+A stopped instance's sidebar row and hierarchy popover offer Start, which
+opens a same-home dialog showing the existing runtime, host and home, with an
+optional model (blank keeps the recorded one). The dialog re-checks status
+before submitting, converts a running instance to Open terminal, and blocks
+explicitly on an unknown state, an old CLI or a remote without a route. It
+calls only the kernel command above and waits for the roster to show the
+instance before opening its saved terminal target. When the launch returns
+but the harness is not observed running, the dialog says the instance may
+have exited and offers a status refresh before any retry, instead of
+assuming the roster is merely late.
+
+Status now reads each instance's saved tmux socket, session and window, and
+sees a harness running under its launcher shell; a dead pane or fallback
+shell is stopped and an observation error is unknown, never a guess. The
+terminal transport carries that saved socket end to end (preflight, viewer,
+PTY attachment, resource identity and cleanup), so two instances with the
+same window name on different sockets are distinct and input never lands in
+the wrong one. Viewer sessions left behind by a crash are reclaimed on the
+default server at startup and on each saved socket when a terminal is next
+opened there.
+
+## Remote hosts
+
+`oats session start --server <id> (--instance <name> | --home <abs>)
+[--model <id>]` routes over the saved route and runs the same command on the
+execution host. The kernel's version probe advertises `session-start` in its
+features and remote lists; the local side reads the server's version probe
+and refuses before the remote start, so nothing is mutated on a host whose
+kernel does not advertise it. A remote host needs this release installed
+there first.
+
+## Limitation
+
+A never-launched legacy Herdr home has no saved server endpoint; starting it
+refuses with that reason and does not fall back to tmux.

package/docs/servers.md

@@ -128,7 +128,10 @@ under another soul is observed only.
 
 - Routed: `spawn`, `retire`, `status`, `okf harvest`, and, against a 0.22.2
   or later server, `session inspect` (the execution host's envelope, relayed;
-  a Desktop preflight before attaching) and `session attach`. Session input
+  a Desktop preflight before attaching) and `session attach`; against a
+  server whose version probe advertises the `session-start` feature (0.22.9
+  or later), `session start` (the execution host starts the stopped instance
+  in its saved home; `--model` travels). Session input
   runs on the execution host, where the wake broker calls it. `server roster`
   is local (registrations and saved routes, one status pull per group). The
   version probe's `remote` list names this kernel's remote-side surface

package/lib/core.mjs

@@ -32,11 +32,11 @@ import {
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { homedir, tmpdir } from "node:os";
-import { createHash } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import { attachSessionTarget } from "./session-viewer.mjs";
 import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
-import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, validHerdrTarget } from "./herdr.mjs";
+import { ensureHerdr, allocateHerdr, launchHerdr, inspectHerdr, stopHerdr, validHerdrTarget, herdrSnapshot } from "./herdr.mjs";
 
 export const RESERVED = new Set(["bin", "local-agents", "tmp-agents"]);
 /** The work modes spawn accepts — also the enum a quarantine cleanup descriptor
@@ -6448,6 +6448,321 @@ export function inputInstanceSession(home, text) {
   catch (e) { throw oatsError("E_SESSION_INPUT_FAILED", `cannot submit session input: ${e.message}`); }
 }
 
+// ---------------------------------------------------------------- session start
+
+/** The exact prompt token spawn renders for claude and codex launches. */
+const LAUNCH_PROMPT_TOKEN = '"$(cat TASK.md)"';
+
+/** Tokenize a persisted OATS launch command. The grammar is exactly what
+ *  spawn renders: space-separated tokens that are env assignments NAME='v',
+ *  single-quoted words ('...' with '\'' escapes, i.e. shq output), bare words
+ *  with no shell metacharacters (flags and capability launch args), the bare
+ *  `--` separator, or the exact prompt token "$(cat TASK.md)". Anything else
+ *  is refused with its position: the command was not one OATS
+ *  generated, and rewriting it would be guessing. Re-rendering joins the
+ *  tokens' original text, so untouched tokens are byte-identical. */
+export function parseLaunchCommand(command) {
+  if (typeof command !== "string" || !command.trim() || command.includes("\0")) throw oatsError("E_LAUNCH_COMMAND_UNSUPPORTED", "instance has no valid persisted launch command to start from");
+  const bad = (at, why) => { throw oatsError("E_LAUNCH_COMMAND_UNSUPPORTED", `persisted launch command is not a shape this kernel re-renders (${why} at offset ${at}); inspect the saved command in instance.json before starting this home manually`); };
+  const tokens = [];
+  const n = command.length;
+  let i = 0;
+  while (i < n) {
+    if (command[i] === " ") { i++; continue; }
+    const start = i;
+    if (command.startsWith(LAUNCH_PROMPT_TOKEN, i)) {
+      i += LAUNCH_PROMPT_TOKEN.length;
+      if (i < n && command[i] !== " ") bad(start, "text glued to the prompt token");
+      tokens.push({ kind: "prompt", text: LAUNCH_PROMPT_TOKEN });
+      continue;
+    }
+    let envName;
+    const m = /^([A-Za-z_][A-Za-z0-9_]*)='/.exec(command.slice(i));
+    if (m) { envName = m[1]; i += envName.length + 1; }
+    if (command[i] === "'") {
+      i++;
+      let value = "";
+      for (;;) {
+        if (i >= n) bad(start, "unterminated single quote");
+        if (command[i] === "'") {
+          if (command.startsWith("'\\''", i)) { value += "'"; i += 4; continue; }
+          i++; break;
+        }
+        value += command[i++];
+      }
+      if (i < n && command[i] !== " ") bad(start, "text glued to a quoted token");
+      const text = command.slice(start, i);
+      tokens.push(envName ? { kind: "env", name: envName, value, text } : { kind: "word", value, quoted: true, text });
+      continue;
+    }
+    if (envName) bad(start, "unquoted env value");
+    while (i < n && command[i] !== " ") {
+      if (/[\s'"$`\\;|&<>(){}*?~#]/.test(command[i])) bad(start, "shell metacharacter outside quotes");
+      i++;
+    }
+    const word = command.slice(start, i);
+    tokens.push(word === "--" ? { kind: "sep", text: word } : { kind: "word", value: word, quoted: false, text: word });
+  }
+  let binary = -1;
+  for (let k = 0; k < tokens.length; k++) {
+    if (tokens[k].kind === "env") { if (binary >= 0) bad(0, "env assignment after the binary"); continue; }
+    if (binary < 0) { if (tokens[k].kind !== "word" || !tokens[k].quoted) bad(0, "no quoted binary after the env prefix"); binary = k; }
+  }
+  if (binary < 0) bad(0, "no binary");
+  let modelIndex = -1;
+  for (let k = binary + 1; k < tokens.length; k++) {
+    if (tokens[k].kind === "sep") break;
+    if (tokens[k].kind === "word" && !tokens[k].quoted && tokens[k].value === "--model") {
+      const v = tokens[k + 1];
+      if (!v || v.kind !== "word" || v.value.startsWith("-")) bad(0, "--model without a value");
+      if (modelIndex >= 0) bad(0, "duplicate --model options");
+      modelIndex = k + 1;
+      k++;
+    }
+  }
+  return { tokens, binary, modelIndex };
+}
+
+export function renderLaunchCommand(tokens) { return tokens.map((t) => t.text).join(" "); }
+
+/** The persisted command with `model` as its --model value: an existing
+ *  --model value is replaced; otherwise the pair is inserted right after the
+ *  binary, before any option that could be waiting for a value. Capability
+ *  env, flags, launch args and the prompt expression are untouched. */
+export function withLaunchModel(command, model) {
+  const { tokens, binary, modelIndex } = parseLaunchCommand(command);
+  const valueToken = { kind: "word", value: model, quoted: true, text: shq(model) };
+  if (modelIndex >= 0) tokens[modelIndex] = valueToken;
+  else tokens.splice(binary + 1, 0, { kind: "word", value: "--model", quoted: false, text: "--model" }, valueToken);
+  return renderLaunchCommand(tokens);
+}
+
+function tmuxOn(socket, args, io) {
+  return (io?.exec || execFileSync)("tmux", ["-u", "-S", socket, ...args], { encoding: "utf8", timeout: 10000, maxBuffer: 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+function writeJsonAtomic(path, value, mode) {
+  const tmp = `${path}.tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2) + "\n", mode !== undefined ? { mode } : undefined);
+  renameSync(tmp, path);
+}
+
+/** Start a stopped instance again in its existing home: no new home, no
+ *  spawn hooks, no identity work. The persisted launch command runs in the
+ *  recorded tmux session (on the recorded socket) or Herdr server, the
+ *  instance metadata and the independent retirement receipt get the new
+ *  session target (the receipt's home and work fingerprints are untouched,
+ *  so retire still preserves everything changed since the original spawn),
+ *  and the wake broker's session linkage follows through those receipts.
+ *
+ *  Every observation happens under a per-home lock (E_SESSION_START_BUSY for
+ *  a concurrent start), so two callers cannot both see "stopped" and
+ *  allocate twice. Refusals, before any mutation: unknown or unmanaged home,
+ *  a quarantined home or one whose self-retirement marker is present, a
+ *  receipt that disagrees with the metadata (the same rule retire and
+ *  session use), a session whose state cannot be
+ *  established, a live harness (E_SESSION_RUNNING), a model the recorded
+ *  runtime cannot use, and a command shape this kernel does not re-render.
+ *  A fallback shell with no harness descendant and a dead pane restart in
+ *  that exact pane; a missing window and a lost tmux server after a reboot
+ *  allocate again (the server on the same socket path).
+ *
+ *  Every start retains .oats-start-pending.json naming its target and id.
+ *  Its wrapper writes the matching .oats-start-exited marker on command
+ *  exit, so shells during startup cannot be mistaken for fallback prompts.
+ *  There is no background monitor. The next start
+ *  reconciles that receipt BEFORE the ordinary metadata/receipt equality
+ *  gate: a target that is present (or a retained dead pane) is recorded and
+ *  adopted, an exited target has its metadata reconciled before restarting,
+ *  and a target that cannot be observed refuses and keeps the receipt. */
+export function startInstanceSession(home, o = {}) {
+  if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session start needs an absolute instance home");
+  const realHome = realPathOrNearest(home);
+  const metaPath = join(realHome, "instance.json");
+  if (!existsSync(metaPath)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `${realHome} is not an OATS instance home (no instance.json); nothing was started`);
+  const lock = join(realHome, ".oats-start.lock");
+  const pendingPath = join(realHome, ".oats-start-pending.json");
+  const exitedPath = join(realHome, ".oats-start-exited");
+  const readMeta = () => { try { return JSON.parse(readFileSync(metaPath, "utf8")); } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${metaPath}: ${e.message}`); } };
+  const lostTmuxServer = (e) => /no server running on |(?:error connecting to|failed to connect to) .*(?:No such file or directory|Connection refused)/i.test(String(e.stderr ?? e.message ?? ""));
+  const launchFailure = (backend, error) => {
+    // execFileSync errors embed argv (including capability environment) in
+    // message; backend stderr can echo it too. Neither belongs in the API.
+    const reason = error.code === "ENOENT" ? "backend executable unavailable"
+      : error.code === "ETIMEDOUT" || error.signal === "SIGTERM" ? "backend command timed out" : "backend command failed";
+    return oatsError("E_SESSION_START_FAILED", `${backend} start of ${basename(realHome)} could not be confirmed (${reason}); inspect the recorded session before retrying. Launch evidence is retained in ${pendingPath}`);
+  };
+  // The independent receipt first (retire and session consult it), then the
+  // mutable metadata; both tmp+rename. A failure between them is what the
+  // pending receipt exists for.
+  const record = (meta, { id, backend, target, model, command, startedAt, reused }, clearPending = true) => {
+    const baselinePath = retirementBaselinePath(realHome);
+    let baseline;
+    try { baseline = JSON.parse(readFileSync(baselinePath, "utf8")); } catch (e) { throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or unreadable for ${realHome}: ${e.message}`); }
+    if (baseline.version !== RETIRE_BASELINE_VERSION || baseline.home !== realHome || !runtimeAuthorityOf(baseline)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is invalid for ${realHome}`);
+    baseline.runtime = backend === "herdr"
+      ? { launched: true, sessionTarget: target }
+      : { launched: true, tmux: { session: target.session, window: target.window, socket: resolve(target.socket) } };
+    writeJsonAtomic(baselinePath, baseline, 0o600);
+    if (o.io?.failBeforeMetadataWrite) throw new Error("injected metadata write failure");
+    const recorded = meta.startId === id;
+    const restarts = (Array.isArray(meta.restarts) ? meta.restarts : []).slice(recorded ? -20 : -19);
+    if (!recorded) restarts.push({ startedAt, model: model ?? null, reused });
+    const next = { ...meta, model, command, launched: true, startId: id, restarts, restartCount: (meta.restartCount || 0) + (recorded ? 0 : 1) };
+    if (backend === "herdr") { next.sessionTarget = target; delete next.tmux; }
+    else { next.tmux = { session: target.session, window: target.window, socket: resolve(target.socket) }; delete next.sessionTarget; }
+    writeJsonAtomic(metaPath, next);
+    if (clearPending) rmSync(pendingPath, { force: true });
+    return { instance: meta.instance, agent: meta.agent, home: realHome, runtime: meta.runtime, backend, model: model ?? null, target, startedAt, restartCount: next.restartCount, reused };
+  };
+  try { mkdirSync(lock); }
+  catch (e) {
+    if (e.code === "EEXIST") throw oatsError("E_SESSION_START_BUSY", `another start of ${basename(realHome)} is in progress (${lock}); if no start is running, remove that directory and retry`);
+    throw e;
+  }
+  try {
+    if (existsSync(join(realHome, ".oats-rollback-incomplete.json"))) throw oatsError("E_INSTANCE_RETIRING", `${realHome} is a quarantined home whose cleanup is incomplete; finish its retirement (oats retire) before starting anything there`);
+    // A self-retirement leaves this marker while its detached teardown runs:
+    // the home is about to disappear, so nothing is relaunched into it.
+    if (existsSync(retirePendingMarkerPath(realHome))) throw oatsError("E_INSTANCE_RETIRING", `${basename(realHome)} is being retired (${retirePendingMarkerPath(realHome)} is present); nothing was started`);
+    // 1. Reconcile a pending receipt before the equality gate: it may be the
+    //    only record of a session an earlier start allocated.
+    if (existsSync(pendingPath)) {
+      let pending;
+      try { pending = JSON.parse(readFileSync(pendingPath, "utf8")); } catch { pending = undefined; }
+      const pt = pending?.target;
+      const validTarget = pt?.backend === "herdr" ? validHerdrTarget(pt)
+        : pt?.backend === "tmux" && [pt.session, pt.window, pt.socket].every((v) => typeof v === "string" && v.length > 0) && isAbsolute(pt.socket);
+      let validCommand = false;
+      try { parseLaunchCommand(pending?.command); validCommand = true; } catch { /* preserve invalid receipt below */ }
+      const validReceipt = validTarget && validCommand
+        && typeof pending.id === "string" && /^[a-zA-Z0-9-]{1,80}$/.test(pending.id)
+        && (pending.model === null || (typeof pending.model === "string" && !!pending.model.trim() && !pending.model.includes("\0")))
+        && typeof pending.startedAt === "string" && Number.isFinite(Date.parse(pending.startedAt));
+      if (!validReceipt) throw oatsError("E_SESSION_UNKNOWN", `an earlier start left an unreadable or invalid receipt at ${pendingPath}; inspect it before retrying; nothing was started`);
+      const pbackend = pending.target.backend === "herdr" ? "herdr" : "tmux";
+      let st;
+      try { st = inspectSessionTarget(pending.target, o.io); }
+      catch (e) {
+        if (pbackend === "tmux" && lostTmuxServer(e)) st = { present: false, state: "stopped" };
+        else throw oatsError("E_SESSION_UNKNOWN", `an earlier start of ${basename(realHome)} recorded a session (${pbackend === "herdr" ? `Herdr pane ${pending.target.paneId}` : `tmux ${pending.target.session}:${pending.target.window} on ${pending.target.socket}`}) that cannot be observed now: ${String(e.stderr ?? e.message ?? "").trim() || e.message}; the receipt ${pendingPath} is kept and nothing was started`);
+      }
+      // A launch may still consist entirely of shells (startup files, a
+      // shell-script harness). Only its own completion marker proves this
+      // is a fallback shell. Never respawn an accepted launch in that gap.
+      if (st.present && st.state === "shell") {
+        const exited = existsSync(exitedPath) && readFileSync(exitedPath, "utf8").trim() === pending.id;
+        if (!exited) throw oatsError("E_SESSION_START_BUSY", `${basename(realHome)} is still starting; refresh its status before retrying`);
+      }
+      // Reconcile even an exited target: the independent baseline may
+      // already name it while metadata still names the old allocation.
+      const meta = readMeta();
+      const done = record(meta, { ...pending, backend: pbackend, model: pending.model ?? undefined, reused: "adopted" }, !st.present || st.state === "shell");
+      if (st.present && st.state !== "shell") {
+        if (o.model != null && String(o.model).trim() && resolveModelPreference(String(o.model), meta.runtime) !== done.model) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running with its previously requested model; its target was recovered, but the new model was not applied`);
+        if (meta.startId === pending.id) throw oatsError("E_SESSION_RUNNING", `${meta.instance} is already running; nothing was started`);
+        return done;
+      }
+    }
+    // 2. The ordinary gate and observation, all under the lock.
+    const receipt = instanceSessionTarget(realHome);
+    const meta = readMeta();
+    const runtime = meta.runtime;
+    if (!["pi", "claude", "codex"].includes(runtime)) throw oatsError("E_LAUNCH_COMMAND_UNSUPPORTED", `instance ${meta.instance || realHome} records runtime ${JSON.stringify(runtime)}, which this kernel cannot relaunch`);
+    const backend = meta.sessionTarget || meta.backend === "herdr" ? "herdr" : "tmux";
+    let command = meta.command;
+    let model = meta.model || undefined;
+    if (o.model !== undefined && o.model !== null && String(o.model).trim() !== "") {
+      const resolved = resolveModelPreference(String(o.model), runtime);
+      if (!resolved) throw oatsError("E_MODEL_UNKNOWN", `model preference ${JSON.stringify(o.model)} has no entry usable by runtime ${runtime}; give a ${runtime} model id`);
+      command = withLaunchModel(command, resolved);
+      model = resolved;
+    } else parseLaunchCommand(command);
+    let target = receipt.target;
+    let state = { present: false, state: "not-launched" };
+    let serverGone = false;
+    if (target) {
+      try { state = inspectSessionTarget(target, o.io); }
+      catch (e) {
+        if (backend === "tmux" && lostTmuxServer(e)) { serverGone = true; state = { present: false, state: "stopped" }; }
+        else throw oatsError("E_SESSION_UNKNOWN", `cannot establish whether ${meta.instance} is running, so nothing was started: ${String(e.stderr ?? e.message ?? "").trim() || e.message}`);
+      }
+    }
+    if (state.present && state.state !== "shell") throw oatsError("E_SESSION_RUNNING", `${meta.instance} is running (${state.state}); nothing was started`);
+    const startedAt = new Date().toISOString();
+    const id = randomUUID();
+    const completedCommand = `${command}; oats_start_status=$?; printf '%s\\n' ${shq(id)} > ${shq(exitedPath)}`;
+    let reused = "new";
+    if (backend === "herdr") {
+      if (!target) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `this never-launched Herdr home has no saved server endpoint; no tmux fallback was started`);
+      if (state.present) { reused = "pane"; }
+      else {
+        const base = { backend: "herdr", binary: target.binary, socket: target.socket, protocol: target.protocol };
+        try { herdrSnapshot(base, o.io); }
+        catch (e) { throw oatsError("E_SESSION_UNKNOWN", `Herdr server on ${base.socket} is not reachable, so nothing was started: ${e.message}`); }
+        target = allocateHerdr(base, { home: realHome, instance: meta.instance }, o.io);
+      }
+      writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt }, 0o600);
+      try { launchHerdr(target, `cd ${shq(realHome)} && ${completedCommand}; exit "$oats_start_status"`, o.io); }
+      catch (e) { throw launchFailure("Herdr", e); }
+    } else {
+      const session = target?.session || meta.tmux?.session || DEFAULT_TMUX_SESSION;
+      const window = target?.window || meta.tmux?.window || meta.instance;
+      let socket = target?.socket || meta.tmux?.socket;
+      const windowCmd = `${completedCommand}; exec "\${SHELL:-/bin/zsh}"`;
+      // A fallback shell (no harness descendant) or a retained dead pane is
+      // the agent's own pane: the command runs there, no other window touched.
+      const inPlace = state.paneId && (state.present || state.state === "stopped");
+      if (inPlace) {
+        writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt }, 0o600);
+        try { tmuxOn(socket, ["respawn-pane", "-k", "-t", state.paneId, "-c", realHome, windowCmd], o.io); }
+        catch (e) { throw launchFailure("tmux", e); }
+        reused = "pane";
+      } else {
+        const instancesRoot = dirname(realHome);
+        const hq = existsSync(dirname(dirname(instancesRoot))) ? dirname(dirname(instancesRoot)) : realHome;
+        if (!socket) {
+          // Never launched (--no-launch): the default server, as spawn uses.
+          if (!tmuxAlive(session)) {
+            sh(`tmux new-session -d -s ${shq(session)} -n hq -c ${shq(hq)}`);
+            shTry(`tmux set-option -t ${shq(session)} -g window-size latest`);
+            shTry(`tmux set-option -t ${shq(session)} -g aggressive-resize on`);
+          }
+          socket = tmuxSocket(session);
+        } else if (serverGone) {
+          // The recorded server is gone (a reboot): the same socket path again.
+          mkdirSync(dirname(socket), { recursive: true });
+          tmuxOn(socket, ["new-session", "-d", "-s", session, "-n", "hq", "-c", hq], o.io);
+          tmuxOn(socket, ["set-option", "-t", session, "-g", "window-size", "latest"], o.io);
+          tmuxOn(socket, ["set-option", "-t", session, "-g", "aggressive-resize", "on"], o.io);
+        }
+        let names = [];
+        try { names = tmuxOn(socket, ["list-windows", "-t", `=${session}`, "-F", "#{window_name}"], o.io).split("\n").filter(Boolean); }
+        catch (e) {
+          if (!/can't find session/i.test(String(e.stderr ?? e.message ?? "")) && !lostTmuxServer(e)) throw oatsError("E_SESSION_UNKNOWN", `cannot list tmux windows on ${socket}: ${String(e.stderr ?? e.message ?? "").trim()}`);
+          tmuxOn(socket, ["new-session", "-d", "-s", session, "-n", "hq", "-c", hq], o.io);
+        }
+        if (names.includes(window)) throw oatsError("E_SESSION_RUNNING", `tmux window ${session}:${window} appeared on ${socket} during the start; nothing was started`);
+        target = { backend: "tmux", session, window, socket: resolve(socket) };
+        writeJsonAtomic(pendingPath, { id, target, command, model: model ?? null, startedAt }, 0o600);
+        try { tmuxOn(socket, ["new-window", "-t", `=${session}:`, "-n", window, "-c", realHome, windowCmd], o.io); }
+        catch (e) { throw launchFailure("tmux", e); }
+      }
+      target = { backend: "tmux", session, window, socket: resolve(socket) };
+    }
+    // Keep launch evidence until the command exits or the target disappears.
+    // A transient child (for example cat TASK.md) is not proof that startup
+    // has finished. A later start reconciles the receipt without a watcher.
+    try { return record(meta, { id, backend, target, model, command, startedAt, reused }, false); }
+    catch (e) {
+      if (e.code && String(e.code).startsWith("E_")) throw e;
+      throw oatsError("E_SESSION_START_INCOMPLETE", `${meta.instance} was started (${backend === "herdr" ? `Herdr pane ${target.paneId}` : `tmux ${target.session}:${target.window} on ${target.socket}`}) but its metadata could not be recorded: ${e.message}; the actual target is kept in ${pendingPath} and the next start adopts it instead of allocating another`);
+    }
+  } finally {
+    rmSync(lock, { recursive: true, force: true });
+  }
+}
+
 function inspectRetirementWork(home, work, isWorktree, { branchDeletion } = {}) {
   const classes = [];
   let baseline;

package/lib/servers.mjs

@@ -614,6 +614,24 @@ export function inspectRemote(serverId, { instance, home } = {}, io = {}) {
   return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId, instance: instance || route.snapshot?.instance, home: route.home } } : envelope, stderr, route };
 }
 
+/** The kernel version whose probe first advertises the `session-start`
+ *  feature; the probe's features list is the actual check. */
+export const SESSION_START_REMOTE_VERSION = "0.22.9";
+
+/** `session start` on the execution host for a remote instance: the same
+ *  route resolution as inspect, refused before any mutation when the remote
+ *  kernel does not advertise session-start, the envelope relayed as is. */
+export function startRemote(serverId, { instance, home, model } = {}, io = {}) {
+  const route = resolveRoute(serverId, { instance, home }, "session start");
+  const remote = requireSessionRemote(route.target, io);
+  if (!remote.features.includes("session-start")) {
+    throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${route.target.sshHost} does not advertise session-start (kernels from ${SESSION_START_REMOTE_VERSION} do); upgrade it there, or start the instance on that host`);
+  }
+  const args = ["session", "start", "--home", route.home, ...(model ? ["--model", String(model)] : []), "--json"];
+  const { envelope, stderr } = runRemote(route.target, args, io);
+  return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId, instance: instance || route.snapshot?.instance || envelope.result.instance } } : envelope, stderr, route };
+}
+
 export function attachArgv(serverId, { instance, home } = {}, io = {}) {
   const { target, home: remoteHome } = resolveRoute(serverId, { instance, home }, "session attach");
   if (!io.skipVersionCheck) requireSessionRemote(target, io);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.22.8",
+  "version": "0.22.9",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",