@awebai/oats 0.46.0 → 0.48.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/oats.mjs CHANGED
@@ -30,7 +30,7 @@ import {
30
30
  LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
31
31
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
32
32
  officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
33
- findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchPromptPolicyAt, LAUNCH_PROMPT_UPDATE_WARNING, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
33
+ findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchPromptPolicyAt, LAUNCH_PROMPT_UPDATE_WARNING, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
34
34
  FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
35
35
  } from "../lib/core.mjs";
36
36
  import {
@@ -53,7 +53,7 @@ import { hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/sched
53
53
  import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
54
54
 
55
55
  import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
56
- import { planStop, applyStop, planRetire, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
56
+ import { planStop, applyStop, planRetire, descendantsOf, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
57
57
  import { extraWorktreeLines, formatBytes, workRecoveryLines } from "../lib/retire-output.mjs";
58
58
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
59
59
  import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
@@ -61,7 +61,7 @@ import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mj
61
61
 
62
62
  const rawArgs = process.argv.slice(2);
63
63
  /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
64
- const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
64
+ const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
65
65
  /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
66
66
  * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
67
67
  * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
@@ -1775,26 +1775,55 @@ async function teamsContext(bail) {
1775
1775
  }
1776
1776
  const positional = (i) => (args[i] !== undefined && !args[i].startsWith("--") ? args[i] : undefined);
1777
1777
 
1778
- /** `oats teams [--json] | add <label> --team <id> [--description <d>] | remove <label> | default <label>` —
1779
- * this deployment's teams (team model 3). Config only: never a provider call. */
1778
+ /** The flags each `oats teams` form takes (value flags → true), beyond the global `--dir` and `--json`.
1779
+ * Anything else is refused, never ignored: a kernel that ignored `--if-absent` would set unconditionally. */
1780
+ const TEAMS_FLAGS = {
1781
+ "": { "--max-age": true },
1782
+ add: { "--team": true, "--description": true, "--no-default": false },
1783
+ remove: {},
1784
+ default: { "--if-absent": false, "--expect": true },
1785
+ };
1786
+ /** The first flag `oats teams <sub>` does not take, or undefined. A value flag's value is skipped as flag()
1787
+ * reads it (the next word unless it starts with `--`). */
1788
+ function teamsUnknownFlag(sub) {
1789
+ const takes = { "--dir": true, "--json": false, ...TEAMS_FLAGS[sub ?? ""] };
1790
+ for (let i = 1; i < args.length; i++) {
1791
+ const a = args[i];
1792
+ if (!a.startsWith("-")) continue;
1793
+ if (!Object.hasOwn(takes, a)) return a;
1794
+ if (takes[a] && args[i + 1] !== undefined && !args[i + 1].startsWith("--")) i++;
1795
+ }
1796
+ return undefined;
1797
+ }
1798
+
1799
+ /** `oats teams [--json] | add <label> --team <id> [--description <d>] [--no-default] | remove <label> |
1800
+ * default <label> [--if-absent | --expect <label>]` — this deployment's teams (team model 3). Config only:
1801
+ * never a provider call. */
1780
1802
  async function teamsCmd() {
1781
1803
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
1782
- const usage = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] | oats teams remove <label> | oats teams default <label> [--dir <deployment>] [--json]";
1783
- const sub = positional(1);
1804
+ const usage = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] [--no-default] | oats teams remove <label> | oats teams default <label> [--if-absent | --expect <label>] [--dir <deployment>] [--json]";
1805
+ // A single-dash word (`-x`) is a flag, never the subcommand: teamsUnknownFlag names it.
1806
+ const sub = positional(1)?.startsWith("-") ? undefined : positional(1);
1784
1807
  if (sub !== undefined && !["add", "remove", "default"].includes(sub)) bail("E_USAGE", usage);
1808
+ const unknown = teamsUnknownFlag(sub);
1809
+ if (unknown !== undefined) {
1810
+ const form = sub ? `oats teams ${sub}` : "oats teams";
1811
+ bail("E_USAGE", `${form} does not take ${unknown} (an option this kernel does not know may need a newer kernel; nothing was changed) — ${usage}`, { flag: unknown });
1812
+ }
1785
1813
  const label = sub ? positional(2) : undefined;
1786
1814
  if (sub && label === undefined) bail("E_BAD_ARGS", `oats teams ${sub} needs a team label — ${usage}`);
1787
1815
  const ctx = await teamsContext(bail);
1788
1816
  const V = await import("../lib/teams-verbs.mjs");
1789
1817
  let result = null;
1790
1818
  try {
1791
- if (sub === "add") result = V.teamsAdd(ctx, label, { team: valueFlag("team"), description: valueFlag("description") });
1819
+ if (sub === "add") result = V.teamsAdd(ctx, label, { team: valueFlag("team"), description: valueFlag("description"), noDefault: args.includes("--no-default") });
1792
1820
  else if (sub === "remove") result = V.teamsRemove(ctx, label);
1793
- else if (sub === "default") result = V.teamsDefault(ctx, label);
1821
+ else if (sub === "default") result = V.teamsDefault(ctx, label, { ifAbsent: args.includes("--if-absent"), expect: valueFlag("expect") });
1794
1822
  } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
1795
1823
  const doc = V.teamsDocument(result ? { ...ctx, local: result.local } : ctx);
1796
- if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed } : withObservation(doc)); return; }
1797
- if (result) console.log(result.changed ? `${sub === "add" ? `Declared team ${label}` : sub === "remove" ? `Removed team ${label}` : `The default team is now ${label}`} in ${shortPath(ctx.localPath)}` : "Nothing to change");
1824
+ if (JSON_MODE) { jsonOk(result ? { ...doc, changed: result.changed, ...(result.reused ? { reused: true } : {}) } : withObservation(doc)); return; }
1825
+ if (result?.reused) console.log(`Team ${label} is already declared with that id: nothing to change`);
1826
+ else if (result) console.log(result.changed ? `${sub === "add" ? `Declared team ${label}` : sub === "remove" ? `Removed team ${label}` : `The default team is now ${label}`} in ${shortPath(ctx.localPath)}` : "Nothing to change");
1798
1827
  console.log(`default ${doc.defaultTeam ? `${doc.defaultTeam.label} (${doc.defaultTeam.from})` : "(none)"}`);
