@awebai/oats 0.43.2 → 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 (34) hide show
  1. package/bin/oats.mjs +119 -37
  2. package/docs/capabilities.md +37 -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/knowledge.md +2 -1
  8. package/docs/oats-local.schema.json +19 -1
  9. package/docs/oats-workspace.schema.json +1 -1
  10. package/docs/release-notes/v0.43.3.md +22 -0
  11. package/docs/release-notes/v0.44.0.md +161 -0
  12. package/docs/schedules.md +27 -9
  13. package/docs/souls-and-instances.md +7 -0
  14. package/lib/core.mjs +254 -88
  15. package/lib/instance-events.mjs +1 -1
  16. package/lib/instance-inspect.mjs +39 -6
  17. package/lib/launch-prompt-fixtures/README.md +49 -0
  18. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +35 -0
  19. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +35 -0
  20. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +35 -0
  21. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +35 -0
  22. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +77 -0
  23. package/lib/launch-prompt-fixtures.mjs +114 -0
  24. package/lib/launch-prompt-policy.mjs +73 -0
  25. package/lib/launch-prompt-transport.mjs +102 -0
  26. package/lib/launch-prompts.mjs +216 -0
  27. package/lib/operator-coverage.mjs +134 -0
  28. package/lib/remote.mjs +15 -9
  29. package/lib/schedule.mjs +57 -10
  30. package/lib/teams-verbs.mjs +3 -3
  31. package/lib/triggers.mjs +2 -2
  32. package/lib/workspace.mjs +20 -2
  33. package/package.json +1 -1
  34. 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, 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
  }
@@ -3094,10 +3163,13 @@ async function capabilityCommand() {
3094
3163
  // as a spawn preview reads it (the per-commit copy a spawn left under the agents root, else a
3095
3164
  // temporary fetch removed when the command ends). Read only when the command runs (after its
3096
3165
  // --help). A soul that cannot be read refuses the command: it never runs with OATS_SOUL unset.
3166
+ // Its name and stable id are the ones a spawn of it records and hands its hooks (OATS_AGENT,
3167
+ // OATS_SOUL_ID): the agents-root name and the prepared entry's id, never the copy's path.
3097
3168
  const soul = async () => {
3098
- const { previewWorkspaceSoul } = await import("../lib/instance-resolution.mjs");
3169
+ const { previewWorkspaceSoul, agentDirOf } = await import("../lib/instance-resolution.mjs");
3099
3170
  const entry = hit.prepared?.soulEntry;
3100
- try { const p = await previewWorkspaceSoul(hit.prepared, join(hit.deployment, "agents")); return { dir: p.soulDir, cleanup: p.cleanup }; }
3171
+ const identity = entry ? { agent: agentDirOf(entry), id: preparedSoulIdOf(entry) } : {};
3172
+ try { const p = await previewWorkspaceSoul(hit.prepared, join(hit.deployment, "agents")); return { dir: p.soulDir, cleanup: p.cleanup, ...identity }; }
3101
3173
  catch (e) {
3102
3174
  throw Object.assign(new Error(`oats ${cmd}: cannot read soul ${flag("soul")} at ${String(entry?.commit ?? "?").slice(0, 12)}, so the command would run without OATS_SOUL; nothing was run: ${e.message}`),
3103
3175
  { code: typeof e?.code === "string" && e.code.startsWith("E_") ? e.code : "E_REMOTE_UNREADABLE", details: { soul: flag("soul"), repoKey: entry?.repoKey ?? null, commit: entry?.commit ?? null } });
@@ -3177,7 +3249,10 @@ async function capabilityCommand() {
3177
3249
  catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details); throw e; }
3178
3250
  teamCtx = homeTeamCtx(live);
3179
3251
  }
3180
- return runManifestCommand(m, { settings: capSettings[m.capability] || {}, origins: capOrigins[m.capability] }, teamCtx, () => m._dir, () => ({ dir: soulDir, cleanup: () => {} }));
3252
+ // The home's soul as its lifecycle hooks get it: the recorded name and stableSoulId's id.
3253
+ const agent = homeMeta.meta.agent;
3254
+ return runManifestCommand(m, { settings: capSettings[m.capability] || {}, origins: capOrigins[m.capability] }, teamCtx, () => m._dir,
3255
+ () => ({ dir: soulDir, cleanup: () => {}, agent, id: stableSoulId({ home: instanceHome, soulDir, agentName: agent }) }));
3181
3256
  }
