@awebai/oats 0.22.7 → 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/capabilities/oats-okf/bin/oats-okf.mjs

@@ -27,9 +27,12 @@ import { existsSync, mkdirSync, mkdtempSync, writeFileSync, readFileSync, readdi
 import { join, isAbsolute, dirname } from "node:path";
 import { tmpdir } from "node:os";
 import { execFile, spawnSync } from "node:child_process";
+import { reclaimHarvestBranch } from "../lib/harvest-branch.mjs";
 
 const out = (o) => { process.stdout.write(JSON.stringify(o) + "\n"); process.exit(0); };
 const warn = (m) => out({ warning: `oats-okf: ${String(m).slice(0, 300)}` });
+// A reported failure must not exit 0: callers and hooks read the status.
+const warnFail = (m) => { process.stdout.write(JSON.stringify({ warning: `oats-okf: ${String(m).slice(0, 300)}` }) + "\n"); process.exit(1); };
 
 // Desktop CLI API v1: `oats okf harvest --json` emits EXACTLY ONE envelope
 // object on stdout — {schemaVersion:1,ok,result|error} — and a nonzero exit
@@ -38,6 +41,12 @@ const JSON_MODE = process.argv.includes("--json");
 const jsonOk = (result) => { process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: true, result }) + "\n"); process.exit(0); };
 const jsonFail = (code, message) => { process.stdout.write(JSON.stringify({ schemaVersion: 1, ok: false, error: { code, message: String(message).slice(0, 300) } }) + "\n"); process.exit(1); };
 
+// --help/-h never runs a command here either (the kernel answers it from the
+// manifest since 0.22.6; this keeps an older kernel from spawning a harvester).
+if (process.argv.slice(2).some((a) => a === "--help" || a === "-h")) {
+  process.stdout.write("oats okf harvest [--json] [--from-record] [--force]  promote this instance's pending notes (and record windows) into its soul by spawning a memory-harvest worker; --help never spawns\noats okf status [--json]\n");
+  process.exit(0);
+}
 const event = process.env.OATS_EVENT || process.argv[2];
 const instance = process.env.OATS_INSTANCE;
 const home = process.env.OATS_HOME || process.cwd();
