@awebai/oats 0.43.3 → 0.44.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.
Files changed (32) hide show
  1. package/bin/oats.mjs +98 -27
  2. package/docs/capabilities.md +7 -1
  3. package/docs/configuration.md +65 -0
  4. package/docs/desktop-cli-api.md +149 -4
  5. package/docs/execution-targets.md +75 -0
  6. package/docs/implementation.md +14 -1
  7. package/docs/oats-local.schema.json +19 -1
  8. package/docs/oats-workspace.schema.json +1 -1
  9. package/docs/release-notes/v0.44.0.md +161 -0
  10. package/docs/schedules.md +27 -9
  11. package/docs/souls-and-instances.md +7 -0
  12. package/lib/core.mjs +253 -87
  13. package/lib/instance-events.mjs +1 -1
  14. package/lib/instance-inspect.mjs +39 -6
  15. package/lib/launch-prompt-fixtures/README.md +49 -0
  16. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +35 -0
  17. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +35 -0
  18. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +35 -0
  19. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +35 -0
  20. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +77 -0
  21. package/lib/launch-prompt-fixtures.mjs +114 -0
  22. package/lib/launch-prompt-policy.mjs +73 -0
  23. package/lib/launch-prompt-transport.mjs +102 -0
  24. package/lib/launch-prompts.mjs +216 -0
  25. package/lib/operator-coverage.mjs +134 -0
  26. package/lib/remote.mjs +15 -9
  27. package/lib/schedule.mjs +57 -10
  28. package/lib/teams-verbs.mjs +3 -3
  29. package/lib/triggers.mjs +2 -2
  30. package/lib/workspace.mjs +20 -2
  31. package/package.json +1 -1
  32. package/skills/oats-getting-started/SKILL.md +15 -0
package/bin/oats.mjs CHANGED
@@ -5,8 +5,8 @@
5
5
  * oats doctor [dir] [--soul <s>] [--json] show the deployment; --soul: the instructions an instance of <s> would carry
6
6
  * oats onboard [<dir>] --workspace <ref> realize a workspace here (oats-local.yaml +
7
7
  * agents/), then sync
8
- * oats sync [--dir <d>] [--json] discover the workspace, confirm membership,
9
- * resolve packages, write the lock
8
+ * oats sync [--dir <d>] [--plan] [--json] discover the workspace, confirm membership,
9
+ * resolve packages, write the lock (--plan: write nothing)
10
10
  * oats package add|remove ... edit `packages:` in the workspace file
11
11
  * oats workspace status membership table, packages
12
12
  * oats capabilities | oats souls every visible item of the workspace
@@ -30,11 +30,11 @@ 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, 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, 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,
34
34
  FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
35
35
  } from "../lib/core.mjs";
36
36
  import {
37
- writeFileAtomic, LOCK_FILE, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
37
+ writeFileAtomic, LOCK_FILE, canonicalLock, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
38
38
  classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
39
39
  import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
40
40
  import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
@@ -252,6 +252,40 @@ function doctorLocalTeams(local) {
252
252
  information: !standalone && file === null && declared ? ["local-teams-closed: whether oats-workspace.yaml allows oats-local.yaml teams/defaultTeam (localTeams: true) couldn't be checked: this deployment hasn't observed its workspace yet; run oats sync"] : [] };
253
253
  }
254
254
 