3182
3257
 
3183
3258
  /** Help / unknown-command / spec validation / exec — shared by every context.
@@ -3218,14 +3293,15 @@ async function capabilityCommand() {
3218
3293
  try { abs = capabilityExecutablePath(withDir, script); }
3219
3294
  catch (e) { bail("E_CAPABILITY_BROKEN", e.message); }
3220
3295
  if (!abs) bail("E_CAPABILITY_BROKEN", `${cmd} ${sub}: script not found (${join(dir, script)})`);
3221
- // The soul the command acts for → { dir, cleanup }: a home's recorded soul directory, or (operator
3222
- // dispatch) the soul read at its resolved commit, whose temporary copy goes when this process exits.
3223
- let soulDir;
3224
- try { const read = await soul(); soulDir = read.dir; process.once("exit", read.cleanup); }
3296
+ // The soul the command acts for → { dir, cleanup, agent, id }: a home's recorded soul directory, or
3297
+ // (operator dispatch) the soul read at its resolved commit, whose temporary copy goes when this
3298
+ // process exits; with its name and stable id, as the soul's lifecycle hooks get them.
3299
+ let soulDir, soulAgent, soulId;
3300
+ try { const read = await soul(); soulDir = read.dir; soulAgent = read.agent; soulId = read.id; process.once("exit", read.cleanup); }
3225
3301
  catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) bail(e.code, e.message, e.details); throw e; }
3226
- // OATS_SOUL is the recorded soul or nothing: an ambient value inherited from the
3227
- // invoking process names some other soul (a coordinator's own), never this one.
3228
- const { OATS_SOUL: _ambientSoul, ...inherited } = process.env;
3302
+ // OATS_SOUL, OATS_AGENT and OATS_SOUL_ID are this command's soul or nothing: an ambient value
3303
+ // inherited from the invoking process names some other soul (a coordinator's own), never this one.
3304
+ const { OATS_SOUL: _ambientSoul, OATS_AGENT: _ambientAgent, OATS_SOUL_ID: _ambientSoulId, ...inherited } = process.env;
3229
3305
  await readSession?.closeBatches(); // no idle `git cat-file --batch` child held for the provider's whole run
3230
3306
  const r = spawnSync("node", [abs, ...rest, ...rawArgs.slice(2)], { stdio: "inherit", env: {
3231
3307
  ...inherited, OATS_CAPABILITY: m.capability,
@@ -3245,6 +3321,10 @@ async function capabilityCommand() {
3245
3321
  // The soul the command acts for (an instance home's recorded soul directory):
3246
3322
  // homes carry no soul link, so providers read it here.
3247
3323
  ...(soulDir ? { OATS_SOUL: soulDir } : {}),
3324
+ // Its name and stable identity, the values its hooks get: what a provider keys durable state
3325
+ // on (OATS_SOUL is a per-commit or temporary copy, so never a key).
3326
+ ...(typeof soulAgent === "string" && soulAgent ? { OATS_AGENT: soulAgent } : {}),
3327
+ ...(typeof soulId === "string" && soulId ? { OATS_SOUL_ID: soulId } : {}),
3248
3328
  } });
3249
3329
  // Child never ran (spawn error): nothing reached stdout — keep the envelope contract.
3250
3330
  if (r.error) bail("E_CAPABILITY_BROKEN", `oats ${cmd} ${sub}: ${r.error.message || r.error}`);
@@ -4081,13 +4161,15 @@ Usage:
4081
4161
  --soul shows final composed AGENTS.md
4082
4162
  oats update [--check] [--yes] check npm for a newer kernel+pi bridge and
4083
4163
  optionally run the update; then run oats doctor
4084
- 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
4085
4165
  oats-local.yaml over its Git remote, confirm every
4086
4166
  member (reciprocal oats-membership.yaml), resolve
4087
4167
  packages: to exact commits + integrity, write
4088
- oats-lock.json (v3) and report the diff. No approval
4089
- step: declaring a package in packages: is the trust
4090
- 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)
4091
4173
  oats package add <id> <version|git:<repo>@<ref>> edit packages: in oats-workspace.yaml when the
4092
4174
  | remove <id> [--dir <d>] workspace repo is the current checkout; otherwise
4093
4175
  print the line to add (the file travels through Git)
@@ -443,6 +443,36 @@ A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
443
443
  preview (only a preview-aware hook does, below); on a real run
444
444
  `OATS_LAUNCH_PREVIEW` is not set.
445
445
 
446
+ A dispatched command (`oats <namespace> <command>`, from an instance home or
447
+ from the deployment directory) receives:
448
+
449
+ - `OATS_CAPABILITY`;
450
+ - `OATS_CLI_BIN`;
451
+ - `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`: the home's recorded payload, or
452
+ the soul's merged payload from the deployment;
453
+ - the team and workspace variables, as hooks get them;
454
+ - `OATS_SOUL`: the home's recorded soul directory, or from the deployment the
455
+ soul's source at the resolved commit (the copy a spawn left under the
456
+ agents root, else a temporary copy removed when the command ends). It is a
457
+ per-commit or temporary path, so a provider never keys durable state on it;
458
+ - `OATS_AGENT` and `OATS_SOUL_ID` (0.43.3), with the values that soul's
459
+ hooks get: the soul's agents-root name (`<package>--<soul>` for a package
460
+ soul, see [Package souls](packages.md#package-souls)) and its stable id
461
+ (`<repoKey>#<soul>`, or `package:<id>#<soul>`; for a home, the id its
462
+ spawn recorded). One soul gives the same values from its home, from the
463
+ deployment (with `--soul` or as the default soul) and in its hooks. Key
464
+ durable per-soul state on `OATS_SOUL_ID`. A provider that relies on them
465
+ declares `compatibility.oats: ">=0.43.3"`: an earlier kernel sets
466
+ neither, so a value a command sees there is the caller's.
467
+
468
+ An `OATS_SOUL`, `OATS_AGENT` or `OATS_SOUL_ID` in the caller's environment is
469
+ removed: it names another soul (a coordinator's, an outer command's). With
470
+ no soul, the variable is absent. The kernel sets no other hook variable
471
+ (`OATS_EVENT`, `OATS_LAYER`, `OATS_LEVEL`, `OATS_CONTEXT`, `OATS_WORKSPACE`,
472
+ `OATS_ROOT`, `OATS_META`, the spawn and launch extras). `OATS_INSTANCE`,
473
+ `OATS_INSTANCE_HOME` and `OATS_HOME` are neither set nor removed: inside an
474
+ instance session they are the session's.
475
+
446
476
  `OATS_SETTINGS_ORIGINS` says where each leaf of
447
477
  `OATS_SETTINGS` came from: a JSON object from a JSON pointer to `{ kind, at }`,
448
478
  `kind` being `manifest-default`, `workspace`, `soul`, `host`, `spawn` or
@@ -923,7 +953,13 @@ passed as arguments; no shell is involved.
923
953
  [Teams in the provider environment](#teams-in-the-provider-environment)),
924
954
  `OATS_TEAM_SCOPE`, `OATS_TEAM_NAME`, `OATS_WORKSPACE_NAME` and
925
955
  `OATS_WORKSPACE_KEY`;
926
- - `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"`;
927
963
  - `OATS_SOUL`, the soul directory: a home's recorded one, or for a soul
928
964
  (`readiness --soul`, `inspect --soul`) its copy at the resolved commit,
929
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`