@awebai/oats 0.48.0 → 0.50.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 (47) hide show
  1. package/bin/oats.mjs +326 -28
  2. package/docs/capabilities.md +425 -8
  3. package/docs/capability-manifest.schema.json +60 -5
  4. package/docs/configuration.md +103 -0
  5. package/docs/desktop-cli-api.md +542 -47
  6. package/docs/desktop.md +85 -5
  7. package/docs/execution-targets.md +50 -9
  8. package/docs/implementation.md +74 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +4 -4
  12. package/docs/packages.md +28 -14
  13. package/docs/release-lane.md +41 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/release-notes/v0.50.0.md +279 -0
  16. package/docs/schedules.md +289 -53
  17. package/docs/servers.md +7 -0
  18. package/docs/souls-and-instances.md +450 -60
  19. package/docs/workspaces.md +3 -3
  20. package/injects/work-checkout.md +17 -11
  21. package/injects/work-worktree.md +19 -13
  22. package/lib/capability-contract.mjs +100 -11
  23. package/lib/capability-show.mjs +18 -2
  24. package/lib/core.mjs +1374 -394
  25. package/lib/instance-events.mjs +9 -10
  26. package/lib/instance-git.mjs +19 -10
  27. package/lib/instance-inspect.mjs +58 -18
  28. package/lib/instance-lifecycle.mjs +106 -16
  29. package/lib/instance-resolution.mjs +15 -3
  30. package/lib/launch-prompt-policy.mjs +17 -3
  31. package/lib/packages.mjs +1 -0
  32. package/lib/real-path.mjs +27 -0
  33. package/lib/refused-text.mjs +17 -0
  34. package/lib/resolve.mjs +4 -4
  35. package/lib/retained-after-retire.mjs +387 -0
  36. package/lib/retire-output.mjs +6 -1
  37. package/lib/schedule.mjs +9 -2
  38. package/lib/servers.mjs +32 -6
  39. package/lib/tree-copy.mjs +18 -7
  40. package/lib/trigger-sources.mjs +234 -0
  41. package/lib/triggers.mjs +705 -108
  42. package/lib/workspace.mjs +20 -5
  43. package/lib/worktree-hooks.mjs +392 -0
  44. package/lib/worktree.mjs +655 -0
  45. package/package-catalog.json +3 -3
  46. package/package.json +1 -1
  47. package/skills/oats-getting-started/SKILL.md +1 -1
package/bin/oats.mjs CHANGED
@@ -19,7 +19,7 @@
19
19
  * `init` / `use` / `install` / `restore` / `list` / `catalog` / `remove` /
20
20
  * `migrate` / `trust` / `inject` are gone with the installed-capability tier.
21
21
  */
22
- import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readSync, readdirSync, realpathSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
22
+ import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readSync, readdirSync, readlinkSync, realpathSync, rmdirSync, rmSync, writeFileSync } from "node:fs";
23
23
  import { execFileSync, spawnSync } from "node:child_process";
24
24
  import { constants as osConstants, homedir, tmpdir } from "node:os";
25
25
  import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
@@ -30,7 +30,7 @@ import {
30
30
  LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
31
31
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
32
32
  officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
33
- findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchPromptPolicyAt, LAUNCH_PROMPT_UPDATE_WARNING, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
33
+ findInstanceHome, findInstanceHomes, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchPromptPolicyAt, LAUNCH_PROMPT_UPDATE_WARNING, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, 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 {
@@ -55,13 +55,14 @@ import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_
55
55
  import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
56
56
  import { planStop, applyStop, planRetire, descendantsOf, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
57
57
  import { extraWorktreeLines, formatBytes, workRecoveryLines } from "../lib/retire-output.mjs";
58
+ import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
58
59
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
59
60
  import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
60
61
  import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
61
62
 
62
63
  const rawArgs = process.argv.slice(2);
63
64
  /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
64
- const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
65
+ const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "self", "verbose", "yes", "yolo"]);
65
66
  /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
66
67
  * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
67
68
  * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
@@ -90,9 +91,14 @@ function expandInlineValues(argv) {
90
91
  const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
91
92
  let cmd = args[0];
92
93
  const HELP_WORDS = new Set(["help", "--help", "-h"]);
93
- const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "update", "version", "workspace"]);
94
+ const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "update", "version", "workspace", "worktree"]);
94
95
  /** Commands whose argv another parser reads (packages/record and packages/experimental parse process.argv). */
95
96
  const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental"]);
97
+ /** The kernel features this binary implements: `features` in `version --json` (the Desktop API v1
98
+ * probe) and in `status --json`, which a remote roster relays as the host's (feature
99
+ * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
100
+ * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
101
+ const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources"];
96
102
  /** Commands `--server <id>` runs on a registered server. */