1799
1828
  console.log(`local ${doc.localTeams === null ? "allowed (standalone)" : doc.localTeams ? "allowed (localTeams: true)" : "not allowed"}`);
1800
1829
  if (!doc.teams.length) console.log("teams (none: `oats aweb setup` creates them, or `oats teams add <label> --team <id>`)");
@@ -2612,35 +2641,41 @@ function retireCmd() {
2612
2641
  const planRev = flag("plan-revision"), idemKey = flag("idempotency-key");
2613
2642
  if (planRev === true || idemKey === true) die("--plan-revision and --idempotency-key need values");
2614
2643
  if ((planRev !== undefined) !== (idemKey !== undefined)) die("--plan-revision and --idempotency-key go together");
2615
- let replayPath = null, childrenStopped = null, plannedExtraWorktrees;
2644
+ // What the plan says about recorded children holds on every apply path: the
2645
+ // retirement stops them first and keeps them (retireInstance, once it has
2646
+ // resolved the home). A guarded apply acts on the children of the plan it
2647
+ // revalidated; a plain or --self retire computes them as the plan does, and
2648
+ // passes none when there are none.
2649
+ let replayPath = null, plannedExtraWorktrees, fresh, children;
2616
2650
  if (planRev !== undefined) {
2617
2651
  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
2618
2652
  // Replay first: after a successful retire the home is gone, so the receipt
2619
2653
  // (beside the instances dir, keyed by the idempotency key) is the answer.
2620
2654
  const replay = (dir) => { const p = join(dir, `.oats-retire-receipt.${idemKey}.json`); if (!existsSync(p)) return false; try { const prior = JSON.parse(readFileSync(p, "utf8")); if (prior.retired !== name) return false; if (args.includes("--json")) jsonOk({ ...prior, replayed: true }); else console.log(`retire ${name}: replayed receipt for key ${idemKey}`); return true; } catch { return false; } };
2621
2655
  for (const a of listAgents(root)) if (replay(join(a._dir, "instances"))) return;
2622
- let fresh;
2623
2656
  try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message); }
2624
2657
  replayPath = join(dirname(fresh.home), `.oats-retire-receipt.${idemKey}.json`);
2625
2658
  // The extra trees the confirmed plan names, as it names them: the retire refuses as stale rather than
2626
2659
  // move or remove one that no longer reads that way when it gets to them.
2627
2660
  plannedExtraWorktrees = fresh.facts.extraWorktrees;
2628
2661
  if (fresh.planRevision !== planRev) return args.includes("--json") ? jsonFail("E_PLAN_STALE", `the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`, { plan: fresh }) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
2629
- // The plan promised: recorded children are STOPPED first (bounded, never
2630
- // escalated) and retained. A child still running after the grace refuses
2631
- // the retirement — nothing is retired, the receipt names the pid.
2632
- childrenStopped = [];
2633
- for (const kid of fresh.facts.children) {
2634
- try { const s = stopInstanceSession(kid.home, {}); childrenStopped.push({ instance: kid.instance, home: kid.home, ok: true, stopped: s.stopped, alreadyIdle: s.alreadyIdle }); }
2635
- catch (e) { childrenStopped.push({ instance: kid.instance, home: kid.home, ok: false, code: e.code || "E_SESSION_STOP_FAILED", message: e.message, stillRunning: e.receipt?.stillRunning ?? null }); }
2636
- }
2637
- const running = childrenStopped.filter((k) => !k.ok);
2638
- if (running.length) return args.includes("--json") ? jsonFail("E_CHILDREN_RUNNING", `${running.map((k) => k.instance).join(", ")} ${running.length === 1 ? "is" : "are"} still running after a bounded stop; nothing was retired and nothing was escalated`, { childrenStopped, plan: fresh }) : die(`children still running: ${running.map((k) => k.instance).join(", ")}; nothing retired`);
2662
+ children = fresh.facts.children;
2663
+ } else {
2664
+ const recorded = descendantsOf(root, name);
2665
+ if (recorded.length) children = recorded;
2639
2666
  }
2640
2667
  let r;