@@ -421,6 +430,10 @@ _(the single next action — keep this current; a fresh session on any model res
       const soulRepo = gitRootOf(realSoul);
       if (!soulRepo) skip("workspace-mode soul is not inside a git repo — nowhere to deliver a PR");
       const relSoul = realSoul.slice(soulRepo.length + 1);
+      // A leftover memory-harvest/<slug> branch from a merged promotion is
+      // deleted first; an unmerged one refuses the harvest with the remedy.
+      const reclaimed = reclaimHarvestBranch(soulRepo, `memory-harvest/${slug}`);
+      if (reclaimed.action === "deleted") process.stderr.write(`oats-okf: deleted stale harvest branch memory-harvest/${slug} (merged into ${reclaimed.base})\n`);
       const task = `Harvest the pending notes of live WORKSPACE-MODE instance "${inst}" (agent "${agName}") into its soul — delivered as a PR.\n\n- Source notes: ${notes.length ? `${notesDir} (${notes.join(", ")})` : "none pending"}\n- Your ./work is a dedicated worktree of the soul's home repo (${soulRepo}), branch memory-harvest/${slug}.\n- Soul knowledge bundle to update: ./work/${join(relSoul, "knowledge")}\n- Soul skills dir (for procedure-shaped notes): ./work/${join(relSoul, "skills")}\n- Follow your memory-harvest skill: promote/merge/drop each note, knowledge vs skill routing, index + log discipline, validate the bundle, DELETE processed notes from the source notes/ dir, and commit once (prefixed "memory-harvest:") if anything changed.${recordBrief(recordPlan, packageRuntimeCli())}\n- If you changed anything: push the branch and open a PR (\`git push -u origin memory-harvest/${slug}\` then \`gh pr create --fill\`). Do NOT merge it; the humans/owners of ${soulRepo} review soul changes. If gh is unavailable, push the branch and report the compare URL. A harvest that promoted nothing has nothing to commit, push or open; that is a completed harvest, not a failed one.\n- Finally run \`oats retire ${harvName} --self\` (keep the branch: --self only).`;
       r = await spawnHarvester(harvestSpawnArgs({
         slug, parent: inst, repo: soulRepo, work: "worktree",
@@ -458,7 +471,7 @@ _(the single next action — keep this current; a fresh session on any model res
     out({ meta: { harvestSpawn: r.instance, window: r.tmux?.window }, ...warnings });
   } catch (e) {
     if (JSON_MODE) jsonFail(e.code || "E_HARVEST_FAILED", `harvest spawn failed (notes are safe on disk): ${e.message || e}`);
-    warn(`harvest spawn failed (notes are safe on disk): ${e.message || e}`);
+    warnFail(`harvest spawn failed (notes are safe on disk): ${e.message || e}`);
   }
 } else if (event === "retire") {
   // Retirement is intentionally a no-op for knowledge (for now): promotion happens

package/capabilities/oats-okf/lib/harvest-branch.mjs

@@ -0,0 +1,43 @@
+// A workspace-mode harvest delivers its promotion as a PR from a branch named
+// memory-harvest/<slug> in the soul's repository. After that PR merges, the
+// local branch may still exist and the next harvest's spawn would refuse it.
+// A branch fully merged into the base is stale and is deleted before the
+// spawn; an unmerged one is the previous harvester's unfinished work and the
+// harvest refuses with the exact remedy instead of touching it.
+import { execFileSync } from "node:child_process";
+
+/** Single-quote shell escaping for the operator remedy: the repo path may hold spaces or shell metacharacters. */
+export function shellQuote(s) { return "'" + String(s).replace(/'/g, "'\\''") + "'"; }
+
+function git(repo, args) {
+  return execFileSync("git", ["-C", repo, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+/** The repository's base branch: origin/HEAD's target when known, else main, else master. */
+export function baseBranchOf(repo) {
+  try { const ref = git(repo, ["symbolic-ref", "--quiet", "refs/remotes/origin/HEAD"]); if (ref) return ref.replace(/^refs\/remotes\//, ""); } catch { /* no origin/HEAD */ }
+  for (const b of ["origin/main", "main", "origin/master", "master"]) {
+    try { git(repo, ["rev-parse", "--verify", "--quiet", b]); return b; } catch { /* next */ }
+  }
+  return undefined;
+}
+
+/** Returns { action: "absent" | "deleted", base } or throws E_HARVEST_BRANCH_EXISTS. */
+export function reclaimHarvestBranch(repo, branch) {
+  try { git(repo, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`]); }
+  catch { return { action: "absent" }; }
+  const base = baseBranchOf(repo);
+  let merged = false;
+  if (base) { try { git(repo, ["merge-base", "--is-ancestor", branch, base]); merged = true; } catch { merged = false; } }
+  if (!merged) {
+    const err = new Error(`branch ${branch} already exists in ${repo} and is not merged into ${base || "any base branch"}: a previous harvest's promotion is unfinished — review and merge or delete it (git -C ${shellQuote(repo)} branch -D ${shellQuote(branch)}) before harvesting again`);
+    err.code = "E_HARVEST_BRANCH_EXISTS";
+    throw err;
+  }
+  // -D, not -d: the merge check above is against the BASE (origin/main when
+  // present). `branch -d` re-checks against the branch's upstream or the
+  // current HEAD instead, so with the soul's local main behind origin/main a
+  // branch fully merged upstream would still be refused as "not fully merged".
+  git(repo, ["branch", "-D", branch]);
+  return { action: "deleted", base };
+}

package/capabilities/oats-okf/oats.json

@@ -1,15 +1,21 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "1.5.1",
-  "compatibility": { "oats": ">=0.22.3" },
+  "version": "1.5.2",
+  "compatibility": {
+    "oats": ">=0.22.3"
+  },
   "layer": "knowledge",
   "description": "Knowledge layer via OKF: soul bundles, instance memory (STATE.md/log.md/notes/), continuous post-commit harvest into the soul (commit, PR, or direct-edit for local souls), craft + memory skills, validator.",
   "requires": [],
   "settings": {
     "harvest-runtime": {
       "default": "pi",
-      "values": ["pi", "claude", "codex"],
+      "values": [
+        "pi",
+        "claude",
+        "codex"
+      ],
       "description": "Harness for the memory harvester, independent of the source instance's runtime."
     },
     "harvest-model": {

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/integrations.md

@@ -167,6 +167,14 @@ start a second harvester while the first one's home exists. The check uses the
 existing prepared watermark file and does not treat a successful spawn as
 completed learning.
 
+## oats.okf 1.5.2
+
+`okf harvest` exits non-zero when it reports a failure (the plain and the
+`--json` forms alike). A leftover `memory-harvest/<slug>` branch from a merged
+promotion is deleted before the next workspace-mode harvest; an unmerged one
+refuses the harvest and names the remedy. `oats okf harvest --help` prints
+usage and never spawns.
+
 ## oats.aweb late joins (1.10.3)
 
 `aw team join` at spawn gets 120 s (a slow link is slow, not broken). If the

package/docs/operating-team-migration.md

@@ -33,24 +33,30 @@ Every remembering role must have a tested learning path. Preserve each role's
 explicit policy: Cjr reviewers exclude accumulated memory; Themis uses
 reviewed learning. Config discovery alone establishes none of this.
 
-The installed CLI baseline is published OATS 0.22.5 on this Mac and `aweb-agents`,
+The installed CLI baseline is published OATS 0.22.7 on this Mac and `aweb-agents`,
 including native Pi/Claude/Codex, tmux/Herdr, shared `yolo`, remote Desktop
 roster/actions, retained-authority binding and corrected deferred retirement.
-The installed Mac Desktop 0.22.5 passed published ZIP checksum, strict deep
-codesign, packaged renderer and PTY launch checks; the previous 0.22.4 app
-is preserved for rollback. Official oats.okf 1.5.1 is published after independent
+The installed Mac Desktop 0.22.7 passed published ZIP checksum and strict deep
+codesign. Its controlled single-instance check passed and the app was closed
+afterwards, with all owned processes verified gone. The previous 0.22.6 app
+is preserved for rollback; earlier renderer/PTY checks remain version-specific.
+Official oats.okf 1.5.1 is published after independent
 review, adding harvest-runtime selection and detection of unadvanced record
 plans. Each deployment selects an authenticated harness; without an explicit
 harvest-model, that harness uses its own configured default. Some prepared
 teams still use the compatible 1.5.0 package; preserve the exact versions of
-each earlier qualification.
+each earlier qualification. Follow-up 1.5.2 is now published with truthful
+failure exits, harmless help and repeat-harvest branch reuse. BeadHub's actual
+deployment has been updated and re-trusted at 1.5.2; its previous lock was 1.5.0.
 
 BeadHub, Minerva and Merlin now have managed standing executions with retained
 identities. BeadHub and Minerva passed separate mail/chat checks; Merlin verified
 his identity and preserved claims, then received and replied to Minerva's real
-mail through the host wake path. This is not completion of all teams: frontend
-and Themis encountered failed setup, Docflow still has a running backfill, and
-the coordinator handovers remain outstanding. See the current status below;
+mail through the host wake path. Frontend also has a managed execution with
+separate mail/chat proof and reviewed knowledge promotion. This is not completion
+of all teams: TSM is held, Docflow still has a running backfill, and normal
+coordinator learning remains queued. The final lead handover is accepted.
+See the current status below;
 older evidence records keep the version and outcome of each earlier check.
 
 ## Current status and operating limits (2026-09-06)
@@ -70,22 +76,36 @@ no OATS Desktop process remained when lead took the incident snapshot.
 
 Lead stopped the capture watcher and residual capture passes, disabled their
 exact Claude hooks, and stopped the experimental mind follow service. Settings,
-service definitions, raw records and learning state are preserved. GUI launch
-is paused. Resume with one bounded operation at a time, checking memory between
-launches; declining swap alone does not prove sustained stability. Capture stays
-disabled until its concurrency fix is independently reviewed and measured. The
-first proposed lock was rejected because age-based stealing and initialization
-races could still permit overlapping passes.
+service definitions, raw records and learning state are preserved. Continue
+with one bounded operation at a time, checking memory between
+launches; declining swap alone does not prove sustained stability. Published
+0.22.6 prevents overlapping capture passes with a conservative lock that never
+steals an existing owner; interrupted owners require explicit recovery. Its
+measured full pass still exceeded a 2 GiB RSS budget during indexing and was
+stopped by the monitor. The follow-up streams journal entries instead of loading
+whole arrays. The independently reviewed candidate completed the real index of
+1.74 million turns in 41.6 seconds, at 809.5 MiB peak RSS with normal memory
+pressure, under a 256 MiB Node old-space budget. That fix is now published and
+installed in 0.22.7. The replacement launchd job runs one background pass every
+15 minutes, without per-tool hooks or a permanent watcher. Its first real pass
+completed in 101 seconds at 746 MiB peak RSS, with index completion and zero
+aw-log projection failures. The reviewed operator wrapper stops its own child
+on a 2 GiB RSS limit, two elevated memory-pressure samples, or a five-minute
+deadline. It records each run atomically in
+`~/.local/state/oats/capture/status.json`, retaining the previous success time
+through failures. Idle between passes is normal. Interrupted capture locks
+still need explicit owner-checked recovery; the wrapper reports the remedy.
+Experimental mind follow remains paused.
 
 | Scope | Verified state | Next boundary |
 | --- | --- | --- |
 | Host services | Published aw 1.36.1 installed; normal launchd wake service on Mac and enabled user service on `aweb-agents`; private broker stopped | Investigate repeated reconnect hints and reported read timing without assuming the broker acknowledged mail |
-| BeadHub | `beadhub-seat`, retained DID/address and claims; native Codex; independent mail/chat; first reviewed knowledge PR merged at `70c839e` | Repeat harvest exposed a retained merged-branch collision; operator updated the linked soul and removed only the verified merged branch; next cycle waits for a bounded launch slot |
-| Cjr | `accountant-minerva` and `coordinator-merlin` live on retained identities; old holders stopped first; claims preserved; real delivery and reviewed learning recorded | Complete the existing log worker's fresh review, one reviewer at a time; no financial authority changes |
-| Aweb | Coordinator remains live; old frontend stopped; replacement failed during a timed-out join that completed server-side | Supported cleanup of the retained failed home/orphan binding, then one successor with independent delivery checks |
+| BeadHub | `beadhub-seat`, retained DID/address and claims; native Codex; independent mail/chat; trusted OKF 1.5.2 and aweb 1.10.3; repeat harvest promoted all four notes and retired cleanly | PR #2 at `a111a222` independently reviewed and merged; canonical deployment checkout fast-forwarded with untracked data preserved, so the live soul sees the six-concept bundle |
+| Cjr | `accountant-minerva` and `coordinator-merlin` live on retained identities; old holders stopped first; claims preserved; real delivery and reviewed learning recorded | Log `5bfeefd1` and corrected librarian knowledge `6c91f986` landed with user edits preserved; librarian retired with alias reusable; Merlin's own harvest and health-reader follow-up remain queued |
+| Aweb | Retained `coordinator-aweb` and fresh `frontend-oats` both passed independent mail/chat; frontend knowledge `d649d729` reviewed and landed | Old holders stopped with their channel children before replacement; metadata repair and encryption-key findings tracked separately, with repeated wake-hint diagnosis in progress |
 | TSM | Prepared souls and owner checkpoints; Themis setup failed before the current hold | **No migration work until Zeus reports deployment finished**; re-inventory with its owner afterwards |
 | Docflow | Legacy seat and actual mail backfill remain running | Finish backfill and register checks; owner restores mail-ingest afterwards; accountant-sync remains unloaded under its separate export fence |
-| Oats/lead | Existing coordinators remain active | Last handovers, with actual stop receipts and all unresolved work carried forward |
+| Oats/lead | Retained `oats-coordinator-coordinator` passed independent mail wake; fresh team-local `lead-operating-lead` passed separate idle-to-wake mail fetch/reply after verified predecessor stop; root packages trusted at OKF 1.5.2 and aweb 1.10.3 | BeadHub accepted the lead and transferred the still-open rollout epic; Oats's provider capacity, historical lead claim reconciliation, coordinator learning and preserved recovery lessons remain follow-ups; cross-team updates use retained global relays |
 | Remote qualification | Published host service delivered native Claude mail/chat through Herdr; corrected knowledge independently reviewed; source retired with `aliasReusable: true` | Earlier separate fresh-reader cycle passed; latest corrected wake-specific retrieval is still pending |
 
 Published aw 1.36.1 is tagged at `bfdb20886080e4ffe1f02b266f6116d12bd100fd`.
@@ -97,10 +117,17 @@ Production same-alias join/delete/rejoin passed, and official oats.aweb 1.10.2
 reports the released alias result truthfully. Retained standing-seat retirement
 must still preserve authority.
 
-Desktop 0.22.5 has six validated team roots saved as workspace suggestions,
+Desktop has six validated team roots saved as workspace suggestions,
 not six running GUI instances. It starts with one workspace and can add others.
 It is currently closed; visual QA and sustained multi-workspace memory behavior
-are not claimed. Native remote Pi authentication and remote Codex remain
+are not claimed. Version 0.22.6 added a single-instance guard and 0.22.7 runs the
+packaged backend as Node. An installed 0.22.7 check served the Oats workspace API;
+a second launch exited successfully while the primary remained, with both
+owned process groups peaking at 589 MiB and normal memory pressure. All test
+processes were stopped and verified absent. The full release gate and all three
+Desktop builds passed on hosted runners; publication succeeded, and the bot's
+version-bump PR permission failure was resolved through reviewed manual PR #8.
+Native remote Pi authentication and remote Codex remain
 unqualified; the accepted remote harness is Claude.
 
 ## Scope inventory
@@ -119,7 +146,7 @@ of continuing seats.
 | `~/prj/docflow` | Live Claude seat identified itself as local `juan.aweb.ai/alice` on `docflow:juan.aweb.ai` | Owner Juan; finish running mail backfill and register checks before transfer; retain identity, memory and Minerva route; accountant-sync remains deliberately unloaded |
 | `ai.aweb` on `aweb-agents` | Aweb confirms Athena intentionally inactive; remote legacy home retained | Aweb and oats own archival inspection; do not resurrect as a continuing seat |
 | `~/awebai/demo-aweb/bob` | Live Pi demo | Aweb owns safe stop and archival disposition; it is not an operating-team migration |
-| `~/.turn-record` | Capture and experimental mind services paused after memory incident | Preserve records; review and measure resource fixes before resuming |
+| `~/.turn-record` | Guarded periodic capture enabled and measured; per-tool hooks and experimental mind follow remain disabled | Preserve records; monitor the run artifact; no blind watcher restart |
 
 The starting inventory above was checked on 2026-09-05 using harness process
 working directories and exact custom tmux sockets, without interrupting them.

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

@@ -0,0 +1,40 @@
+# OATS v0.22.8
+
+Two fixes an operator meets directly: picking a remote workspace in Desktop
+now works, and the bundled catalog pin for the knowledge package catches up
+with what is published.
+
+## Desktop: selecting a discovered remote workspace
+
+A registered SSH server's workspaces are discovered after the app starts, so
+the main process's record of what the backend advertises could be seeded
+before that discovery finished. Clicking the remote workspace in the menu then
+looked like nothing happened: the request carried a workspace id the record
+did not recognize, and an unrecognized selection is deliberately pinned back
+to the verified local scope. The workaround was to open Add workspace and
+cancel, whose own refresh repaired the record as a side effect.
+
+The main process now learns that record from the successful `/api/panel`
+responses it is already making, which are the same server-owned choices the
+menu is built from, so a workspace that appears late is selectable as soon as
+the menu can show it. No request is added, including for a selection that
+stays unrecognized. Only a successful panel response teaches it: error
+replies and other endpoints cannot. Nothing learned from an outgoing backend
+can survive its replacement: a request that begins while the backend is being
+replaced never teaches, and one that began earlier is refused if a replacement
+started before its reply arrived, so the workspaces a stopped server
+advertised cannot come back. Off-origin resolution is still rejected before
+anything is fetched, and a selection the backend does not advertise is still
+pinned to the local scope.
+
+## Bundled: oats.okf 1.5.2 pin
+
+The catalog shipped with the kernel now pins oats.okf v1.5.2, so
+`oats update oats.okf` resolves it without an explicit selector. Until now a
+bare update resolved the pin baked into the installed kernel, which was
+v1.5.1, and reaching 1.5.2 needed `oats update oats.okf --to v1.5.2`.
+Deployments that moved early with the explicit selector are already on the
+same payload and need nothing. 1.5.2 makes a failed harvest exit non-zero,
+stops `okf harvest --help` from running a harvest, and reclaims a leftover
+`memory-harvest/<slug>` branch whose promotion is already merged into the
+base, including when the base is a remote main ahead of the local one.

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-catalog.json

@@ -2,7 +2,7 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v1.5.1",
+      "ref": "v1.5.2",
       "path": "oats-package"
     },
     "oats.aweb": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.22.7",
+  "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",