97
103
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
98
104
  const flag = (name) => {
@@ -218,7 +224,8 @@ async function doctorComposition(ctx, soulName, ws, bail) {
218
224
  const pv = await previewWorkspaceSoul(prepared, root);
219
225
  cleanups.push(pv.cleanup);
220
226
  const { text, blocks, resolved, oatsCoreDeclared } = await composeSoulInstructions({ deployment, prepared, soulDir: pv.soulDir });
221
- return { text, blocks, resolved, oatsCoreDeclared };
227
+ const { resolutionContractWarnings } = await import("../lib/instance-resolution.mjs");
228
+ return { text, blocks, resolved, oatsCoreDeclared, warnings: resolutionContractWarnings(prepared.resolution) };
222
229
  } catch (e) {
223
230
  if (e?.code?.startsWith?.("E_")) bail(e.code, e.message, e.details);
224
231
  throw e;
@@ -273,6 +280,84 @@ async function doctorOperator(ws) {
273
280
  return { problems: found.map(({ code, label, message, remedy }) => ({ code, ...(label ? { label } : {}), message, remedy })), information: [] };
274
281
  }
275
282
 
283
+ /** What the deployment's capabilities declare and this kernel ignores (an unknown hook event), for
284
+ * doctor without --soul, OFFLINE like doctorOperator, from this machine's parsed cache: each member's
285
+ * capabilities as `oats sync` enumerated them (the workspace's members confirmed by the cached
286
+ * membership; a standalone deployment's own repository), and every capability of every locked package.
287
+ * Each source is read on its own, so one the cache cannot answer leaves the others' warnings, and is
288
+ * said to be unchecked (information, `hook-events-unchecked`), never read as "no warning".
289
+ * → { warnings: [{ code, capability, path, message }], information } */
290
+ async function doctorHookWarnings(ws) {
291
+ const { cacheOnlyRemote } = await import("../lib/operator-coverage.mjs");
292
+ const { lockedPackageCapabilities } = await import("../lib/resolve.mjs");
293
+ const { capabilityContractWarnings, confirmMembership, observeWorkspace } = await import("../lib/workspace.mjs");
294
+ const { locatedContractWarnings } = await import("../lib/capability-contract.mjs");
295
+ const deployment = dirname(ws.local.path);
296
+ const local = ws.local.value;
297
+ const { bindRemote } = await import("../lib/packages.mjs");
298
+ const remoteOptions = remoteOptionsFromEnv();
299
+ // This machine's cache directory travels with every read (discovery binds it the same way).
300
+ const remote = bindRemote(cacheOnlyRemote(), remoteOptions);
301
+ const warnings = [], information = [];
302
+ const unchecked = (what, e) => information.push(`hook-events-unchecked: ${what} not checked for hook events this kernel does not run: ${e?.code === "E_REMOTE_UNREADABLE" ? `this machine's cache cannot answer (${e.message})` : `${e?.code ? `${e.code}: ` : ""}${e?.message ?? e}`}; oats sync, then run doctor again`);
303
+ // A member's capabilities as its enumeration at the observed commit lists them (lib/workspace.mjs enumerateRepo).
304
+ const memberCapabilities = async (ref) => {
305
+ const { commit } = await remote.observeRemote(ref);
306
+ // The cache-only remote never computes; the compute argument keeps bindRemote's options in place.
307
+ return (await remote.memoAtCommit(ref, commit, "enumerate", () => undefined)).capabilities || [];
308
+ };
309
+ const standalone = typeof local.standalone === "string" && local.standalone !== "" ? local.standalone : null;
310
+ if (standalone) {
311
+ try { warnings.push(...capabilityContractWarnings(await memberCapabilities(standalone))); }
312
+ catch (e) { unchecked(`member ${standalone}'s capabilities were`, e); }
313
+ } else {
314
+ let observed = null;
315
+ try { observed = await observeWorkspace(local.workspace, { remote }); }
316
+ catch (e) {
317
+ if (e?.code !== "E_WORKSPACE_SCHEMA" || e?.details?.notAHost !== true) unchecked("member capabilities were", e);
318
+ else {
319
+ // `workspace:` names a member (docs/workspaces.md), as discovery follows it: its host, from the
320
+ // member's cached oats-membership.yaml. Without the host (unreadable, or never read here), the
321
+ // member's own capabilities (discovery's standalone view), and the other members unchecked.
322
+ const member = local.workspace;
323
+ let backlink;
324
+ try { const { commit } = await remote.observeRemote(member); backlink = await remote.memoAtCommit(member, commit, "membership", () => undefined); }
325
+ catch (miss) { backlink = { miss }; }
326
+ if (backlink && !backlink.miss && backlink.kind !== "ok") unchecked("member capabilities were", e);
327
+ else {
328
+ try { if (backlink.miss) throw backlink.miss; observed = await observeWorkspace(backlink.value.workspace, { remote }); }
329
+ catch (host) {
330
+ try { warnings.push(...capabilityContractWarnings(await memberCapabilities(member))); }
331
+ catch (own) { unchecked(`member ${member}'s capabilities were`, own); }
332
+ unchecked("the workspace's other members' capabilities were", host);
333
+ }
334
+ }
335
+ }
336
+ }
337
+ for (const ref of observed?.workspace?.members || []) {
338
+ try {
339
+ const membership = await confirmMembership(observed, ref, { remote });
340
+ if (!membership.confirmed) {
341
+ // Not a member: discovery lists none of its capabilities. Not read: unchecked.
342
+ if (membership.reason === "cannot-read") unchecked(`member ${membership.key}'s capabilities were`, { code: "E_REMOTE_UNREADABLE", message: membership.detail });
343
+ continue;
344
+ }
345
+ warnings.push(...capabilityContractWarnings(await memberCapabilities(ref)));
346
+ } catch (e) { unchecked(`member ${ref}'s capabilities were`, e); }
347
+ }
348
+ }
349
+ let lock = null;
350
+ try { lock = readLockIfPresent(deployment); } catch { lock = null; } // an invalid lock is doctor's own problem, reported above
351
+ let catalog = null; try { catalog = officialPackageCatalog(); } catch { catalog = null; }
352
+ for (const [id, entry] of Object.entries(lock?.packages || {}).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
353
+ try {
354
+ const { capabilities } = await lockedPackageCapabilities(id, entry, { catalog, remote, remoteOptions });
355
+ for (const c of capabilities) warnings.push(...locatedContractWarnings(c.manifest, `package:${id}:${c.dir}/oats.json`));
356
+ } catch (e) { unchecked(`package ${id}'s capabilities were`, e); }
357
+ }
358
+ return { warnings, information };
359
+ }
360
+
276
361
  /** Workspace-model v2 doctor data, OFFLINE: the deployment declaration found
277
362
  * walking up from ctx (oats-local.yaml) and the lock v3 beside it. Doctor never
278
363
  * goes to the network for this view (only `--soul`, which resolves the soul like a
@@ -473,6 +558,7 @@ function printWorkspaceInspect(doc) {
473
558
  for (const l of LAYERS) console.log(` ${l} capability: ${doc.layers[l].id || "none"}`);
474
559
  for (const c of doc.capabilities) console.log(` ${c.id}@${c.version || "?"} ${c.from?.kind === "package" ? `package ${c.from.package}` : c.from?.kind === "member" ? `member ${c.from.repoKey}` : ""}${c.operations.length ? ` ops: ${c.operations.map((o) => `${o.name}${o.available ? "" : "(unavailable)"}`).join(", ")}` : ""}`);
475
560
  for (const p of doc.problems) console.log(` ! ${p.code}: ${p.message}`);
561
+ for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
476
562
  const composed = doc.souls[0].composedInstructions;
477
563
  if (composed !== undefined) console.log(composed ? `\nComposed AGENTS.md (a spawn here, resolution ${composed.resolution ?? "?"}${composed.truncated ? ", truncated" : ""}):\n\n${composed.text}` : "\nComposed AGENTS.md: unavailable (see the problems above)");
478
564
  }
@@ -641,20 +727,31 @@ async function doctorJson(dir) {
641
727
  function legacyLayoutProblems(root) {
642
728
  return [legacyLocalAgents(root), legacyCapturedHomes(root)].filter(Boolean);
643
729
  }
730
+ /** What retires left in the deployment (#703 part 2a), read-only: the
731
+ * `retained-recovery:` and `retained-worktree:` information lines, as one
732
+ * block per kind (a count line, then one line per item). */
733
+ function doctorRetained(ws) {
734
+ const deployment = dirname(ws.local.path);
735
+ const kept = retainedWorktrees(deployment);
736
+ return [retainedRecoveryLines(join(deployment, "agents"), kept), retainedWorktreeLines(kept)].filter((block) => block.length);
737
+ }
644
738
  async function doctorWorkspaceJson(ctx, soulName, ws) {
645
739
  const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
646
740
  const agentsRoot = join(dirname(ws.local.path), "agents");
647
741
  const localTeams = doctorLocalTeams(ws.local.value);
648
742
  const schedules = unresolvedScheduleAttempts(dirname(ws.local.path));
649
743
  const operator = await doctorOperator(ws);
744
+ // With --soul, the soul's composition; without, the deployment's capabilities (doctorHookWarnings).
745
+ const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
650
746
  const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...localTeams.problems, ...schedules.problems, ...operator.problems].filter(Boolean);
651
747
  return {
652
748
  schemaVersion: 1, workspaceApi: 2, context: ctx,
653
749
  workspace: { file: ws.local.path, ref: ws.local.workspace },
654
750
  workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
655
- information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information],
751
+ information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
656
752
  composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
657
753
  ...(problems.length ? { problems } : {}),
754
+ warnings: hookEvents.warnings,
658
755
  };
659
756
  }
660
757
  /** Kernel/bridge version skew (published in lockstep from one tag). */
@@ -694,7 +791,10 @@ async function doctor(dir) {
694
791
  for (const p of schedules.problems) console.log(`\n! ${p.code}: ${p.message}`);
695
792
  const operator = await doctorOperator(ws);
696
793
  for (const p of operator.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
697
- for (const line of [...localTeams.information, ...schedules.information, ...operator.information]) console.log(`\nINFO: ${line}`);
794
+ const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
795
+ for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
796
+ for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
797
+ for (const block of doctorRetained(ws)) console.log(`\n${block.map((line) => `INFO: ${line}`).join("\n")}`);
698
798
  if (soulName) {
699
799
  const information = operationalKnowledgeNote(composition, soulName);
700
800
  if (information) console.log(`\nINFO: ${information}`);
@@ -1018,6 +1118,85 @@ function instanceWaitingCmd(sub, bail) {
1018
1118
  } catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
1019
1119
  }
1020
1120
 
1121
+ /** `oats worktree add|remove` (#796, feature worktree-event): an instance's extra trees,
1122
+ * `<home>/.work-<purpose>`, made from its home (lib/worktree.mjs). The home is
1123
+ * $OATS_INSTANCE_HOME (or $OATS_HOME), else the home enclosing the working directory.
1124
+ * `add` streams the worktree hooks' output to stderr; stdout holds only the answer
1125
+ * (one envelope with --json). An interrupt exits 128+signal after the rollback. */
1126
+ async function worktreeCmd() {
1127
+ const bail = (code, msg, details, exit) => (JSON_MODE ? jsonFail(code, msg, details, exit) : die(msg, exit));
1128
+ const sub = args[1];
1129
+ const usage = "usage: oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json] | oats worktree remove --purpose <p> [--json]";
1130
+ if (!["add", "remove"].includes(sub)) return bail("E_BAD_ARGS", usage);
1131
+ if (flag("server") !== undefined) return bail("E_BAD_ARGS", "oats worktree runs in an instance home on this machine; --server is not accepted");
1132
+ for (const f of ["dir", "home"]) if (args.includes(`--${f}`)) return bail("E_BAD_ARGS", `oats worktree has no --${f}: it acts on the instance home it runs in; ${usage}`);
1133
+ const value = (name) => { const v = flag(name); if (v === true) throw Object.assign(new Error(`--${name} needs a value`), { code: "E_BAD_ARGS" }); return v === undefined ? undefined : String(v); };
1134
+ const homeVariable = ["OATS_INSTANCE_HOME", "OATS_HOME"].find((name) => process.env[name]);
1135
+ const home = homeVariable ? process.env[homeVariable] : enclosingInstanceHome(logicalCwd());
1136
+ if (!home) return bail("E_BAD_ARGS", `oats worktree runs from an instance home: run it in the home (or below it), or with $OATS_INSTANCE_HOME set; ${usage}`);
1137
+ const W = await import("../lib/worktree.mjs");
1138
+ // A caller that closes its end of stdout or stderr (a tool shell killed, Desktop gone) has only
1139
+ // stopped reading: the add or remove goes on to its consistent end, and what it can no longer
1140
+ // print is dropped. Unhandled, that EPIPE would end this process mid-hook, with no rollback.
1141
+ const readerGone = (e) => { if (e?.code !== "EPIPE" && e?.code !== "ERR_STREAM_DESTROYED") throw e; };
1142
+ process.stdout.on("error", readerGone);
1143
+ process.stderr.on("error", readerGone);
1144
+ try {
1145
+ if (sub === "remove") {
1146
+ for (const f of ["branch", "base", "repo", "preview"]) if (args.includes(`--${f}`)) return bail("E_BAD_ARGS", `oats worktree remove takes only --purpose; ${usage}`);
1147
+ const r = await W.worktreeRemove(resolve(home), { purpose: value("purpose") });
1148
+ if (JSON_MODE) { jsonOk(r); return; }
1149
+ console.log(r.rolledBack
1150
+ ? `rolled back the interrupted add of ${r.path}; branch ${r.branch} ${r.branchKept ? `kept${r.branchKeptReason ? ` (${r.branchKeptReason})` : ""}` : "not left behind"}`
1151
+ : `removed ${r.path}; branch ${r.branch} kept`);
1152
+ for (const w of r.warnings || []) console.error(`oats: warning: ${w}`);
1153
+ return;
1154
+ }
1155
+ const r = await W.worktreeAdd(resolve(home), { purpose: value("purpose"), branch: value("branch"), base: value("base"), repo: value("repo"), preview: args.includes("--preview") });
1156
+ if (JSON_MODE) { jsonOk(r); return; }
1157
+ if (r.preview) {
1158
+ console.log(`preview ${r.path} from ${r.clone} (origin ${r.remote || "?"}): branch ${r.branch} at origin's ${r.base}${r.resume === "noop" ? " — already made: add is a no-op" : r.resume === "recover" ? " — an interrupted add is rolled back first" : ""}; nothing was fetched or written`);
1159
+ const hooks = r.resume === "noop" ? [] : r.hooks;
1160
+ console.log(hooks.length ? `worktree hooks: ${hooks.map((h) => `${h.capability}${h.required ? " (required)" : ""}`).join(", ")}` : "worktree hooks: none");
1161
+ return;
1162
+ }
1163
+ console.log(r.resumed ? `${r.path} is already made (branch ${r.branch} from ${r.base} @ ${String(r.baseOid).slice(0, 12)}); nothing was run` : `made ${r.path}: branch ${r.branch} from origin's ${r.base} @ ${String(r.baseOid).slice(0, 12)}${r.hooks.length ? `; worktree hooks: ${r.hooks.map((h) => `${h.capability} ${h.ok ? "ok" : "FAILED"}`).join(", ")}` : ""}`);
1164
+ for (const w of r.warnings || []) console.error(`oats: warning: ${w}`);
1165
+ } catch (e) {
1166
+ if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details, e.exitStatus);
1167
+ throw e;
1168
+ }
1169
+ }
1170
+
1171
+ /** realpath of `p`, or of its nearest existing ancestor with the rest re-appended:
1172
+ * how lib/instance-events.mjs names a removed home (realOrNearest). */
1173
+ function realOrNearestPath(p) {
1174
+ let d = resolve(p); const tail = [];
1175
+ while (!existsSync(d) && dirname(d) !== d) { tail.unshift(basename(d)); d = dirname(d); }
1176
+ try { return join(realpathSync(d), ...tail); } catch { return resolve(p); }
1177
+ }
1178
+ /** #642: the addresses of a RETIRED instance `name` under `root`, from the
1179
+ * workspace logs that outlive its home (<deployment>/.agents/events/
1180
+ * <agent>--<name>.jsonl), as `{ root, agent, home }` like resolveInstance's
1181
+ * candidates. Asked only when no live home resolves. A `home` (the --home
1182
+ * claim) counts only when it is <root>/<agent>/instances/<name> by real path
1183
+ * and that agent's log exists; the agent is then read from the path, never
1184
+ * from the log's file name, and the row carries the claim as `asked` while
1185
+ * `home` is the scope's spelling, from which the logs are found (an alias of
1186
+ * the agents root elsewhere would lead readEvents to another deployment). */
1187
+ function retiredInstanceAddresses(root, name, home) {
1188
+ const events = join(workspaceOf(root), ".agents", "events"), suffix = `--${name}.jsonl`;
1189
+ const logged = (agent) => { try { return lstatSync(join(events, `${agent}${suffix}`)).isFile(); } catch { return false; } };
1190
+ if (home !== undefined) {
1191
+ const h = resolve(home), agent = basename(dirname(dirname(h)));
1192
+ const ok = basename(h) === name && basename(dirname(h)) === "instances" && agent && realOrNearestPath(h) === realOrNearestPath(join(root, agent, "instances", name)) && logged(agent);
1193
+ return ok ? [{ root, agent, home: join(root, agent, "instances", name), asked: home }] : [];
1194
+ }
1195
+ let entries; try { entries = readdirSync(events, { withFileTypes: true }); } catch { return []; }
1196
+ return entries.filter((e) => e.isFile() && e.name.endsWith(suffix) && e.name.length > suffix.length).map((e) => e.name.slice(0, -suffix.length)).sort()
1197
+ .map((agent) => ({ root, agent, home: join(root, agent, "instances", name) }));
1198
+ }
1199
+
1021
1200
  /** `oats instance <git|diff> <instance>` — K1: read-only Git observation of one
1022
1201
  * instance's work tree. The instance is addressed qualified: an explicit
1023
1202
  * --home, or a name under the --dir scope (team roots included) that resolves
@@ -1039,8 +1218,21 @@ function instanceCmd() {
1039
1218
  const { resolveInstance } = await_import_lifecycle();
1040
1219
  // K7b: --home is an ADDRESS claim, checked like K1 — it must be a home of
1041
1220
  // exactly this name under the scope (E_HOME_MISMATCH otherwise).
1042
- const home = resolveInstance(dirFlag(), root, name, homeOpt ? { home: homeOpt } : {}).home;
1043
- const ev = readEvents(home, { ...(limit !== undefined ? { limit: Math.max(1, Math.min(2000, Number(limit) || 200)) } : {}), ...(since ? { since } : {}) });
1221
+ let home, asked;
1222
+ try { home = resolveInstance(dirFlag(), root, name, homeOpt ? { home: homeOpt } : {}).home; }
1223
+ catch (e) {
1224
+ // #642: no live home — a retired instance still answers from the
1225
+ // workspace log, which outlives its home (home source absent,
1226
+ // incarnation null). A live home never reaches this.
1227
+ const gone = homeOpt ? e.code === "E_HOME_MISMATCH" && !existsSync(homeOpt) : e.code === "E_SESSION_UNKNOWN";
1228
+ const candidates = gone ? retiredInstanceAddresses(root, name, homeOpt) : [];
1229
+ if (candidates.length > 1) return bail("E_AMBIGUOUS_INSTANCE", `retired instance ${JSON.stringify(name)} has ${candidates.length} workspace logs (one per agent); pass --home <abs>`, { candidates });
1230
+ if (!candidates.length) throw e;
1231
+ home = candidates[0].home;
1232
+ // The logs are found from the scope's spelling; the answer names the home as --home spelled it.
1233
+ asked = candidates[0].asked;
1234
+ }
1235
+ const ev = readEvents(home, { ...(limit !== undefined ? { limit: Math.max(1, Math.min(2000, Number(limit) || 200)) } : {}), ...(since ? { since } : {}), ...(asked !== undefined ? { asked } : {}) });
1044
1236
  if (JSON_MODE) { jsonOk(ev); return; }
1045
1237
  console.log(`${ev.instance}: ${ev.returned} of ${ev.count} event(s)${ev.truncated ? " (window truncated)" : ""}${ev.waitingOnYou ? ` — waiting on you since ${ev.waitingOnYou.since} (${ev.waitingOnYou.producer})` : ""}`);
1046
1238
  for (const e of ev.events) console.log(` ${e.at ?? "?"} ${e.kind.padEnd(20)} ${e.producer}${e.data ? ` ${JSON.stringify(e.data).slice(0, 120)}` : ""}`);
@@ -1140,6 +1332,7 @@ async function readinessCmd() {
1140
1332
  for (const i of check.items) console.log(` ${i.status.padEnd(14)} ${i.subject}${i.required ? "" : " (optional)"}${i.reason ? ` — ${i.reason}` : ""}${i.remedy ? ` → ${i.remedy}` : ""}`);
1141
1333
  }
1142
1334
  if (doc.policy) console.log(` policy: child spawns ${doc.policy.childSpawns.allowed ? "allowed" : "disabled"} (${doc.policy.childSpawns.origin.kind}${doc.policy.childSpawns.enforced ? ", enforced" : ""}); worktrees ${doc.policy.worktrees.allowed === null ? "unknown" : doc.policy.worktrees.allowed ? "allowed" : "not in this work mode"}`);
1335
+ for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
1143
1336
  for (const n of doc.notes) console.log(` note: ${n}`);
1144
1337
  return;
1145
1338
  }
@@ -1181,7 +1374,7 @@ function sayReadNotices() {
1181
1374
  }
1182
1375
  /** Which kernel command forms take --max-age: THE allow-list (docs/desktop-cli-api.md "Observation reuse").
1183
1376
  * → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`. */
1184
- const MAX_AGE_READS = "status, workspace status, souls, capabilities, capabilities show, inspect --soul|--home, spawn --preview, and the read forms of teams and soul teams";
1377
+ const MAX_AGE_READS = "status, workspace status, souls, capabilities, capabilities show, inspect --soul|--home, spawn --preview, trigger poll, and the read forms of teams and soul teams";
1185
1378
  function maxAgeRefusal(command, head) {
1186
1379
  const word = (i) => (head[i] !== undefined && !head[i].startsWith("--") ? head[i] : undefined);
1187
1380
  const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs reuse observations (${MAX_AGE_READS})`;
@@ -1194,6 +1387,8 @@ function maxAgeRefusal(command, head) {
1194
1387
  case "teams": return word(1) === undefined ? null : refuse(`teams ${word(1)}`);
1195
1388
  // `soul teams` only reads (its edit flags were removed in 0.38.0, and refuse as such).
1196
1389
  case "soul": return word(1) === "teams" ? null : refuse(["soul", word(1)].filter(Boolean).join(" "));
1390
+ // A capability source's poll resolves its soul as a read (the tick's child passes --max-age 600).
1391
+ case "trigger": return word(1) === "poll" ? null : refuse(["trigger", word(1)].filter(Boolean).join(" "));
1197
1392
  default: {
1198
1393
  const sub = ["package", "schedule", "session", "trigger", "automations", "launch-config", "server", "instance", "operation", "pane"].includes(command) ? word(1) : undefined;
1199
1394
  return refuse([command, sub].filter(Boolean).join(" "));
@@ -1535,7 +1730,9 @@ async function addWorkspaceAutomation(desc, { id, body, description }) {
1535
1730
  const content = A.automationFileText(desc, { id, description: description || undefined, runsOn, owner, body });
1536
1731
  const parsed = A.parseAutomationFile(desc, { stem: id, path: `${desc.folder}/${id}.yaml`, bytes: Buffer.from(content), member: name, repoKey: row.key, commit: row.commit });
1537
1732
  if (parsed.problem) bail(parsed.problem.code, parsed.problem.message, { path: parsed.problem.path });
1538
- await desc.expand(parsed.entry);
1733
+ const def = await desc.expand(parsed.entry);
1734
+ // A capability source's trigger means something only against its soul's resolution: checked before the file is written.
1735
+ if (desc.kind === "trigger") await (await import("../lib/triggers.mjs")).checkAddMeaning(ctx.deploymentDir, def, { remoteOptions: ctx.remoteOptions });
1539
1736
  const sameRepo = (url) => { try { return remoteModule.parseRepoRef(url).key === row.key; } catch { return false; } };
1540
1737
  const at = A.memberCheckoutFor(dirFlag(), desc, id, { sameRepo });
1541
1738
  const file = { member: name, repoKey: row.key, path: `${desc.folder}/${id}.yaml`, content };
@@ -1954,6 +2151,8 @@ async function capabilityShowCmd(bail) {
1954
2151
  process.stdout.write(f.text.endsWith("\n") || f.text === "" ? f.text : `${f.text}\n`);
1955
2152
  if (f.truncated) console.log(`(${f.path}: truncated — ${formatBytes(f.bytes)}, the first ${formatBytes(S.TEXT_LIMIT)} shown)`);
1956
2153
  }
2154
+ // The file's text is stdout's alone: a warning goes to stderr.
2155
+ for (const w of doc.warnings) console.error(`warning ${w.code} ${w.message}`);
1957
2156
  return;
1958
2157
  }
1959
2158
  console.log(`${doc.name} — ${doc.kind === "member" ? `member ${doc.repoKey}` : `package ${doc.package} v${doc.version} (${doc.repoKey})`} @ ${short(doc.commit)}, ${doc.path}\n`);
@@ -1970,7 +2169,19 @@ async function capabilityShowCmd(bail) {
1970
2169
  if (skill.filesTruncated) console.log(` … more files (the first ${S.FILES_PER_SKILL} are listed)`);
1971
2170
  }
1972
2171
  }
2172
+ if (doc.triggerSources !== undefined) {
2173
+ // As declared (a malformed declaration is shown, never refused): names, commands and events, made safe to print.
2174
+ const { safeText } = await import("../lib/refused-text.mjs");
2175
+ const decl = doc.triggerSources && typeof doc.triggerSources === "object" && !Array.isArray(doc.triggerSources) ? doc.triggerSources : null;
2176
+ console.log(decl && Object.keys(decl).length ? " trigger sources:" : ` trigger sources: ${decl ? "(none)" : "(malformed — see trigger source problems)"}`);
2177
+ for (const [n, src] of Object.entries(decl ?? {})) {
2178
+ const o = src && typeof src === "object" ? src : {};
2179
+ console.log(` ${safeText(n, 60)} command ${typeof o.command === "string" ? safeText(o.command, 60) : "?"} events ${Array.isArray(o.events) ? o.events.map((e) => safeText(String(e), 40)).join(",") : "?"}${typeof o.description === "string" ? ` — ${safeText(o.description, 200)}` : ""}`);
2180
+ }
2181
+ for (const p of doc.triggerSourceProblems ?? []) console.log(` trigger source problem: ${p.pointer} — ${safeText(p.message, 300)}`);
2182
+ }
1973
2183
  for (const p of doc.problems) console.log(` problem: ${p.code}${p.path ? ` ${p.path}` : ""} — ${p.message}`);
2184
+ for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
1974
2185
  console.log(`\n a file's text: oats capabilities show ${doc.name}${doc.kind === "package" ? ` --package ${doc.package}` : ""} --file <path>`);
1975
2186
  }
1976
2187
 
@@ -2230,7 +2441,9 @@ async function status() {
2230
2441
  }
2231
2442
  }
2232
2443
  const observation = maxAgeGiven === null ? {} : { observation: observationBlock() };
2233
- console.log(JSON.stringify({ root, agents: data, ...observation, ...(ws ? { workspace: { ...(ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true }), ...workspaceIdentity(ws.local, ws.discovery) } } : {}), ...(problems.length ? { problems } : {}), ...envelopeWarnings() }, null, 2)); return;
2444
+ // `features` (feature server-probe-features): this kernel's own list, as `version --json` answers
2445
+ // it, so a remote roster relays the host's without probing it. Never part of a reused observation.
2446
+ console.log(JSON.stringify({ root, agents: data, ...observation, features: KERNEL_FEATURES, ...(ws ? { workspace: { ...(ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true }), ...workspaceIdentity(ws.local, ws.discovery) } } : {}), ...(problems.length ? { problems } : {}), ...envelopeWarnings() }, null, 2)); return;
2234
2447
  }