2641
- try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(plannedExtraWorktrees ? { plannedExtraWorktrees } : {}) }); }
2642
- catch (e) { if (!e?.code) throw e; return args.includes("--json") ? jsonFail(e.code, e.message, e.candidates ? { ...e.details, candidates: e.candidates } : e.details) : die(e.message); }
2643
- if (childrenStopped) r.childrenStopped = childrenStopped;
2668
+ try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(plannedExtraWorktrees ? { plannedExtraWorktrees } : {}), ...(children ? { children } : {}) }); }
2669
+ catch (e) {
2670
+ if (!e?.code) throw e;
2671
+ // A child still running (or whose stop could not be established) refused the retirement: the
2672
+ // guarded apply returns the plan it acted on, and the text names each child's reason.
2673
+ if (e.code === "E_CHILDREN_RUNNING") {
2674
+ const running = e.details.childrenStopped.filter((k) => !k.ok);
2675
+ return args.includes("--json") ? jsonFail(e.code, e.message, { ...e.details, ...(planRev !== undefined ? { plan: fresh } : {}) }) : die(`children still running: ${running.map((k) => `${k.instance} (${k.code})`).join(", ")}; nothing retired`);
2676
+ }
2677
+ return args.includes("--json") ? jsonFail(e.code, e.message, e.candidates ? { ...e.details, candidates: e.candidates } : e.details) : die(e.message);
2678
+ }
2644
2679
  if (replayPath) { r.planRevision = planRev; r.idempotencyKey = idemKey; r.replayed = false; try { writeFileAtomic(replayPath, JSON.stringify(r, null, 2)); } catch { /* receipt is evidence, not authority */ } }
2645
2680
  // A retired home's wake jobs are forgotten (definitions only; nothing is
2646
2681
  // stopped by this); a deferred self-retire keeps them until the home is gone.
@@ -2677,6 +2712,7 @@ function retireCmd() {
2677
2712
  process.exit(1);
2678
2713
  }
2679
2714
  console.log(`Retired ${r.retired} (agent ${r.agent})${r.worktreeRemoved ? ", worktree removed" : ""}`);
2715
+ for (const k of r.childrenStopped || []) console.log(` child ${k.instance}: ${k.alreadyIdle ? "already idle" : "stopped"}`);
2680
2716
  // Preserving work and not saying so leaves the operator believing it is gone,
2681
2717
  // which is most of the harm of deleting it. Name the classes and the path.
2682
2718
  for (const line of workRecoveryLines(r)) console.log(line);
@@ -3414,7 +3450,7 @@ function versionCmd() {
3414
3450
  // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
3415
3451
  // runs on resolve/materialize (contract §6); a feature the binary does not implement is
3416
3452
  // never listed.
3417
- console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
3453
+ console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
3418
3454
  return;
3419
3455
  }
3420
3456
  console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -4217,10 +4253,14 @@ Usage:
4217
4253
  [--max-age <s>] (souls have no private mode), with origin
4218
4254
  (member <key> @ <commit> | package <id> v<ver>) and its
4219
4255
  teams on this deployment
4220
- oats teams [--json] | add <label> --team <id> [--description <d>] | remove <label>
4221
- | default <label> [--dir <d>] this deployment's teams (shared + local), the
4256
+ oats teams [--json] | add <label> --team <id> [--description <d>] [--no-default] | remove <label>
4257
+ | default <label> [--if-absent | --expect <label>]
4258
+ [--dir <d>] this deployment's teams (shared + local), the
4222
4259
  [--max-age <s>] (the read form only) default, the workspace's souls:; add/remove/default
4223
- edit oats-local.yaml (only with localTeams: true)
4260
+ edit oats-local.yaml (only with localTeams: true);
4261
+ --no-default: the mapping only (an exact repeat is
4262
+ reuse); --if-absent / --expect: set the default only
4263
+ where there is none / it is <label>
4224
4264
  oats soul teams <soul>|'*' [--dir <d>] which teams a soul may join here, its default, and