255
+ /** Operator coverage in doctor (#671), OFFLINE like the rest of doctor: the souls this workspace offers,
256
+ * discovered and resolved from this machine's cache only (cacheOnlyRemote: no git process, no network),
257
+ * for the workspace and EVERY declared team. Warnings in problems; when the cache cannot answer, one
258
+ * information line that says coverage is unknown, never that the operator is missing.
259
+ * → { problems: [{ code, message, remedy, label? }], information: [string] } */
260
+ async function doctorOperator(ws) {
261
+ const { operatorCoverage, operatorProblems, cacheOnlyRemote } = await import("../lib/operator-coverage.mjs");
262
+ const { discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
263
+ const deployment = dirname(ws.local.path);
264
+ const local = ws.local.value;
265
+ const remote = cacheOnlyRemote();
266
+ const remoteOptions = remoteOptionsFromEnv();
267
+ // Doctor reads the resolutions `oats souls` (and readiness, spawn) leave in the cache; `oats sync` alone
268
+ // does not resolve souls. Online, `oats readiness --soul <soul>` answers the same question.
269
+ const CACHE_REMEDY = "oats sync, then oats souls (it resolves every soul; doctor reads what that keeps), or online: oats readiness --soul <soul>";
270
+ let coverage, workspace = null, unknownRemedy = CACHE_REMEDY;
271
+ try {
272
+ const lock = readLockIfPresent(deployment);
273
+ const discovery = await discoverOrStandalone(local, { lock, deployment, remoteOptions, remote });
274
+ workspace = discovery.workspace?.name ?? null;
275
+ const labels = [...teamModel(discovery.standalone === true ? null : discovery.workspace, local, { workspaceKey: discovery.key ?? null }).labels.keys()].sort();
276
+ coverage = await operatorCoverage({ discovery, local, lock, teams: labels, remoteOptions, remote });
277
+ } catch (e) {
278
+ // A cache miss is the cache's; anything else (an invalid lock, which doctor reports above) is named as itself.
279
+ const missed = e?.code === "E_REMOTE_UNREADABLE";
280
+ coverage = { known: false, reason: missed ? `this machine's cache cannot answer (${e.message})` : `${e?.code ? `${e.code}: ` : ""}${e?.message ?? e}` };
281
+ if (!missed) unknownRemedy = "fix the error named here (doctor reports it), then run doctor again";
282
+ }
283
+ const found = operatorProblems(coverage, { workspace, unknownRemedy });
284
+ const unknown = found.find((p) => p.code === "operator-coverage-unknown");
285
+ if (unknown) return { problems: [], information: [`${unknown.code}: ${unknown.message}; ${unknown.remedy}`] };
286
+ return { problems: found.map(({ code, label, message, remedy }) => ({ code, ...(label ? { label } : {}), message, remedy })), information: [] };
287
+ }
288
+
255
289
  /** Workspace-model v2 doctor data, OFFLINE: the deployment declaration found
256
290
  * walking up from ctx (oats-local.yaml) and the lock v3 beside it. Doctor never
257
291
  * goes to the network for this view (only `--soul`, which resolves the soul like a
@@ -619,12 +653,13 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
619
653
  const agentsRoot = join(dirname(ws.local.path), "agents");
620
654
  const localTeams = doctorLocalTeams(ws.local.value);
621
655
  const schedules = unresolvedScheduleAttempts(dirname(ws.local.path));
622
- const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...localTeams.problems, ...schedules.problems].filter(Boolean);
656
+ const operator = await doctorOperator(ws);
657
+ const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...localTeams.problems, ...schedules.problems, ...operator.problems].filter(Boolean);
623
658
  return {
624
659
  schemaVersion: 1, workspaceApi: 2, context: ctx,
625
660
  workspace: { file: ws.local.path, ref: ws.local.workspace },
626
661
  workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
627
- information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information],
662
+ information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information],
628
663
  composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
629
664
  ...(problems.length ? { problems } : {}),
630
665
  };
@@ -664,7 +699,9 @@ async function doctor(dir) {
664
699
  for (const p of localTeams.problems) console.log(`\n! ${p.code} (${p.condition}): ${p.message}`);
665
700
  const schedules = unresolvedScheduleAttempts(dirname(ws.local.path));
666
701
  for (const p of schedules.problems) console.log(`\n! ${p.code}: ${p.message}`);
667
- for (const line of [...localTeams.information, ...schedules.information]) console.log(`\nINFO: ${line}`);
702
+ const operator = await doctorOperator(ws);
703
+ for (const p of operator.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
704
+ for (const line of [...localTeams.information, ...schedules.information, ...operator.information]) console.log(`\nINFO: ${line}`);
668
705
  if (soulName) {
669
706
  const information = operationalKnowledgeNote(composition, soulName);
670
707
  if (information) console.log(`\nINFO: ${information}`);
@@ -815,7 +852,8 @@ function launchPreview(bail) {
815
852
  // selection the planner refuses it (E_LAUNCH_LEGACY: re-spawn it from the deployment).
816
853
  let d, frozen;
817
854
  try { frozen = withSafeTaskPrompt(meta.command, meta.harness); d = describeLaunchCommand(frozen); } catch (e) { bail(e.code || "E_LAUNCH_COMMAND_UNSUPPORTED", e.message); }
818
- jsonOk({ context, selected, selection: { source: "frozen-command", launchConfig: null, harness: null, model: null, yolo: null }, harness: meta.harness, model: meta.model || null, modelSource: meta.model ? "recorded" : "native default", yolo: meta.yolo ?? null, launchConfig: null, launchConfigSource: null, launchConfigDefault: false, executable: { path: d.executable, declared: null, resolvedFrom: "recorded" }, argv: d.argv, environment: d.environment, command: redactLaunchCommand(frozen), prompt: { kind: "task-file", file: "TASK.md" }, hooks: null, preflight: [{ check: "recipe", ok: true, detail: "frozen command; a selection is refused (E_LAUNCH_LEGACY): re-spawn it" }], ok: true });
855
+ const launchPromptAnswers = launchPromptPolicyAt(dirname(dirname(dirname(dirname(home)))), home);
856
+ jsonOk({ context, selected, launchPromptAnswers, ...(launchPromptAnswers.awebDevelopmentChannel ? { warnings: [LAUNCH_PROMPT_UPDATE_WARNING] } : {}), selection: { source: "frozen-command", launchConfig: null, harness: null, model: null, yolo: null }, harness: meta.harness, model: meta.model || null, modelSource: meta.model ? "recorded" : "native default", yolo: meta.yolo ?? null, launchConfig: null, launchConfigSource: null, launchConfigDefault: false, executable: { path: d.executable, declared: null, resolvedFrom: "recorded" }, argv: d.argv, environment: d.environment, command: redactLaunchCommand(frozen), prompt: { kind: "task-file", file: "TASK.md" }, hooks: null, preflight: [{ check: "recipe", ok: true, detail: "frozen command; a selection is refused (E_LAUNCH_LEGACY): re-spawn it" }], ok: true });
819
857
  return;
820
858
  }
821
859
  const agentsRoot = agentsRootOfHome(home);
@@ -837,7 +875,7 @@ function launchPreview(bail) {
837
875
  const command = renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
838
876
  const d = describeLaunchCommand(command);
839
877
  const environment = d.environment.map((e) => e.reference && recipe.env[e.name]?.fromEnv ? { name: e.name, fromEnv: recipe.env[e.name].fromEnv } : e);
840
- jsonOk({ context, selected, selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, launchConfigDefault: recipe.launchConfigDefault === true, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
878
+ jsonOk({ context, selected, launchPromptAnswers: plan.launchPromptAnswers, ...(plan.warnings?.length ? { warnings: plan.warnings } : {}), selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, launchConfigDefault: recipe.launchConfigDefault === true, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
841
879
  }
842
880
  async function launchConfigCmd() {
843
881
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
@@ -1312,8 +1350,10 @@ const APPROVAL_REMOVED = "package approval was removed; declaring a package in p
1312
1350
  * `packages:` against the lock (commit + integrity), write the lock. There is no approval step:
1313
1351
  * declaring a package in `packages:` is the trust decision (human decision 2026-09-24).
1314
1352
  * `bail` never returns (it exits the process with the caller's error shape).
1353
+ * `plan` (#731, `oats sync --plan`): the same discovery, resolution and report, written nowhere —
1354
+ * no lock, no agents/, no automations snapshot; `lockFile` is the lock a sync would write.
1315
1355
  * → { report, lock, discovery, items, lockFile, problems } */
1316
- async function performSync(ctx, bail, { onDiscovered } = {}) {
1356
+ async function performSync(ctx, bail, { onDiscovered, plan = false } = {}) {
1317
1357
  if (args.includes("--approve")) return bail("E_BAD_ARGS", `--approve: ${APPROVAL_REMOVED}`, { flag: "--approve" });
1318
1358
  const catalog = catalogForSync(bail);
1319
1359
  const discovery = await discoverForCli(ctx, bail);
@@ -1333,8 +1373,9 @@ async function performSync(ctx, bail, { onDiscovered } = {}) {
1333
1373
  throw e;
1334
1374
  }
1335
1375
  const lock = resolved.lock;
1336
- let lockFile;
1337
- try { lockFile = writeLock(ctx.deploymentDir, lock); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
1376
+ let lockFile = join(resolve(ctx.deploymentDir), LOCK_FILE);
1377
+ // A plan validates the lock exactly as writeLock would (canonicalLock), so it never answers ok where the sync fails.
1378
+ try { if (plan) canonicalLock(lock); else lockFile = writeLock(ctx.deploymentDir, lock); } catch (e) { return bail(e.code || "E_LOCK_SCHEMA", e.message, e.details); }
1338
1379
  // Package souls come from the lock: list what THIS sync locked, not what the previous lock held.
1339
1380
  if (discovery.standalone !== true) {
1340
1381
  let pkg;
@@ -1348,19 +1389,22 @@ async function performSync(ctx, bail, { onDiscovered } = {}) {
1348
1389
  }
1349
1390
  // The deployment's instance root: <deployment>/agents/ (findRoot's marker). A hand-written
1350
1391
  // oats-local.yaml + sync is a complete deployment; spawn must not answer E_NO_DEPLOYMENT after it.
1351
- try { mkdirSync(join(ctx.deploymentDir, "agents"), { recursive: true }); } catch { /* reported by spawn's E_NO_DEPLOYMENT remedy if it matters */ }
1392
+ // A plan creates nothing: on a deployment that never synced, a schedule whose cwd is under agents/ is reported
1393
+ // invalid by the plan and accepted by the sync that creates agents/ first (#731 review, accepted edge).
1394
+ if (!plan) try { mkdirSync(join(ctx.deploymentDir, "agents"), { recursive: true }); } catch { /* reported by spawn's E_NO_DEPLOYMENT remedy if it matters */ }
1352
1395
  // Workspace automations (0.29.0): discovered with the members and the new lock (a trigger
1353
1396
  // template instantiates at the locked package commit), kept as the snapshot the host tick reads.
1354
1397
  let automations;
1355
- try { automations = await takeAutomationSnapshot(ctx, discovery, lock); }
1398
+ try { automations = await takeAutomationSnapshot(ctx, discovery, lock, { write: !plan }); }
1356
1399
  catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
1357
1400
  problems.push(...automations.problems);
1358
1401
  const members = memberRows(discovery);
1359
1402
  const packages = packageRows(lock);
1360
1403
  const changes = resolved.changes;
1361
1404
  const items = workspaceItems(discovery, lock, ctx.local, ctx.deploymentDir);
1362
- const report = { syncApi: 1, automations: automationCounts(automations), standalone: discovery.standalone === true || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, lock: lockFile }, members, packages, changes, problems, warnings: discovery.warnings ?? [] };
1363
- return { report, lock, discovery, items, lockFile, problems };
1405
+ const snapshotDue = plan && automationSnapshotDue(ctx.deploymentDir, automations);
1406
+ const report = { syncApi: 1, ...(plan ? { plan: true } : {}), automations: automationCounts(automations), standalone: discovery.standalone === true || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, url: discovery.url, commit: discovery.commit, observedAt: discovery.observedAt, local: ctx.localPath, lock: lockFile }, members, packages, changes, problems, warnings: discovery.warnings ?? [] };
1407
+ return { report, lock, discovery, items, lockFile, problems, snapshotDue };
1364
1408
  }
1365
1409
 
1366
1410
  /** The one-line standalone explanation (decision 10). `standaloneReason` says WHY the view is
@@ -1386,7 +1430,8 @@ function printSyncReport(ctx, synced) {
1386
1430
  console.log(`packages ${packages.map((p) => `${p.id} ${p.version} ✓ (@ ${short(p.commit)})`).join(" ") || "(none)"}`);
1387
1431
  const changed = changes.filter((c) => c.to !== null && c.from !== c.to).map((c) => `${c.id} ${c.from ?? "—"} → ${c.to} (@ ${short(c.commit)})`);
1388
1432
  const removed = changes.filter((c) => c.to === null).map((c) => `${c.id} ${c.from} → removed`);
1389
- console.log(`changed ${[...changed, ...removed].join(" ") || "(nothing — the lock already described this workspace)"}`);
1433
+ const plan = report.plan === true;
1434
+ console.log(`${plan ? "to change " : "changed "} ${[...changed, ...removed].join(" ") || `(nothing — the lock already ${plan ? "describes" : "described"} this workspace)`}`);
1390
1435
  const memberSouls = items.souls.filter((s) => s.kind === "member");
1391
1436
  const externalSouls = items.souls.filter((s) => s.kind === "external");
1392
1437
  // Souls have no private mode (0.26.0); the private count is of repo-owned member capabilities.
@@ -1400,22 +1445,24 @@ function printSyncReport(ctx, synced) {
1400
1445
  if (ac.triggers || ac.schedules) console.log(`automations ${ac.triggers} trigger${ac.triggers === 1 ? "" : "s"}, ${ac.schedules} schedule${ac.schedules === 1 ? "" : "s"} in the members (oats trigger list · oats schedule list)`);
1401
1446
  for (const p of synced.problems ?? discovery.problems) console.log(`problem ${p.code} ${p.repoKey ? `${memberLabel(p.repoKey)}:` : ""}${p.path} ${p.message}`);
1402
1447
  for (const w of discovery.warnings ?? []) console.log(`warning ${w.code} ${w.message}`);
1403
- console.log(`\nlock ${shortPath(lockFile)}`);
1448
+ if (plan) console.log(`\nplan nothing written: \`oats sync\` would write ${shortPath(lockFile)} ${changes.length ? "with the changes above" : "(unchanged)"}${synced.snapshotDue ? " and the automations snapshot" : ""}`);
1449
+ else console.log(`\nlock ${shortPath(lockFile)}`);
1404
1450
  }
1405
1451
 
1406
1452
  /** Discover the workspace automations of a discovery and write the snapshot the host tick reads
1407
1453
  * (lib/automations.mjs). A trigger's `from:` instantiates the package template at the lock's
1408
1454
  * commit; a schedule is checked against this deployment. → the snapshot */
1409
- async function takeAutomationSnapshot(ctx, discovery, lock) {
1455
+ async function takeAutomationSnapshot(ctx, discovery, lock, { write = true } = {}) {
1410
1456
  const kinds = await automationKinds(ctx.deploymentDir, lock, ctx.remoteOptions);
1411
1457
  const found = await A.discoverAutomations(discovery, { remote: kinds.remote, memberName: memberLabel, kinds: [kinds.trigger, kinds.schedule], previous: A.readSnapshot(ctx.deploymentDir) });
1412
1458
  const snap = A.snapshotOf(discovery, found, { souls: A.soulIndexOf(discovery, memberLabel) });
1413
1459
  // A workspace with no triggers or schedules leaves nothing behind (onboard creates what the
1414
1460
  // kernel needs and nothing else); a snapshot that existed is replaced, so a removal lands.
1415
- const empty = !snap.triggers.length && !snap.schedules.length && !snap.problems.length;
1416
- if (!empty || A.readSnapshot(ctx.deploymentDir)) A.writeSnapshot(ctx.deploymentDir, snap);
1461
+ if (write && automationSnapshotDue(ctx.deploymentDir, snap)) A.writeSnapshot(ctx.deploymentDir, snap);
1417
1462
  return snap;
1418
1463
  }
1464
+ /** Whether a sync writes this snapshot: it has entries, or one exists to replace. */
1465
+ const automationSnapshotDue = (dep, snap) => !!(snap.triggers.length || snap.schedules.length || snap.problems.length || A.readSnapshot(dep));
1419
1466
  /** The two kinds' descriptors (lib/triggers.mjs triggerKind, lib/schedule.mjs scheduleKind). */
1420
1467
  async function automationKinds(dep, lock, remoteOptions) {
1421
1468
  const T = await import("../lib/triggers.mjs");
@@ -1483,11 +1530,33 @@ function setDisabledHereCli(ws, kind, qid, enabled) {
1483
1530
  return A.setDisabledHere(path, kind, qid, !enabled, { validate: validateLocal });
1484
1531
  }
1485
1532
 
1486
- /** `oats sync [--dir] [--json]` — contract §6. */
1533
+ const SYNC_USAGE = "usage: oats sync [--dir <deployment>] [--plan] [--json]";
1534
+ /** Why `oats sync`'s argv is not a sync, or undefined (#731): an unknown flag or a positional is refused
1535
+ * before anything is read or written, never ignored. `--approve` keeps its own refusal (performSync). */
1536
+ function syncArgvProblem(argv) {
1537
+ let dirs = 0;
1538
+ for (let i = 1; i < argv.length; i++) {
1539
+ const a = argv[i];
1540
+ if (a === "--json" || a === "--plan") continue;
1541
+ if (a === "--dir") {
1542
+ if (dirs++) return { message: `oats sync: give --dir once\n${SYNC_USAGE}`, details: { flag: a } };
1543
+ if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) i++;
1544
+ continue;
1545
+ }
1546
+ if (a === "--approve") return { message: `--approve: ${APPROVAL_REMOVED}`, details: { flag: a } };
1547
+ if (a.startsWith("-")) return { message: `oats sync: unknown flag ${a}\n${SYNC_USAGE}`, details: { flag: a } };
1548
+ return { message: `oats sync: unexpected argument ${JSON.stringify(a)}: sync takes no positional (the deployment is --dir <deployment>)\n${SYNC_USAGE}`, details: { argument: a } };
1549
+ }
1550
+ return undefined;
1551
+ }
1552
+
1553
+ /** `oats sync [--dir] [--plan] [--json]` — contract §6. `--plan` previews: the same report, nothing written. */
1487
1554
  async function syncCmd() {
1488
1555
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
1556
+ const problem = syncArgvProblem(args);
1557
+ if (problem) return bail("E_BAD_ARGS", problem.message, problem.details);
1489
1558
  const ctx = workspaceContext(bail);
1490
- const synced = await performSync(ctx, bail);
1559
+ const synced = await performSync(ctx, bail, { plan: args.includes("--plan") });
1491
1560
  // One envelope (or the §8 report); success is exit 0 (a failure bails with its code).
1492
1561
  if (JSON_MODE) jsonOk(synced.report); else printSyncReport(ctx, synced);
1493
1562
  }
@@ -4092,13 +4161,15 @@ Usage:
4092
4161
  --soul shows final composed AGENTS.md
4093
4162
  oats update [--check] [--yes] check npm for a newer kernel+pi bridge and
4094
4163
  optionally run the update; then run oats doctor
4095
- oats sync [--dir <d>] [--json] workspace model v2: observe the workspace named by
4164
+ oats sync [--dir <d>] [--plan] [--json] workspace model v2: observe the workspace named by
4096
4165
  oats-local.yaml over its Git remote, confirm every
4097
4166
  member (reciprocal oats-membership.yaml), resolve
4098
4167
  packages: to exact commits + integrity, write
4099
- oats-lock.json (v3) and report the diff. No approval
4100
- step: declaring a package in packages: is the trust
4101
- decision (--approve is E_BAD_ARGS)
4168
+ oats-lock.json (v3) and report the diff. --plan:
4169
+ the same report, nothing written (what a bare sync
4170
+ would change). No approval step: declaring a
4171
+ package in packages: is the trust decision
4172
+ (--approve is E_BAD_ARGS)
4102
4173
  oats package add <id> <version|git:<repo>@<ref>> edit packages: in oats-workspace.yaml when the
4103
4174
  | remove <id> [--dir <d>] workspace repo is the current checkout; otherwise
4104
4175
  print the line to add (the file travels through Git)
@@ -953,7 +953,13 @@ passed as arguments; no shell is involved.
953
953
  [Teams in the provider environment](#teams-in-the-provider-environment)),
954
954
  `OATS_TEAM_SCOPE`, `OATS_TEAM_NAME`, `OATS_WORKSPACE_NAME` and
955
955
  `OATS_WORKSPACE_KEY`;
956
- - `OATS_AGENT` (the soul);
956
+ - `OATS_AGENT` and (0.44.0) `OATS_SOUL_ID`, the soul's name and stable id
957
+ with the values its hooks and dispatched commands get (see
958
+ [Commands and hooks](#commands-and-hooks)). For `--soul` on a package
959
+ soul, `OATS_AGENT` is its agents-root name `<package>--<soul>`
960
+ ([Package souls](packages.md#package-souls)), as its hooks get it (before
961
+ 0.44.0, the bare soul name). A check that relies on them declares
962
+ `compatibility.oats: ">=0.44.0"`;
957
963
  - `OATS_SOUL`, the soul directory: a home's recorded one, or for a soul
958
964
  (`readiness --soul`, `inspect --soul`) its copy at the resolved commit,
959
965
  which the kernel materialises first as a spawn would (0.30; a copy that
@@ -60,6 +60,7 @@ refused (`E_WORKSPACE_SCHEMA`).
60
60
  | `workspace` | Repo ref of the workspace host (`git:host/org/repo`, `https://…`, `git@host:…`, `file:///…`, `/abs/bare.git`). Read with your own Git credentials; it need not be cloned. |
61
61
  | `standalone` | A repo ref to realize on its own: its souls and `from: here` capabilities plus `oats.core`, with no workspace lookup. For a repository whose workspace this machine cannot read ([workspaces.md](workspaces.md#the-standalone-case)). |
62
62
  | `clones` | `<repo key>: <absolute path>` for a member clone that is not at `<deployment>/<member name>/`. Only a soul whose work target needs a clone (`work: worktree \| checkout`) uses it. Lookup order: `spawn --repo`, then this map, then `<deployment>/<member name>` (a member named `agents` → `<deployment>/agents-repo`). None → `E_CLONE_MISSING`; a directory whose `origin` is another repository → `E_CLONE_MISMATCH`. |
63
+ | `launchPromptAnswers.homes.<absolute-home>` | Explicit per-home `awebDevelopmentChannel` boolean consent; defaults false. See [launch prompt consent](#exact-home-launch-prompt-consent). |
63
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)). |
64
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>`. |
65
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. |
@@ -77,6 +78,70 @@ Which teams a soul may join, and its default, are committed in the workspace's
77
78
  commit instead). How teams are resolved, and what a messaging provider does
78
79
  with them, is in [workspaces.md](workspaces.md#teams).
79
80
 
81
+ ## Exact-home launch prompt consent
82
+
83
+ `launchPromptAnswers` belongs only in the host's `oats-local.yaml`. It is
84
+ refused in workspace and soul declarations. Add an entry only for a home whose
85
+ owner has explicitly authorized Claude's aweb development-channel confirmation:
86
+
87
+ ```yaml
88
+ launchPromptAnswers:
89
+ homes:
90
+ /absolute/canonical/instance/home:
91
+ awebDevelopmentChannel: false
92
+ ```
93
+
94
+ `awebDevelopmentChannel` is a strict boolean; absent means `false`. Unknown keys
95
+ are refused. `workspaceTrust` is unsupported: remove it and handle folder trust
96
+ with the harness. Folder-trust automation is separate work in
97
+ [oats#712](https://github.com/awebai/oats/issues/712); it is not enabled here.
98
+ Each home key is an exact absolute canonical path, with no symlink alias,
99
+ wildcard, dot segment, trailing separator, ancestor inheritance or soul-wide
100
+ default. A home not yet created uses its resolved existing directory ancestor
101
+ plus its intended suffix; launch checks the created home's identity again.
102
+ No existing home is enabled automatically. Removing an entry disables consent
103
+ for future launches.
104
+
105
+ The sole confirmation covered is Claude's development-channel prompt for
106
+ `plugin:aweb-channel@awebai-marketplace`. The provider's `claudeChannelMode`
107
+ selects arguments; it does not grant consent. Approved-mode arguments, another
108
+ plugin, multiple plugins or contradictory channel arguments cannot qualify.
109
+ Environment values, spawn flags and saved launch recipes cannot enable consent.
110
+ Existing harness folder-trust configuration remains independent.
111
+
112
+ Preview reports effective `launchPromptAnswers.awebDevelopmentChannel` and
113
+ `consentSource` without terminal capture or input. `--no-launch` never answers.
114
+ The qualified fixture is limited to Claude 2.1.289 on `darwin-arm64`, at terminal
115
+ geometry 110 columns by 35 rows, with executable SHA-256
116
+ `03d66745e3bb69ec727d66023696f3820bc0a00a8a5ba725eb6706d0c67cbe69`.
117
+ The launch must satisfy these guards and the exact complete frame, selection
118
+ and argument checks. Reported version alone is insufficient; another
119
+ executable, platform, geometry or prompt variant does not inherit acceptance.
120
+ The qualified channel frame starts on its accepted option and permits one
121
+ Enter only. Folder-trust and API-key questions remain unexpected and block.
122
+ A qualified normal-output boundary closes observation without asserting readiness.
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. Only the bounded canonical-home directory line may vary.
128
+ Other model, billing, effort or permission banners remain unqualified: the one
129
+ Enter can be submitted before `E_SPAWN_INCOMPLETE` with
130
+ `launchPrompts.status: blocked`. The submitted answer remains in `answers` and
131
+ the event receipt; the pane may already be active. Inspect the retained target;
132
+ do not automatically retry input or relaunch it. The installed capture used an
133
+ isolated configuration and dummy credentials with runtime network denied. It
134
+ proves bounded UI completion, not live-account admission, connection or native
135
+ receive readiness, and does not establish success for every production setup.
136
+
137
+ When a harness update changes the version-bound prompt frame, opted-in homes
138
+ block again with `blocked: unexpected prompt` until fixtures are refreshed.
139
+ There is no fallback keystroke or broader matching rule. The returned
140
+ `launchPrompts.receipt` identifies the launch-prompt event receipt; the home
141
+ and pane are retained for inspection. See [launch outcomes](execution-targets.md#launch-prompt-outcomes)
142
+ for recovery. Answering a confirmation never establishes harness or messaging
143
+ receive readiness.
144
+
80
145
  ## Launch configurations
81
146
 
82
147
  An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
@@ -447,7 +447,10 @@ oats readiness (--home <abs> | --soul <name> [--dir <d>]) [--policy] --json
447
447
  - Four checks, each `{status, items}`. An item is `{subject, status,
448
448
  required, reason, producer, evidence, remedy}`, plus `capability: {id}` on a
449
449
  per-capability item and the keys named below. Statuses are `pass | fail |
450
- unknown | not-applicable`.
450
+ unknown | not-applicable`. An item's `reason`, `remedy` and kernel
451
+ `problems[].message` are at most 1000 characters (0.44.0). Longer text,
452
+ such as a remote error, is clipped with `…`. A provider's `result` is
453
+ relayed verbatim.
451
454
  - A check's status rolls up its required items (any `fail` → `fail`, else any
452
455
  `unknown` → `unknown`, else `pass`; `not-applicable` with none required).
453
456
  - `summary.ready` is true when every required item passes or is
@@ -467,6 +470,8 @@ naming `oats sync`; team refusals go under `configured` instead.
467
470
  **`configured`.** Producer `capability manifest`: each manifest `requires`
468
471
  command, `evidence: {command}`, the manifest's `install` hint as remedy.
469
472
  Producer `team model`: the soul's [team readiness items](#team-readiness-items).
473
+ Producer `operator coverage` (0.44.0): the workspace's and the soul's teams'
474
+ [operator coverage items](#operator-coverage-items), warnings only.
470
475
 
471
476
  **`member`** (producer `workspace discovery`): the soul's repository is a
472
477
  confirmed member (`evidence: {repoKey, workspace, commit}`); `fail` when not
@@ -672,13 +677,22 @@ same argument, given once). The ref is checked before anything is written.
672
677
  ### `oats sync`
673
678
 
674
679
  ```text
675
- oats sync [--dir <d>] --json
680
+ oats sync [--dir <d>] [--plan] --json
676
681
  ```
677
682
 
678
683
  Discovers the workspace, confirms membership, resolves `packages:`, writes
679
684
  `oats-lock.json` (lockfileVersion 3), takes the automations snapshot and
680
685
  reports. It creates `agents/` if missing.
681
686
 
687
+ `--plan` (0.44.0) previews: the same discovery, resolution and report, with
688
+ `plan: true`, and nothing written (no lock, no `agents/`, no automations
689
+ snapshot; the remote cache fills as any read fills it). `changes[]` is what a
690
+ bare `oats sync` would apply, `workspace.lock` the lock it would write, and
691
+ `automations` counts what it would snapshot. A flag or a positional `sync` does
692
+ not read is refused with `E_BAD_ARGS` (`details: {flag}` or `{argument}`) before
693
+ anything is read or written. A kernel before 0.44.0 ignores `--plan` and
694
+ applies: gate `sync --plan` on `version` 0.44.0 or later, never by trying.
695
+
682
696
  ```json
683
697
  {"syncApi":1,"automations":{"triggers":3,"schedules":2,"problems":1,"takenAt":"2026-09-26T19:58:09.281Z"},
684
698
  "workspace":{"name":"acme","key":"github.com/acme/agents","url":"https://github.com/acme/agents.git","commit":"45b86f64…",
@@ -693,6 +707,7 @@ reports. It creates `agents/` if missing.
693
707
  "problems":[],"warnings":[]}
694
708
  ```
695
709
 
710
+ - `plan`: `true` on a `--plan` answer, absent otherwise.
696
711
  - `automations`: counts from the snapshot this sync took.
697
712
  - `workspace.name` is `standalone:<repo>` on a standalone view.
698
713
  - `members[]`: `status` is `confirmed | not-listed | no-backlink |
@@ -1098,7 +1113,10 @@ operator guide: [workspaces.md](workspaces.md#teams).
1098
1113
  home's own record, as always.
1099
1114
  - **A soul's key** is its qualified name: `<package>/<soul>`, or
1100
1115
  `<member>/<soul>` with the member repository's name (as `souls.disabled`
1101
- names it). A label matches `[a-z0-9][a-z0-9._-]*`.
1116
+ names it). A label matches `[a-z0-9][a-z0-9._-]*` and is at most 64
1117
+ characters (0.44.0). A longer one is refused: `E_WORKSPACE_SCHEMA` in
1118
+ either file, `E_BAD_ARGS` from `oats teams add`, and `E_TRIGGER_INVALID`
1119
+ (`field: spawn.teams`) in a trigger.
1102
1120
  - **Team ids.** A `team` value (in either file, and `oats teams add --team`)
1103
1121
  matches `^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,255}$`: the kernel's safety rule
1104
1122
  (never `-`-led, no whitespace or control characters, bounded). Otherwise
@@ -1324,6 +1342,77 @@ hasn't observed its workspace yet; run oats sync"`. A removed key in
1324
1342
  `oats-local.yaml` makes doctor answer that refusal, as for any unreadable
1325
1343
  local file.
1326
1344
 
1345
+ <a id="operator-coverage-items"></a>
1346
+ ### Operator coverage items
1347
+
1348
+ (0.44.0, [#671](https://github.com/awebai/oats/issues/671)) Every workspace
1349
+ needs an operator: a soul that composes `oats.setup`. A soul the workspace
1350
+ offers **covers** it when all of these hold on this machine:
1351
+
1352
+ - it is a confirmed member's soul, a locked package soul or an external soul;
1353
+ - it is not in `souls.disabled`;
1354
+ - it resolves as a spawn would;
1355
+ - its modules include `oats.setup`;
1356
+ - it empties no layer slot the workspace fills, so it keeps the workspace's
1357
+ core, messaging and knowledge.
1358
+
1359
+ It covers a team when that team is among its resolved teams. Detection is by
1360
+ composition only: a soul's name never counts, and there is no role marker. An
1361
+ eligible soul is not a launched or authorized seat. These are warnings: they
1362
+ never refuse anything, and nothing is spawned.
1363
+
1364
+ `oats readiness` lists them under `checks.configured` with `producer:
1365
+ "operator coverage"`, `required: false`, `code`, `reason` and `remedy`. Team
1366
+ items cover the subject's own teams only.
1367
+
1368
+ | Code | Subject | Status | Keys | When |
1369
+ |---|---|---|---|---|
1370
+ | `operator-soul-missing` | `operator` | `fail` | `evidence.excluded` | no soul the workspace offers composes `oats.setup` |
1371
+ | `operator-team-uncovered` | `team <label>` | `fail` | `label` | no such soul is eligible for one of the subject's teams |
1372
+ | `operator-coverage-unknown` | `operator` | `unknown` | | a question is still open and a source could not be read; it never asserts absence |
1373
+
1374
+ A source could not be read when:
1375
+
1376
+ - the workspace itself could not be read;
1377
+ - only its member view could (an unreadable host);
1378
+ - discovery dropped a member as `cannot-read`;
1379
+ - a soul file or listing could not be read;
1380
+ - a resolution hit `E_REMOTE_UNREADABLE`.
1381
+
1382
+ A covering soul that was found is still reported. Any other refusal belongs to
1383
+ the soul, since a spawn would meet it too, so that soul does not cover.
1384
+
1385
+ `evidence.excluded` lists the souls that cannot cover although they are
1386
+ relevant, each as `{soul, code}`:
1387
+
1388
+ - a soul whose `soul.yaml` names `oats.setup` but that is disabled
1389
+ (`E_SOUL_DISABLED`), ambiguous (`E_SOUL_AMBIGUOUS`) or refused (the
1390
+ resolution's code);
1391
+ - a soul that composes `oats.setup` but empties a slot the workspace fills
1392
+ (`slot-none`, with `slots`).
1393
+
1394
+ Coverage that holds adds no item.
1395
+
1396
+ `oats doctor` stays offline. It resolves the souls from this machine's cache
1397
+ only (no git process, no network) and checks the workspace and **every**
1398
+ declared team. It lists `operator-soul-missing` and `operator-team-uncovered`
1399
+ under `problems[]` as `{code, label?, message, remedy}` (text: `! <code>:
1400
+ <message>`, then the remedy).
1401
+
1402
+ Doctor reads the resolutions that `oats souls`, readiness and spawn keep in the
1403
+ cache. `oats sync` alone does not resolve souls. When the cache cannot answer,
1404
+ doctor adds no problem. Instead it adds one `information[]` line, starting
1405
+ `operator-coverage-unknown:`, whose remedy is `oats sync`, then `oats souls`.
1406
+ The cache cannot answer when:
1407
+
1408
+ - the machine never synced;
1409
+ - the cache was pruned;
1410
+ - a soul was not yet resolved here;
1411
+ - the deployment uses a configured `standalone:` view, whose membership read
1412
+ is not cached. There, ask readiness.
1413
+
1414
+ Any other error, such as an invalid lock, is named as itself.
1415
+
1327
1416
  <a id="soul-launch-preferences-feature-launch-preference-oats-0300"></a>
1328
1417
  ## Launch preferences
1329
1418
 
@@ -1460,6 +1549,48 @@ shows the drift as `launch-changed`.
1460
1549
  No verb writes `souls.launch`; it is plain YAML. A GUI that edits it checks
1461
1550
  the result with `oats inspect --soul <name> --json`.
1462
1551
 
1552
+ ## Launch prompt results
1553
+
1554
+ Spawn preview adds `launchPromptAnswers` with the strict effective boolean
1555
+ `awebDevelopmentChannel` and `consentSource` (a config-file
1556
+ JSON pointer or `null`). This is a policy report, not a terminal observation
1557
+ or readiness assertion. Only the aweb development-channel confirmation is
1558
+ covered, restricted to the qualified Claude executable digest, platform and
1559
+ geometry documented under [launch consent](configuration.md#exact-home-launch-prompt-consent).
1560
+ Folder-trust prompts remain unexpected and blocked.
1561
+
1562
+ An observed launch has `launchPrompts: {status, answers, reason, receipt}`.
1563
+ `receipt` carries the actual checked launch-prompt event-write results,
1564
+ including partial log availability; it is not a receive-readiness receipt.
1565
+ The `launch-prompt` event records the launch start and pane/PID identity,
1566
+ consent provenance, signature identifier/digest, action and outcome. Intent is
1567
+ durable before input; submission (`submitted`, `failed`, `uncertain`) and an
1568
+ observed screen transition are distinct. Unexpected raw screen text is never
1569
+ included in the receipt.
1570
+
1571
+ Spawn and start both reuse `E_SPAWN_INCOMPLETE` for retained prompt outcomes,
1572
+ with `launchPrompts.status` set to `blocked` or `incomplete`. Error details
1573
+ preserve `instance`, `home`, `launched:"unknown"`, `unconfirmed:true` and add
1574
+ `retained:true`, `target`,
1575
+ `parentLineageCommitted`, and `launchPrompts`. Unknown prompts report
1576
+ `blocked: unexpected prompt`. An incomplete audit can follow a possible key;
1577
+ clients must not offer automatic key retry. `launched:false` in retained
1578
+ metadata does not mean there is no process or that another harness may be
1579
+ allocated. Use runtime inspection and the existing start/restart lifecycle.
1580
+ Same-key spawn replay cannot convert a blocked outcome to successful spawn.
1581
+
1582
+ `answers` can contain a `submitted` answer even when the final status is
1583
+ `blocked`: the accepted installed-plugin and plugin-absent completion banners
1584
+ pin specific model/billing/effort/permission text. A different normal-looking banner can block after Enter
1585
+ while the actual pane is active. Consumers must preserve that submitted receipt
1586
+ and never translate this outcome into “nothing started” or automatic retry.
1587
+ The [completion limitation](configuration.md#exact-home-launch-prompt-consent)
1588
+ is part of the shipping contract.
1589
+
1590
+ Strict Desktop/pi readers must accept these additive fields and the new event
1591
+ kind before a writer containing them ships. For operator recovery, see
1592
+ [launch prompt outcomes](execution-targets.md#launch-prompt-outcomes).
1593
+
1463
1594
  ## Spawn
1464
1595
 
1465
1596
  ### The preview
@@ -1702,7 +1833,7 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
1702
1833
  | `E_INSTANCE_NAME_INVALID`, `E_INSTANCE_NAME_TAKEN` | see above | |
1703
1834
  | `E_DECISION_STALE` | `{decision}` | |
1704
1835
  | `E_PLACEMENT_TAKEN`, `E_IDEMPOTENCY_CONFLICT` | `{instance, home}` | |
1705
- | `E_SPAWN_INCOMPLETE` | `{instance, home, launched, unconfirmed: true}` | |
1836
+ | `E_SPAWN_INCOMPLETE` | `{instance, home, launched, unconfirmed: true}`; retained launch-prompt outcomes additionally carry `{retained: true, target, parentLineageCommitted, launchPrompts}` | See [launch prompt results](#launch-prompt-results). |
1706
1837
  | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
1707
1838
  | `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
1708
1839
  | `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
@@ -2761,6 +2892,20 @@ selection flags. See [the start workflow](desktop-instance-start.md).
2761
2892
  - Restart is one command: the kernel validates the new selection before
2762
2893
  stopping, and owns the stop, lock, launch recovery and metadata. Never
2763
2894
  restart by retiring and spawning.
2895
+ - Launch recovery (0.44.0). A start keeps its launch receipt in the home
2896
+ until the next start replaces it. The next start **adopts** a receipt only
2897
+ for a start `instance.json` does not record (one whose metadata write
2898
+ failed): it records that target and launches nothing again. A receipt for
2899
+ a start `instance.json` already records, on the target it records, is
2900
+ **completed**, and none of it is recorded again: a newer launch recipe or
2901
+ provider metadata stays. A plain start then answers `E_SESSION_RUNNING`
2902
+ while that target runs, writing nothing and running no hook; a restart, or
2903
+ a start after the target is gone or the harness exited, starts from
2904
+ `instance.json` as it is, and its own receipt replaces the old one. A
2905
+ receipt that names the recorded start on another target is ambiguous:
2906
+ `E_SESSION_UNKNOWN`, the receipt kept, nothing started. The message names
2907
+ that target and the way out: stop it, then `oats session restart`, which
2908
+ goes ahead once that target no longer runs. Never edit or remove a receipt by hand.
2764
2909
  - A lost response does not mean the launch failed: check status before a
2765
2910
  retry. A remote home's saved route names its execution host.
2766
2911
  - Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,