2235
2448
  console.log(`oats status — agents root ${shortPath(root)}\n`);
2236
2449
  if (ws?.unreachable) console.log(` workspace: unreachable (${ws.unreachable.reason}) — drift unknown\n`);
@@ -2296,7 +2509,7 @@ function herdrSpawnFlag() {
2296
2509
  }
2297
2510
  async function spawnCmd() {
2298
2511
  // JSON mode: contract envelope, stable error codes, stderr-only progress.
2299
- const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
2512
+ const bail = (code, msg, details, exit) => (JSON_MODE ? jsonFail(code, msg, details, exit) : die(msg, exit));
2300
2513
  const note = (msg) => (JSON_MODE ? console.error(msg) : console.log(msg));
2301
2514
  const yolo = yoloFlag();
2302
2515
  { const herdr = herdrSpawnFlag(); if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); } }
@@ -2435,8 +2648,13 @@ async function spawnCmd() {
2435
2648
  if (f !== undefined) {
2436
2649
  if (!existsSync(f)) bail("E_BAD_ARGS", `--trigger-event not found: ${f}`);
2437
2650
  try { triggerEvent = JSON.parse(readFileSync(f, "utf8")); } catch (e) { bail("E_BAD_ARGS", `--trigger-event is not valid JSON: ${e.message}`); }
2438
- const ok = triggerEvent && typeof triggerEvent === "object" && !Array.isArray(triggerEvent) && typeof triggerEvent.trigger === "string" && typeof triggerEvent.source === "string" && typeof triggerEvent.repo === "string" && Number.isInteger(triggerEvent.number) && typeof triggerEvent.event === "string";
2439
- if (!ok) bail("E_BAD_ARGS", "--trigger-event must hold { trigger, source, repo, number, url, event, headSha, labels, observedAt }");
2651
+ // A pull-request event names its repo and number; a capability source's, its subject and key,
2652
+ // and its fields, recorded in instance.json, are a plain object of strings.
2653
+ const stringMap = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && Object.values(v).every((x) => typeof x === "string");
2654
+ const ok = triggerEvent && typeof triggerEvent === "object" && !Array.isArray(triggerEvent) && typeof triggerEvent.trigger === "string" && typeof triggerEvent.source === "string" && typeof triggerEvent.event === "string"
2655
+ && (triggerEvent.source === "github.pull_request" ? typeof triggerEvent.repo === "string" && Number.isInteger(triggerEvent.number)
2656
+ : typeof triggerEvent.subject === "string" && typeof triggerEvent.key === "string" && (triggerEvent.fields === undefined || stringMap(triggerEvent.fields)));
2657
+ if (!ok) bail("E_BAD_ARGS", "--trigger-event must hold { trigger, source, repo, number, url, event, headSha, labels, observedAt } (github.pull_request) or { trigger, source, subject, event, key, url?, fields, observedAt } (a capability source; fields an object of strings)");
2440
2658
  } }