4225
4265
  [--max-age <s>] [--json] why (the workspace's souls: and local teams)
4226
4266
  oats instance git <instance> [--home <abs>] [--dir <d>] [--json]
@@ -495,6 +495,14 @@ start (a renewed session grant, for example) leaves the CURRENT one on record. A
495
495
  launch hook that answers without `meta` keeps its previous entry; a start whose
496
496
  preparation fails changes nothing.
497
497
 
498
+ A launch hook's `brief` is not used. A home's `TASK.md` (which carries the
499
+ spawn hooks' briefs) and `AGENTS.md` are composed once, at spawn, and no start
500
+ rewrites them. A provider whose state changes at a start records it in `meta`.
501
+ `oats inspect --home <abs> --json` reads the served identity a provider
502
+ recorded there (the messaging provider's, when it has one) as `identity`. A
503
+ spawn brief that describes such state should say it is the state at spawn and
504
+ point to that command.
505
+
498
506
  A launch hook may do idempotent provider registration on a real start (an
499
507
  aweb home registering with the host wake broker, for example). How the
500
508
  kernel runs it depends on whether its capability declares **preview
@@ -63,7 +63,7 @@ refused (`E_WORKSPACE_SCHEMA`).
63
63
  | `launchPromptAnswers.homes.<absolute-home>` | Explicit per-home `awebDevelopmentChannel` boolean consent; defaults false. See [launch prompt consent](#exact-home-launch-prompt-consent). |
64
64
  | `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
65
65
  | `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`, a team only this deployment uses; every soul may join it. Allowed only where `oats-workspace.yaml` says `localTeams: true` (or in the standalone view); otherwise refused (`E_WORKSPACE_SCHEMA`, reason `local-teams-closed`). Shared teams are committed in `oats-workspace.yaml`; a label in both is `team-label-collision` (the shared one wins). Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
66
- | `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it; `oats teams default <label>` changes it. |
66
+ | `defaultTeam` | This deployment's default team: a label of a local or shared team, under the same condition as `teams`. A soul's own default in the workspace's `souls:` wins over it; it wins over the workspace's `defaultTeam`. The first `oats teams add` sets it (unless `--no-default`); `oats teams default <label>` changes it, and `--if-absent` / `--expect <label>` change it only where there is no effective default / it is that label. |
67
67
  | `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. |
68
68
  | `session.tmuxSession` | The tmux session new tmux instances open their windows in (0.31). Absent: `OATS_TMUX_SESSION`, else `PI_AGENTS_TMUX_SESSION` (the pre-0.31 variable), else `oats-agents`. `session: { tmuxSession: pi-agents }` keeps the pre-0.31 layout. `oats inspect --json` reports it as `session`. |
69
69
  | `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
@@ -121,24 +121,30 @@ The qualified channel frame starts on its accepted option and permits one
121
121
  Enter only. Folder-trust and API-key questions remain unexpected and block.
122
122
  A qualified normal-output boundary closes observation without asserting readiness.
123
123
 
124
- **Qualified completion and limitation:** exact captured banners cover Claude
125
- 2.1.289 on darwin-arm64 at 110x35 with aweb-channel 1.7.11 installed, and the
126
- original plugin-absent banner. Both name Opus 5.5, API Usage Billing, auto mode
127
- and medium effort. Source-derived synthetic variants additionally allow exactly
128
- `Claude Max`, `Claude Pro`, `Claude Team` or `Claude Enterprise` in place of
129
- `API Usage Billing`; these are not observed subscription captures. Claude may
130
- prefer an account-specific plan display name over those fallback labels; other
131
- display names remain unqualified even for subscribers on those plans. Every other
132
- row stays exact apart from the bounded canonical-home directory line. This
133
- interim extension does not cover task-filled screens or bypass-permissions mode.
134
- Other model, billing, effort or permission banners remain unqualified: the one
135
- Enter can be submitted before `E_SPAWN_INCOMPLETE` with
136
- `launchPrompts.status: blocked`. The submitted answer remains in `answers` and
137
- the event receipt; the pane may already be active. Inspect the retained target;
138
- do not automatically retry input or relaunch it. The installed capture used an
139
- isolated configuration and dummy credentials with runtime network denied. It
140
- proves bounded UI completion, not live-account admission, connection or native
141
- receive readiness, and does not establish success for every production setup.
124
+ **Qualified completion and limitation:** the existing exact captured and
125
+ source-derived empty API/subscription frames remain supported. After one recorded
126
+ submitted channel Enter, the same qualified Claude 2.1.289 darwin-arm64 executable
127
+ also recognizes the [bounded bottom input/footer structure](launch-prompt-completion.md)
128
+ at 110x35. Its six mode labels, five effort labels and finite hints are
129
+ source-qualified; header/billing/model and preceding task text are not structural
130
+ completion conditions. The 21 exact question markers take precedence over both
131
+ completion paths after submission. Normal `? for shortcuts` and `esc to interrupt`
132
+ are not markers. Input authorization and exact-home consent are unchanged.
133
+
134
+ **Accepted reporting risk:** an unknown dialog retaining the composer/footer can
135
+ be misclassified completed. Completion permanently closes input authority, but
136
+ proves neither absence of all questions nor idle/account/channel readiness.
137
+ Missing effort, trailing notices, wrapped footers and other unsupported shapes
138
+ still block. A feature-flag footer change can reduce matches without a binary
139
+ change. A matched structural frame must be saved privately before completed is
140
+ audited; failure reports incomplete with the answer and target preserved.
141
+
142
+ A submitted Enter can therefore precede `E_SPAWN_INCOMPLETE`; the pane may already
143
+ be active. Inspect the answer, checked event receipt and retained target, rather
144
+ than automatically retrying input or relaunching. Existing API fixtures used
145
+ isolated dummy credentials; the observed Max regression is a labeled home-only
146
+ sanitized derivative of one controller-compared in-progress frame, not a new
147
+ end-to-end launch proof or general production-success claim.
142
148
 
143
149
  When a harness update changes the version-bound prompt frame, opted-in homes
144
150
  block again with `blocked: unexpected prompt` until fixtures are refreshed.
@@ -40,7 +40,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
40
40
  "team-model-3","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
41
41
  "preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
42
42
  "workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
43
- "automation-descriptions","souls-capabilities","soul-composed-instructions"],
43
+ "automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default"],
44
44
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
45
45
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
46
46
  "capabilityShowApi":1}
@@ -112,6 +112,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
112
112
  | `automation-descriptions` | a `description` on every trigger and schedule row, local or workspace, by one rule; `oats schedule update <id> --description=<text>` (the description only) and `oats trigger update <id> --description=<text>`; `--description=<text>` on `schedule add` and `trigger add`, OATS 0.43.0 ([Shared row fields](#automations-shared-rows)) | |
113
113
  | `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
114
114
  | `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
115
+ | `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
115
116
 
116
117
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
117
118
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -367,7 +368,7 @@ An instance subject, abridged:
367
368
  | `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
368
369
  | `knowledge` | `{provider, version, operations: [{name, kind, available, reason}]}` for the knowledge slot (`null`s and `[]` when empty) |
369
370
  | `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order |
370
- | `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null` |
371
+ | `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null`. Read on every call, so after a start whose launch hook returned new `meta` it is that start's record, not the spawn's |
371
372
  | `problems` | below |
372
373
 
373
374
  **Soul row** (`soulsApi: 2`). For a home it is read from the recorded
@@ -1250,9 +1251,9 @@ unknown.
1250
1251
 
1251
1252
  ```text
1252
1253
  oats teams [--dir <d>] [--max-age <s>] --json
1253
- oats teams add <label> --team <id> [--description <d>] --json
1254
+ oats teams add <label> --team <id> [--description <d>] [--no-default] --json
1254
1255
  oats teams remove <label> --json
1255
- oats teams default <label> --json
1256
+ oats teams default <label> [--if-absent | --expect <label>] --json
1256
1257
  ```
1257
1258
 
1258
1259
  ```json
@@ -1284,13 +1285,41 @@ oats teams default <label> --json
1284
1285
  still runs there: taking local teams away is the last step of committing
1285
1286
  them in the workspace.
1286
1287
  - **`add`**: the first team added also becomes the local `defaultTeam`. A
1287
- label already declared is `E_TEAM_EXISTS {label, from}`; a bad label or no
1288
- `--team` is `E_BAD_ARGS`.
1288
+ label already declared is `E_TEAM_EXISTS {label, from, observed: {label,
1289
+ team, from}}` (`observed` is the declared mapping; `from` is `"local"` or
1290
+ `"shared"`); a bad label or no `--team` is `E_BAD_ARGS`.
1291
+ - **`add --no-default`** (feature `teams-conditional-default`) writes the
1292
+ mapping and never touches `defaultTeam`. A mapping already declared with
1293
+ the same label and the same team id (local or shared) is reuse: the answer
1294
+ is `changed: false, reused: true`, so a setup can retry it. The description
1295
+ is neither compared nor changed. The same label with another id is
1296
+ `E_TEAM_EXISTS` as above. `reused` appears only on that answer. Where local
1297
+ teams are not allowed, `add --no-default` is refused with local-teams-closed
1298
+ like every `add`, before reuse is considered.
1289
1299
  - **`remove`**: a label the local `defaultTeam` names is `E_TEAM_IN_USE
1290
1300
  {label, usedBy: ["defaultTeam"]}`; a shared label is `E_TEAM_SHARED {label,
1291
1301
  at}` (a label in both files can be removed locally); unknown is
1292
1302
  `E_TEAM_UNKNOWN {label}`.
1293
1303
  - **`default`**: any declared label, else `E_TEAM_UNKNOWN`.
1304
+ - **`default --if-absent`** sets it only where the deployment has no effective
1305
+ default (this document's `defaultTeam` is `null`); **`default --expect
1306
+ <label0>`** only where the effective default's label is `<label0>`, local
1307
+ or inherited from the workspace (feature `teams-conditional-default`). The
1308
+ two together are `E_BAD_ARGS`. A failed condition is `E_TEAM_DEFAULT_MISMATCH
1309
+ {expected: {absent: true} | {label}, observed}`, `observed` being the
1310
+ `defaultTeam` exactly as this document reports it (or `null`); nothing was
1311
+ written. A soul's `souls:` default is not the deployment's and is not
1312
+ looked at. The refusals above run first, in order: `E_BAD_ARGS`,
1313
+ local-teams-closed, `E_TEAM_UNKNOWN`, then the condition. When the
1314
+ condition holds and `<label>` already is the local default, `changed` is
1315
+ `false`.
1316
+ - **Flags**: each form refuses a flag it does not take with `E_USAGE {flag}`,
1317
+ naming the flag and the usage, before anything is read. `add` takes
1318
+ `--team`, `--description`, `--no-default`; `remove` none; `default`
1319
+ `--if-absent`, `--expect`; every form `--dir` and `--json`, and the read
1320
+ form `--max-age` (on a write form, `--max-age` is the kernel's own
1321
+ `E_BAD_ARGS`, as for every write verb). `--help` is the kernel's usage
1322
+ answer, as for every command.
1294
1323
  - A write that would introduce an unknown reference is refused with that
1295
1324
  code; an invalid result is `E_WORKSPACE_SCHEMA`.
1296
1325
  - **Writes** edit `oats-local.yaml` in place and touch only the entries that
@@ -1298,7 +1327,22 @@ oats teams default <label> --json
1298
1327
  entries, are kept. Each verb re-reads the file and judges its refusals on it
1299
1328
  as it is now, and writes only if the file did not change meanwhile (else it
1300
1329
  redoes the edit on the new content). A file that keeps changing is
1301
- `E_LOCAL_CHANGED {path}`; nothing was written.
1330
+ `E_LOCAL_CHANGED {path}`; nothing was written. The condition of `--if-absent`
1331
+ and `--expect` is judged the same way, on the file as it is now and again on
1332
+ every redo.
1333
+ - **Concurrency.** Every `add`, `remove` and `default` holds
1334
+ `<deployment>/.agents/locks/local.lock` for its whole read-compare-write.
1335
+ Among concurrent `oats teams` writers on one deployment, a conditional write
1336
+ therefore never overwrites a default another of them set: when two race, the
1337
+ later one sees the earlier result and refuses with
1338
+ `E_TEAM_DEFAULT_MISMATCH`. A lock still held after 5 s is `E_LOCAL_BUSY
1339
+ {path, lock}`, naming the directory to remove when no oats process is
1340
+ editing; nothing was written. The limits: a person or tool editing
1341
+ `oats-local.yaml` directly does not take the lock (the content compare still
1342
+ catches most such edits, but not one landing between the compare and the
1343
+ rename), and changes to the committed `oats-workspace.yaml` (a pull, a
1344
+ merge) are not serialized with it: the condition reads the workspace file
1345
+ when it is judged, and that is the only promise.
1302
1346
 
1303
1347
  <a id="oats-soul-teams"></a>
1304
1348
  ### `oats soul teams`
@@ -1626,13 +1670,15 @@ allocated. Use runtime inspection and the existing start/restart lifecycle.
1626
1670
  Same-key spawn replay cannot convert a blocked outcome to successful spawn.
1627
1671
 
1628
1672
  `answers` can contain a `submitted` answer even when the final status is
1629
- `blocked`: the accepted installed-plugin and plugin-absent completion banners
1630
- pin specific model/effort/permission text and finite billing labels, including
1631
- source-derived Max/Pro/Team/Enterprise variants of the empty API frame. A different normal-looking banner can block after Enter
1673
+ `blocked`: even after exact or structural completion recognition is qualified,
1674
+ unsupported input/footer shapes and known question markers can block after Enter
1632
1675
  while the actual pane is active. Consumers must preserve that submitted receipt
1633
1676
  and never translate this outcome into “nothing started” or automatic retry.
1634
1677
  The [completion limitation](configuration.md#exact-home-launch-prompt-consent)
1635
- is part of the shipping contract.
1678
+ is part of the shipping contract. Structural completion closes observation only;
1679
+ unknown dialogs retaining the recognized composer/footer can be misclassified.
1680
+ Mandatory structural evidence-save failure reports checked `incomplete` with the
1681
+ same answer and target preserved. Private receipt v2 adds no public DTO fields.
1636
1682
 
1637
1683
  Strict Desktop/pi readers must accept these additive fields and the new event
1638
1684
  kind before a writer containing them ships. For operator recovery, see
@@ -2846,14 +2892,32 @@ A first retire prints the **raw receipt**, not an envelope:
2846
2892
  pendingMarker, resultPath, logPath, completesInSec, completionPid}`, or
2847
2893
  `{…, alreadyScheduled: true, requestedAt}`.
2848
2894
 
2895
+ **Recorded children**, on every apply (plain, guarded and `--self`), as the
2896
+ plan says: each child the plan lists is stopped first (bounded SIGTERM,
2897
+ never escalated) and kept, once the retire has resolved the home and before
2898
+ the instance's own session is stopped. `childrenStopped[]` lists them,
2899
+ deepest first, as `{instance, home, ok: true, stopped, alreadyIdle}` or
2900
+ `{instance, home, ok: false, code, message, stillRunning}`. A plain or
2901
+ `--self` receipt carries it only when there are children; a guarded receipt
2902
+ always does (`[]` when there are none). One child still running after the
2903
+ grace, or whose stop could not be established (`E_SESSION_UNAVAILABLE`,
2904
+ `E_INSTANCE_RETIRING`, …), refuses everything: nothing is retired, exit 1,
2905
+ `E_CHILDREN_RUNNING {childrenStopped}` (the text form names each child and its
2906
+ `code`). **`--force` does not bypass it**: `--force` covers incomplete
2907
+ cleanup, not a running child. A `--self` retirement stops the children
2908
+ recorded when it was scheduled that are still instances (a child retired in
2909
+ between is skipped), in its detached completion before it stops the caller;
2910
+ a refusal there leaves the caller's window and home in place and
2911
+ writes `{ok: false, error: {code: "E_CHILDREN_RUNNING"}, childrenStopped,
2912
+ retry}` to `resultPath`. Before 0.48.0 only a guarded apply stopped children.
2913
+
2849
2914
  **Guarded apply** (what the Desktop sends): `--plan-revision` and
2850
2915
  `--idempotency-key` together.
2851
2916
  - A used key replays its receipt as an **envelope** with `replayed: true`
2852
2917
  (receipts live beside the instances directory and outlive the home).
2853
2918
  - The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`.
2854
- - Children are stopped first (never escalated) and kept; `childrenStopped[]`
2855
- lists them. One still running refuses everything: `E_CHILDREN_RUNNING
2856
- {childrenStopped, plan}`.
2919
+ - The children stopped are those of the revalidated plan, and a refusal
2920
+ carries it: `E_CHILDREN_RUNNING {childrenStopped, plan}`.
2857
2921
  - A first guarded retire prints the raw receipt with `planRevision`,
2858
2922
  `idempotencyKey` and `replayed: false`.
2859
2923
 
package/docs/desktop.md CHANGED
@@ -294,12 +294,12 @@ for a password or key, and never runs anything over ssh itself.
294
294
  ## Instances on servers
295
295
 
296
296
  Every instance a registered server reports shows in its workspace's roster, whoever spawned it. You
297
- can open its terminal, start, restart, stop and remove it, and read its readiness, activity, Git
297
+ can open its terminal, start, restart, stop and retire it, and read its readiness, activity, Git
298
298
  and diffs, as for a local one. The context panel's Soul tab and its Messaging & Teams list read
299
299
  through the server too (`oats inspect --server <id> --home <path>`), and its Work card, "model
300
300
  from" line and "older build" chip show the facts the server relays. Only its pull request is not read here, since the forge reads this
301
301
  computer's clones. Every command goes to the server by the instance's home (`--server <id> --home
302
- <path>`), never by a bare name. Stop and Remove show the plan the server makes, and confirm
302
+ <path>`), never by a bare name. Stop and Retire show the plan the server makes, and confirm
303
303
  against it.
304
304
 
305
305
  A read waits for the server: the view says "Reading from <server>…", and gives up after about
@@ -615,7 +615,8 @@ anchor edited or removed since the original pre-hook snapshot, instead of
615
615
  replacing concurrent changes with stale metadata. `launchPrompts` records `status`,
616
616
  `answers`, `reason` and event `receipt`; unknown prompts use
617
617
  `blocked: unexpected prompt`. Status `incomplete` means the audit could not be
618
- completed, including a possible key followed by an audit failure. It is
618
+ completed, including a possible key followed by an audit failure or failure to
619
+ retain mandatory structural-completion evidence. It is
619
620
  not proof that no input was sent. Both outcomes record `launched:false` while
620
621
  retaining the real process/endpoint for inspection: this is never permission
621
622
  to allocate another harness.
@@ -636,11 +637,79 @@ No audit or metadata write is directed into the replacement home.
636
637
  A blocked result can follow a successfully submitted Enter. The accepted
637
638
  completion families cover exact installed-plugin and plugin-absent banners,
638
639
  plus source-derived billing-only variants of those empty frames (Max, Pro,
639
- Team and Enterprise). Other model, billing, effort or permission text can leave the pane active while
640
+ Team and Enterprise), and source-derived empty Max/bypass/medium frames.
641
+ Other model, billing, effort or permission text can leave the pane active while
640
642
  reporting a retained block. Inspect `answers` and the event receipts; never infer
641
643
  that nothing started or nothing was answered. See the
642
644
  [completion limitation](configuration.md#exact-home-launch-prompt-consent).
643
645
 
646
+ ### Private unmatched launch evidence
647
+
648
+ This section also covers mandatory structural-completion evidence.
649
+
650
+ After a submitted launch answer, an unmatched 110x35 frame is retained locally
651
+ at `<home>/.oats/launch-prompt-evidence/<sha256(startId)>/frame.txt`, with
652
+ `receipt.json` published last. This is the exact UTF-8 text already compared by
653
+ the controller, including whitespace and final newline, not a later recapture.
654
+ It is bounded to 64 KiB and 35 rows. There is no new input, observation, retry,
655
+ geometry change or readiness claim. Evidence is also mandatory when the post-answer
656
+ [structural completion rule](launch-prompt-completion.md) selects completion.
657
+ Previously qualified exact completion does not acquire that requirement. No
658
+ frame is saved before a submitted answer or for unrelated blocked reasons.
659
+
660
+ Find the invocation's existing `launch-prompt` event in the home's
661
+ `.oats-events.jsonl` (or the checked event rows in `launchPrompts.receipt`). Its
662
+ `data.startId` supplies the string to hash with SHA-256, UTF-8, yielding the
663
+ lowercase hexadecimal directory name. Match the event's home, socket, window,
664
+ pane, PID and `signatureDigest`; do not assume a top-level spawn-result `startId`.
665
+ Spawn and same-home start/restart use this same controller and event path.
666
+
667
+ New evidence directories are owner-only 0700 and files 0600. The writer checks
668
+ canonical directory identities, ownership, modes and symlinks, refuses ACLs on
669
+ evidence directories/files (including macOS ACLs hidden by xattrs), refuses an
670
+ existing invocation directory, and publishes bounded files without overwrite.
671
+ The private receipt binds the start, target, original home identity, dimensions,
672
+ frame inode, byte count and SHA-256. `retainedAt` is write time; `captureTime:null`
673
+ means no independent capture timestamp was recorded. It does not substitute an
674
+ event timestamp for capture time. Same-uid concurrent mutation between checks is
675
+ not excluded.
676
+
677
+ Private receipt version 2 uses `kind:"launch-prompt-frame"` and admits only
678
+ `outcome:"blocked", recognition:"unmatched"` or
679
+ `outcome:"completed", recognition:"structural"`. These fields describe the
680
+ recognition whose frame was saved, not the final public launch result: a later
681
+ audit or cleanup failure can still report `incomplete`. Historical version 1
682
+ receipts with `kind:"launch-prompt-unmatched"` describe blocked/unmatched
683
+ evidence. Readers must reject unknown versions, kinds or crossed pairs rather
684
+ than infer completion from an artifact's presence.
685
+
686
+ Before collecting a frame, verify its original `frameIdentity`, byte count,
687
+ digest and dimensions against the receipt, and bind the receipt's `startId`,
688
+ home and target to the checked launch event. A copied file has a different
689
+ inode: preserve the original identity as provenance instead of comparing the
690
+ copy's inode with it. Missing, partial, mismatched or failed-save evidence, or
691
+ an incomplete public launch result, must not be reported as a successful
692
+ completed observation. Collection never recaptures the pane or retries input.
693
+
694
+ Verify both files, receipt/identity/digest and the corresponding checked event
695
+ before treating the save as complete. A frame alone is partial evidence. Failed
696
+ publication, fsync, readback or temporary-file cleanup leaves the launch blocked
697
+ and adds only `; private launch evidence retention failed` to its diagnostic
698
+ reason. Already published files may remain, including a receipt if a later
699
+ verification fails; their presence alone is not a success claim. The submitted
700
+ answer is preserved. Existing event-audit failures still report `incomplete`.
701
+ A structural-completion save failure instead reports checked `incomplete` with
702
+ `private launch evidence retention failed`, preserving the submitted answer and
703
+ retained target. It never retries publication or input. An audit failure remains
704
+ incomplete even if private evidence was saved. No public result or event contains
705
+ the raw screen or private receipt.
706
+
707
+ The frame can contain private task or account text. It stays on this host with
708
+ no automatic transmission or expiry. Preserve needed evidence privately before
709
+ retirement; it follows the home's ordinary conservative recovery behavior, with
710
+ no integrity-neutral exclusion or new cleanup policy. A saved frame is evidence
711
+ for review, never automatic permission to activate a new matcher.
712
+
644
713
  Retiring a blocked or incomplete spawned home can preserve a recovery copy
645
714
  labelled `changed instance-home bytes`, even without authored changes: the
646
715
  kernel changed metadata from `launched:true` to `false` after its baseline.
@@ -675,6 +744,9 @@ oats session attach --home /abs/home
675
744
  harness, `shell` for a fallback shell,
676
745
  `stopped` for an absent or dead terminal, or `not-launched`. An unavailable
677
746
  backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
747
+ A home without its session receipt is refused with
748
+ `E_RUNTIME_ENDPOINT_UNKNOWN`, naming the receipt path it looked for; what
749
+ to do is in [souls and instances](souls-and-instances.md#retire).
678
750
  Beside `state`, `waitingOnYou` (feature `waiting-on-you`) is a producer's
679
751
  live claim that the instance needs input from a human, `{since, producer,
680
752
  reason, message}`, or `null`; it is non-null only for a running harness
@@ -13,8 +13,9 @@ reference pages ([workspaces](workspaces.md), [souls and instances](souls-and-in
13
13
  catalog (`package-catalog.json`). It has no runtime dependencies.
14
14
  - **`@awebai/oats-pi`** (`packages/pi/`): a thin pi adapter that exposes an
15
15
  instance's own resources. It registers no agent tools.
16
- - **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup` and
17
- `oats.knowledge-theory` capabilities and the `knowledge-theory-expert` soul,
16
+ - **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup`,
17
+ `oats.support` and `oats.knowledge-theory` capabilities and the
18
+ `knowledge-theory-expert` soul,
18
19
  released as a package under its own `oats-framework/v<version>` tags.
19
20
  `oats.core` is the one with executables: its spawn and launch hook and the
20
21
  Claude Code waiting emitter (`capabilities/oats-core/bin/`).
@@ -66,6 +67,8 @@ published to npm. Its developer docs are in
66
67
  | `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`), the hook environment rules, the readiness wire |
67
68
  | `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
68
69
  | `servers.mjs` | routing commands to a registered server |
70
+ | `launch-prompt-evidence.mjs` | private bounded storage of exact post-answer unmatched or structurally completed frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
71
+ | `launch-prompt-completion.mjs` | pure, qualified post-answer completion reporting using a finite bottom input/footer table and 21 question markers; never an input matcher |
69
72
  | `launch-prompt-policy.mjs` | strict host-local exact-home aweb development-channel consent, canonical directory validation and config provenance |
70
73
  | `launch-prompts.mjs`, `launch-prompt-transport.mjs` | bounded launch-only controller and visible-screen transport; private process authority, injectable clock/transport, durable checked receipts and the fixture-gated exact aweb development-channel signature |
71
74
  | `harness-trust.mjs` | read-only native trust coverage and operator remedy for launches |
@@ -365,3 +368,22 @@ and acts on every existing session through its recorded socket
365
368
  `list-windows`, `new-window` (a window id) and `set-option`.
366
369
  - A server a test starts is killed by its socket, never by name and never
367
370
  with a bare `tmux kill-server`.
371
+
372
+ Nor does a test depend on where or how the suite runs:
373
+
374
+ - A worker whose working directory is inside an instance home (a developer
375
+ agent running the suite from its work tree) is that instance to the
376
+ kernel. `isolateSessionEnvironment` leaves it; a fixture that builds its
377
+ environment itself calls `leaveEnclosingInstance(base)` and moves back
378
+ when it is done.
379
+ - `isolateSessionEnvironment` drops `CLAUDECODE`, which a worker inherits
380
+ from a Claude Code session: a server the worker starts would hold it.
381
+ - An expected path is built on a canonical fixture base,
382
+ `realpathSync(mkdtempSync(…))`: the platform's temporary directory can be
383
+ a symlink (`/var` on macOS), and the kernel builds the paths it reports on
384
+ its working directory, which the OS gives as the physical path.
385
+ - A probe of the host that reads under `HOME` (the scheduler's installed
386
+ unit) runs with the fixture's own `HOME`.
387
+ - A fixture the filesystem may not represent (a file name that is not valid
388
+ UTF-8, which APFS refuses) is probed in the fixture directory and skipped
389
+ with its reason only when refused; Linux CI runs it.