2441
2659
  const relativeRoot = flag("relative-root");
2442
2660
  if (relativeRoot !== undefined && (relativeRoot === true || !String(relativeRoot).trim())) bail("E_BAD_ARGS", "--relative-root needs an agents-root path");
@@ -2524,6 +2742,8 @@ async function spawnCmd() {
2524
2742
  if (prepared) r.soulFetched = soulFetched;
2525
2743
  if (JSON_MODE) { jsonOk(withObservation(r)); return; }
2526
2744
  console.log(`preview ${r.agent} → ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch} from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}) harness ${r.harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}${r.launchConfig ? ` via launch configuration ${r.launchConfig}${r.launchConfigDefault ? ` (this machine's ${r.harness} default)` : ""}` : ""}${r.yolo ? " YOLO" : ""}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
2745
+ if (Array.isArray(r.worktreeHooks)) console.log(r.worktreeHooks.length ? `worktree hooks: ${r.worktreeHooks.map((h) => `${h.capability}${h.required ? " (required)" : ""}`).join(", ")}` : "worktree hooks: none");
2746
+ for (const w of r.warnings || []) console.log(` WARNING: ${w}`);
2527
2747
  return;
2528
2748
  }
2529
2749
  } catch (e) {
@@ -2541,6 +2761,12 @@ async function spawnCmd() {
2541
2761
  if (e?.code === "E_REQUIREMENT_INACTIVE") { bail(e.code, e.message, { soul: e.soul, capabilities: e.capabilities, context: e.context, remedy: e.remedy }); throw e; }
2542
2762
  if (e?.code === "E_CHILD_SPAWNS_DISABLED") { bail(e.code, e.message, { parent: e.parent, policy: e.policy }); throw e; }
2543
2763
  if (["E_BRANCH_EXISTS", "E_BASE_UNKNOWN"].includes(e?.code)) { bail(e.code, e.message); throw e; }
2764
+ // #796: interrupted while its worktree hooks ran: rolled back (the message says how far), 128+signal.
2765
+ if (e?.code === "E_INTERRUPTED") { bail(e.code, e.message, e.details, e.exitStatus); throw e; }
2766
+ // A required spawn or worktree hook that failed, or answered outside its environment contract, keeps
2767
+ // its typed code: the hooks' receipt (`details.hooks`, paths only) and `unconfirmed` when the rollback
2768
+ // could not confirm its effects. Never `home`: a consumer reads that as retained effects.
2769
+ if (e?.code === "E_REQUIRED_HOOK_FAILED" || e?.code === "E_HOOK_ENVIRONMENT_CONTRACT") { bail(e.code, e.message, { hooks: e.details?.hooks ?? [], ...(e.details?.unconfirmed === true ? { unconfirmed: true } : {}) }); throw e; }
2544
2770
  // The observed base could not be fetched into the clone: the clone, the repository and the commit travel along.
2545
2771
  if (e?.code === "E_REMOTE_UNREADABLE" && e.details?.commit) { bail(e.code, e.message, e.details); throw e; }
2546
2772
  // K6b: the confirmed decision drifted — the fresh decision travels with the refusal so a GUI re-previews.
@@ -2581,12 +2807,15 @@ async function spawnCmd() {
2581
2807
  ...(r.decision ? { decision: r.decision } : {}), ...(r.replayed !== undefined ? { replayed: r.replayed } : {}),
2582
2808
  ...(r.wake !== undefined ? { wake: r.wake } : {}), // {requested, saved|null, error}: saved:null = outcome not recorded
2583
2809
  launchConfig: r.launch?.launchConfig ?? null, launch: r.launch || null, // already redacted by the kernel
2810
+ // #796: the worktree hooks this spawn ran, with their logs; only when it ran any.
2811
+ ...(r.worktreeHooks ? { worktreeHooks: r.worktreeHooks } : {}),
2584
2812
  });
2585
2813
  return;
2586
2814
  }
2587
2815
  console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
2588
2816
  console.log(` home: ${shortPath(r.home)}`);
2589
2817
  if (r.base) console.log(` base: ${r.base.oid.slice(0, 12)} (${r.base.ref === r.workspace?.soul?.repoKey ? `observed head of ${r.base.ref}` : r.base.ref})`);
2818
+ for (const h of r.worktreeHooks || []) console.log(` setup: ${h.capability} worktree hook ${h.ok ? "ok" : "FAILED"} (log: ${shortPath(h.log)})`);
2590
2819
  if (wakeSchedule) console.log(` wake: schedule ${wakeSchedule.id} (${wakeSchedule.cron} ${wakeSchedule.tz}), next ${wakeSchedule.nextRun || "disabled"}`);
2591
2820
  if (wakeScheduleError) console.error(` wake: NOT saved — ${wakeScheduleError.message} (the instance is created and launched; add the wake by hand with oats schedule add)`);
2592
2821
  if (!r.launched) console.log(` launch: oats session start --home ${shellQuote(r.home)}`);
@@ -2633,7 +2862,6 @@ function retireCmd() {
2633
2862
  if (isSelf && !args.includes("--self")) die(`"${name}" is the calling instance — self-retire is irreversible; if your task is complete and you were told to retire, re-run with --self (finish your memory files FIRST; your session dies ~8s after)`);
2634
2863
  if (!isSelf && args.includes("--self")) die(`--self given but "${name}" is not the calling instance`);
2635
2864
  const root = ensureRoot(dirFlag());
2636
- const retiringHome = homeFlag || findInstanceHome(root, name);
2637
2865
  // K3: a GUI-driven Remove carries the plan revision it showed and an
2638
2866
  // idempotency key. The revision is revalidated against a fresh plan
2639
2867
  // (E_PLAN_STALE with that plan attached — re-confirm, never act on the old
@@ -2679,7 +2907,9 @@ function retireCmd() {
2679
2907
  if (replayPath) { r.planRevision = planRev; r.idempotencyKey = idemKey; r.replayed = false; try { writeFileAtomic(replayPath, JSON.stringify(r, null, 2)); } catch { /* receipt is evidence, not authority */ } }
2680
2908
  // A retired home's wake jobs are forgotten (definitions only; nothing is
2681
2909
  // stopped by this); a deferred self-retire keeps them until the home is gone.
2682
- if (retiringHome && r.removedDir !== false && !r.deferred) { try { const gone = removeWakeForHome(scheduleScopeOf(workspaceOf(root)), retiringHome); if (gone.length) r.wakeSchedulesRemoved = gone; } catch (e) { r.warnings = [...(r.warnings || []), `wake schedules not cleaned: ${e.message}`]; } }
2910
+ // The home is the one the retire selected (awebai/oats#693), as a path.
2911
+ const retiringHome = r[RETIRE_SELECTED_HOME];
2912
+ if (typeof retiringHome === "string" && r.removedDir !== false && !r.deferred) { try { const gone = removeWakeForHome(scheduleScopeOf(workspaceOf(root)), retiringHome); if (gone.length) r.wakeSchedulesRemoved = gone; } catch (e) { r.warnings = [...(r.warnings || []), `wake schedules not cleaned: ${e.message}`]; } }
2683
2913
  // Deferred self-retire: nothing has been inspected, run, or removed yet. The
2684
2914
  // caller's window dies first; a detached process then retires the instance
2685
2915
  // as an external operator and writes its outcome beside the home.
@@ -2712,7 +2942,9 @@ function retireCmd() {
2712
2942
  process.exit(1);
2713
2943
  }
2714
2944
  console.log(`Retired ${r.retired} (agent ${r.agent})${r.worktreeRemoved ? ", worktree removed" : ""}`);
2715
- for (const k of r.childrenStopped || []) console.log(` child ${k.instance}: ${k.alreadyIdle ? "already idle" : "stopped"}`);
2945
+ // An attached child the retire repointed to the retained worktree (#718), as its link now reads.
2946
+ const followsWorktree = (k) => { if (r.retention?.worktree !== "retained") return false; try { return readlinkSync(join(k.home, "work")) === r.retention.movedTo; } catch { return false; } };
2947
+ for (const k of r.childrenStopped || []) console.log(` child ${k.instance}: ${k.alreadyIdle ? "already idle" : "stopped"}${followsWorktree(k) ? `; its work now links to the retained worktree ${r.retention.movedTo}` : ""}`);
2716
2948
  // Preserving work and not saying so leaves the operator believing it is gone,
2717
2949
  // which is most of the harm of deleting it. Name the classes and the path.
2718
2950
  for (const line of workRecoveryLines(r)) console.log(line);
@@ -2829,13 +3061,24 @@ async function triggerCmd() {
2829
3061
  const sub = args[1];
2830
3062
  const id = args[2] && !args[2].startsWith("--") ? args[2] : undefined;
2831
3063
  const T = await import("../lib/triggers.mjs");
3064
+ const { REFUSED_TEXT, safeText } = await import("../lib/refused-text.mjs");
2832
3065
  let scope;
2833
3066
  const ws = () => (scope ??= scheduleScopeOf(dirFlag()));
2834
- const out = (result, text) => { if (JSON_MODE) jsonOk(result); else console.log(text ? text(result) : JSON.stringify(result, null, 2)); };
3067
+ // A stored definition that fails validation is still listed and shown, as it was written: what a
3068
+ // terminal gets of it never carries a refused character. In a row's text it is replaced (`shown`);
3069
+ // in the JSON `show` prints as text it is escaped (\uXXXX; the layout's own newlines stay), so the document's value is unchanged.
3070
+ const shown = (v, max) => safeText(typeof v === "string" ? v : JSON.stringify(v) ?? String(v), max);
3071
+ const escaped = (json) => json.replace(new RegExp(REFUSED_TEXT.source, "gu"), (c) => (c === "\n" ? c : Array.from({ length: c.length }, (_, i) => `\\u${c.charCodeAt(i).toString(16).padStart(4, "0")}`).join("")));
3072
+ const out = (result, text) => { if (JSON_MODE) jsonOk(result); else console.log(text ? text(result) : escaped(JSON.stringify(result, null, 2))); };
2835
3073
  const needId = () => { if (!id) throw T.triggerError("E_BAD_ARGS", `oats trigger ${sub} <id>`); return id; };
2836
- const usage = "usage: oats trigger add (--file <trigger.json> | --from <package>:<template> [--set <name>=<value>]… [--id <id>]) [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>] | update <id> --description=<text> | list | show <id> | enable <id> | disable <id> | remove <id> | test <id> | status [<id>] [--dir <deployment>] [--json] (<id>: local/<id> or <member>/<id>)";
3074
+ const usage = "usage: oats trigger add (--file <trigger.json> | --from <package>:<template> [--set <name>=<value>]… [--id <id>]) [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>] | update <id> --description=<text> | list | show <id> | enable <id> | disable <id> | remove <id> | test <id> [--run-source] | poll <id> --run-source [--max-age <s>] | status [<id>] [--dir <deployment>] [--json] (<id>: local/<id> or <member>/<id>; --run-source: run a capability source's command on this host, which test and poll do only when asked)";
2837
3075
  const where = (t) => (t.origin?.kind === "workspace" ? (t.runsHere ? `runs here as ${t.owner}` : `${t.reason === "assigned-elsewhere" ? `runs on ${t.runsOn}` : t.reason ?? "disabled here"}`) : t.enabledHere ? "local" : "local, disabled");
2838
- const line = (t) => `${t.id} ${where(t)} ${t.on?.source ?? "?"} ${t.on?.repo ?? "?"} [${(t.on?.events || []).join(",")}]${t.on?.labels?.length ? ` labels ${t.on.labels.join(",")}` : ""} every ${t.on?.poll ?? "?"} → spawn ${t.spawn?.soul ?? "?"}${t.spawn?.teams?.length ? ` in ${t.spawn.teams.join(",")}` : ""}${t.invalid ? ` INVALID: ${t.invalid.message}` : ""}`;
3076
+ // A capability source names its params where the built-in names its repository.
3077
+ const watched = (on) => (T.isCapabilitySource(on?.source) ? `${on.source}${Object.keys(on.params || {}).length ? ` ${Object.entries(on.params).map(([k, v]) => `${shown(k, 40)}=${shown(v, 200)}`).join(" ")}` : ""}` : `${on?.source ?? "?"} ${on?.repo ?? "?"}`);
3078
+ // One row, one line, whatever an invalid stored definition holds (its id, labels and soul are as written too).
3079
+ const line = (t) => safeText(`${t.id} ${where(t)} ${watched(t.on)} [${T.isCapabilitySource(t.on?.source) ? shown((t.on?.events || []).join(","), 700) : (t.on?.events || []).join(",")}]${t.on?.labels?.length ? ` labels ${t.on.labels.join(",")}` : ""} every ${t.on?.poll ?? "?"} → spawn ${t.spawn?.soul ?? "?"}${t.spawn?.teams?.length ? ` in ${t.spawn.teams.join(",")}` : ""}${t.invalid ? ` INVALID: ${t.invalid.message}` : ""}`, 8000);
3080
+ // A source's own words are printed only under this label, never as the kernel's (docs/schedules.md).
3081
+ const said = (x) => (x ? `source says: ${x.code}${x.message ? `: ${x.message}` : ""}` : "");
2839
3082
  // The workspace automations of this deployment (the snapshot) placed on this host.
2840
3083
  let actx;
2841
3084
  const ctx = () => (actx ??= scopeAutomations(ws(), {}));
@@ -2863,7 +3106,31 @@ async function triggerCmd() {
2863
3106
  return out({ trigger: T.updateTriggerDescription(ws(), needId(), description, ctx()) }, (r) => line(r.trigger));
2864
3107
  }
2865
3108
  case "remove": return out(T.removeTrigger(ws(), needId(), ctx()), (r) => `removed trigger ${r.removed}${r.live.length ? ` (its live instances keep running: ${r.live.join(", ")})` : ""}`);
2866
- case "status": return out(T.triggerStatus(ws(), id, ctx()), (r) => r.triggers.map((t) => `${t.id} last poll ${t.lastPoll ? `${t.lastPoll.at} ${t.lastPoll.ok ? `ok (${t.lastPoll.matching}/${t.lastPoll.prs} PRs match)` : `FAILED: ${t.lastPoll.error}`}` : "never"} pending ${t.pending.length} fired ${t.firedTotal} live ${t.live.map((l) => l.instance).join(",") || "none"}${t.lastError ? `\n last error ${t.lastError.at}: ${t.lastError.message}` : ""}`).join("\n") || "(no triggers)");
3109
+ case "status": return out(T.triggerStatus(ws(), id, ctx()), (r) => r.triggers.map((t) => {
3110
+ if (!t.source) return `${t.id} last poll ${t.lastPoll ? `${t.lastPoll.at} ${t.lastPoll.ok ? `ok (${t.lastPoll.matching}/${t.lastPoll.prs} PRs match)` : `FAILED: ${t.lastPoll.error}`}` : "never"} pending ${t.pending.length} fired ${t.firedTotal} live ${t.live.map((l) => l.instance).join(",") || "none"}${t.lastError ? `\n last error ${t.lastError.at}: ${t.lastError.message}` : ""}`;
3111
+ const lp = t.lastPoll;
3112
+ return [`${t.id} source ${t.source.capability}:${t.source.name} last poll ${lp ? `${lp.at} ${lp.ok ? `ok (${lp.events} events, ${lp.invalidEvents} invalid, ${lp.skipped} skipped, ${lp.filtered} filtered)` : `FAILED (${lp.cause ?? "?"}): ${lp.error}`}` : "never"} pending ${t.pending.length} fired ${t.firedTotal} live ${t.live.map((l) => l.instance).join(",") || "none"}`,
3113
+ ...(t.invalid ? [` INVALID ${t.invalid.at}: ${t.invalid.code}: ${t.invalid.message}`] : []),
3114
+ ...(lp && !lp.ok && lp.source ? [` ${said(lp.source)}`] : []),
3115
+ ...t.invalidEvents.map((x) => ` invalid event (${x.rule}): ${x.text}`),
3116
+ ...t.skipped.map((x) => ` skipped ${x.subject}, source says: ${x.why}`),
3117
+ ...(t.lastError && !t.invalid ? [` last error ${t.lastError.at}: ${t.lastError.message}`] : [])].join("\n");
3118
+ }).join("\n") || "(no triggers)");
3119
+ case "poll": {
3120
+ // Runs the capability's source command now (records nothing, spawns nothing), and so only with
3121
+ // --run-source: the caller's intent, never trust consent (the tick's child passes it). The tick's own
3122
+ // child gets OATS_TRIGGER_POLL_DEADLINE (epoch ms; internal between the tick and its child,
3123
+ // not a contract): its source gets only what is left before it (lib/triggers.mjs pollViaChild).
3124
+ const raw = process.env.OATS_TRIGGER_POLL_DEADLINE;
3125
+ const deadline = raw && /^\d+$/.test(raw) ? Number(raw) : null;
3126
+ const r = await T.pollSource(ws(), needId(), { ctx: ctx(), remoteOptions: remoteOptionsFromEnv(), deadline, runSource: args.includes(T.RUN_SOURCE_FLAG) });
3127
+ if (JSON_MODE) { jsonOk(withObservation(r)); return; }
3128
+ return out(r, (x) => [`trigger ${x.id}: ${x.source.capability}:${x.source.name} listed ${x.events.length} event(s) (nothing recorded, nothing spawned)`,
3129
+ ...x.events.map((ev) => ` ${ev.event} ${ev.subject} ${ev.key}`),
3130
+ ...(x.filtered ? [` ${x.filtered} filtered (events the trigger does not select)`] : []),
3131
+ ...x.invalidEvents.map((v) => ` invalid event (${v.rule}): ${v.text}`),
3132
+ ...x.skipped.map((k) => ` skipped ${k.subject}, source says: ${k.why}`)].join("\n"));
3133
+ }
2867
3134
  case "test": {
2868
3135
  let workspaceTeams = null;
2869
3136
  try {
@@ -2873,7 +3140,23 @@ async function triggerCmd() {
2873
3140
  const shared = typeof local.workspace === "string" && !local.standalone ? (await observeWorkspace(local.workspace, { remoteOptions: remoteOptionsFromEnv() })).workspace : null;
2874
3141
  workspaceTeams = [...teamModel(shared, local).labels.keys()];
2875
3142
  } catch { /* reported as unknown (null) */ }
2876
- return out(T.testTrigger(ws(), needId(), { workspaceTeams, ctx: ctx() }), (r) => [
3143
+ // --run-source: a capability source's command runs only when asked (inert for the built-in).
3144
+ const tested = await T.testTrigger(ws(), needId(), { workspaceTeams, ctx: ctx(), remoteOptions: remoteOptionsFromEnv(), runSource: args.includes(T.RUN_SOURCE_FLAG) });
3145
+ if (tested.source) return out(tested, (r) => [
3146
+ `trigger ${r.id}: ${r.ok ? "ready" : "NOT ready"} (${r.source.invalid || r.source.cause === "resolution" ? "the source did not run" : "the source ran"}; nothing was recorded or spawned)`,
3147
+ ` placement ${r.placement.runsOn ? `runs on ${r.placement.runsOn} as ${r.placement.owner}; this host is ${r.placement.host ?? "(unnamed)"} — ${r.placement.runsHere ? "runs here" : r.placement.reason ?? "disabled here"}` : "local (this host)"}`,
3148
+ ...(r.gh ? [` gh auth ${r.gh.ok ? `ok — ${r.gh.account ?? "?"} via ${r.gh.credentialSource}` : `FAILED${r.gh.detail ? ` — ${r.gh.detail}` : ""}`}`] : []),
3149
+ ` source ${r.source.capability}:${r.source.name} ${r.source.ok ? `listed ${r.source.events.length} event(s), ${r.source.invalidEvents.length} invalid, ${r.source.skipped.length} skipped, ${r.source.filtered} filtered` : r.source.invalid ? `INVALID: ${r.source.invalid.message}` : `FAILED (${r.source.cause ?? "?"}): ${r.source.error.message}`}`,
3150
+ ...(r.source.source ? [` ${said(r.source.source)}`] : []),
3151
+ ...r.source.invalidEvents.map((v) => ` invalid (${v.rule}) ${v.text}`),
3152
+ ...r.source.skipped.map((k) => ` skipped ${k.subject}, source says: ${k.why}`),
3153
+ ` soul ${r.soul.name} ${r.soul.resolves ? `resolves${r.soul.messaging ? ` (messaging ${r.soul.messaging})` : ""}` : `does NOT resolve: ${r.soul.error.code} ${r.soul.error.message}`}`,
3154
+ ` teams ${r.teams.requested.join(", ") || "(none)"}${r.teams.undeclared?.length ? ` undeclared: ${r.teams.undeclared.join(", ")}` : ""}`,
3155
+ ` would fire ${r.wouldFire.length ? r.wouldFire.map((w) => `${w.event} ${w.subject}${w.instance ? ` as ${w.instance}` : ""}${w.held ? ` (held: ${w.held})` : ""}`).join(", ") : "nothing now"}`,
3156
+ ...r.problems.map((p) => ` problem ${p}`),
3157
+ ...(r.warnings ?? []).map((w) => ` warning ${w}`),
3158
+ ].join("\n"));
3159
+ return out(tested, (r) => [
2877
3160
  `trigger ${r.id}: ${r.ok ? "ready" : "NOT ready"} (nothing was spawned)`,
2878
3161
  ` placement ${r.placement.runsOn ? `runs on ${r.placement.runsOn} as ${r.placement.owner}; this host is ${r.placement.host ?? "(unnamed)"} — ${r.placement.runsHere ? "runs here" : r.placement.reason ?? "disabled here"}` : "local (this host)"}`,
2879
3162
  ` gh auth ${r.gh.ok ? `ok — ${r.gh.account ?? "?"} via ${r.gh.credentialSource}` : `FAILED${r.gh.detail ? ` — ${r.gh.detail}` : ""}`}`,
@@ -2916,7 +3199,9 @@ async function triggerCmd() {
2916
3199
  return out(r, printWorkspaceAdd);
2917
3200
  }
2918
3201
  if (spec === undefined) spec = await triggerFromPackage(T, String(from), sets, idFlag);
2919
- return out({ trigger: T.addTrigger(ws(), withDescription(spec, description)) }, (r) => `added ${line(r.trigger)}\n(\`oats trigger test ${r.trigger.id}\` checks gh, the repository, the soul and the teams on this host)`);
3202
+ // A capability source's meaning needs the soul's resolution (asynchronous, so here, before the write).
3203
+ await T.checkAddMeaning(ws(), T.validateTrigger({ ...spec, kind: spec?.kind ?? "trigger" }), { remoteOptions: remoteOptionsFromEnv() });
3204
+ return out({ trigger: T.addTrigger(ws(), withDescription(spec, description)) }, (r) => `added ${line(r.trigger)}\n(\`oats trigger test ${r.trigger.id}${T.isCapabilitySource(r.trigger.on?.source) ? ` ${T.RUN_SOURCE_FLAG}\` runs ${r.trigger.on.source}'s source command on this host and checks the soul and the teams)` : "` checks gh, the repository, the soul and the teams on this host)"}`);
2920
3205
  }
2921
3206
  default: throw T.triggerError("E_BAD_ARGS", usage);
2922
3207
  }
@@ -3450,7 +3735,7 @@ function versionCmd() {
3450
3735
  // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
3451
3736
  // runs on resolve/materialize (contract §6); a feature the binary does not implement is
3452
3737
  // never listed.
3453
- console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
3738
+ console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: KERNEL_FEATURES, automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
3454
3739
  return;
3455
3740
  }
3456
3741
  console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -4000,6 +4285,7 @@ else if (cmd === "update") {
4000
4285
  else if (cmd === "harness") harnessTrustCmd();
4001
4286
  else if (cmd === "readiness") await readinessCmd();
4002
4287
  else if (cmd === "instance") instanceCmd();
4288
+ else if (cmd === "worktree") await worktreeCmd();
4003
4289
  else if (cmd === "root") console.log(resolve(new URL("..", import.meta.url).pathname));
4004
4290
  else if (cmd === "sync") await syncCmd();
4005
4291
  else if (cmd === "package") await packageCmd();
@@ -4132,9 +4418,12 @@ Usage:
4132
4418
  oats schedule add|update <id> … --description=<text> a one-line summary (1-200 characters)
4133
4419
  oats schedule update <id> --description=<text> change only it (--description= clears it)
4134
4420
  oats trigger add (--file <json> | --from <package>:<template> [--set k=v]) | list | show | enable
4135
- | disable | remove <id> | test <id> | status [<id>] event-driven spawns (github.pull_request
4136
- polled with the host's gh by the schedule tick;
4137
- see docs/schedules.md#triggers)
4421
+ | disable | remove <id> | test <id> | poll <id> | status [<id>] event-driven spawns, polled
4422
+ by the schedule tick: github.pull_request (the
4423
+ host's gh) or a capability's <capability>:<source>;
4424
+ see docs/schedules.md#triggers
4425
+ oats trigger test|poll <id> --run-source run a capability source's command on this host: by
4426
+ hand, test and poll do it only when asked
4138
4427
  oats trigger add … --description=<text> a one-line summary (1-200 characters)
4139
4428
  oats trigger update <id> --description=<text> change only it (--description= clears it)
4140
4429
  oats trigger|schedule add … --workspace <member> --runs-on <host> --owner <host>/<login>
@@ -4286,6 +4575,15 @@ Usage:
4286
4575
  oats instance stop <instance> --apply --plan-revision <rev> --idempotency-key <key>
4287
4576
  quiesce (SIGTERM, bounded, never escalated),
4288
4577
  children first; home/work/launch retained
4578
+ oats worktree add --purpose <p> --branch <b> --base <remote-branch> from an instance home: make the
4579
+ [--repo <member key|clone path>] extra tree <home>/.work-<p> on a new branch at origin's
4580
+ [--preview] [--json] <base> (the clone's refs are not moved), then run the
4581
+ worktree hooks of the home's capabilities (they may take
4582
+ minutes; their output goes to stderr and .oats/logs/);
4583
+ again with the same arguments: a no-op; --preview:
4584
+ the clone, path, branch, base and hooks, nothing done
4585
+ oats worktree remove --purpose <p> [--json] git worktree remove of a tree made by add (a dirty
4586
+ tree is refused: E_WORKTREE_DIRTY); the branch is kept
4289
4587
  oats readiness (--soul <n> | --home <abs>) [--policy] [--json]
4290
4588
  readinessApi 2 for a soul or an instance home:
4291
4589
  installed | configured | member | providers, each