@awebai/oats 0.49.0 → 0.51.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/oats.mjs CHANGED
@@ -30,7 +30,7 @@ import {
30
30
  LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
31
31
  capabilityManifests, capabilityTrust, capabilityExecutablePath,
32
32
  officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
33
- findInstanceHome, findInstanceHomes, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, 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,
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, RETIRE_UNDER_CLAIM, 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`):
@@ -97,7 +98,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental"]
97
98
  * probe) and in `status --json`, which a remote roster relays as the host's (feature
98
99
  * server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
99
100
  * time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
100
- 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"];
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", "session-attach-detach-key"];
101
102
  /** Commands `--server <id>` runs on a registered server. */
102
103
  const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
103
104
  const flag = (name) => {
@@ -726,6 +727,14 @@ async function doctorJson(dir) {
726
727
  function legacyLayoutProblems(root) {
727
728
  return [legacyLocalAgents(root), legacyCapturedHomes(root)].filter(Boolean);
728
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
+ }
729
738
  async function doctorWorkspaceJson(ctx, soulName, ws) {
730
739
  const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
731
740
  const agentsRoot = join(dirname(ws.local.path), "agents");
@@ -739,7 +748,7 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
739
748
  schemaVersion: 1, workspaceApi: 2, context: ctx,
740
749
  workspace: { file: ws.local.path, ref: ws.local.workspace },
741
750
  workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
742
- information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...hookEvents.information],
751
+ information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
743
752
  composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
744
753
  ...(problems.length ? { problems } : {}),
745
754
  warnings: hookEvents.warnings,
@@ -784,7 +793,8 @@ async function doctor(dir) {
784
793
  for (const p of operator.problems) console.log(`\n! ${p.code}: ${p.message}\n ${p.remedy}`);
785
794
  const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
786
795
  for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
787
- for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...hookEvents.information]) console.log(`\nINFO: ${line}`);
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")}`);
788
798
  if (soulName) {
789
799
  const information = operationalKnowledgeNote(composition, soulName);
790
800
  if (information) console.log(`\nINFO: ${information}`);
@@ -1364,7 +1374,7 @@ function sayReadNotices() {
1364
1374
  }
1365
1375
  /** Which kernel command forms take --max-age: THE allow-list (docs/desktop-cli-api.md "Observation reuse").
1366
1376
  * → null when this form reads with observation reuse, else the E_BAD_ARGS message. `head` is argv before `--`. */
1367
- 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";
1368
1378
  function maxAgeRefusal(command, head) {
1369
1379
  const word = (i) => (head[i] !== undefined && !head[i].startsWith("--") ? head[i] : undefined);
1370
1380
  const refuse = (form) => `--max-age is not accepted by \`oats ${form}\`: only the read verbs reuse observations (${MAX_AGE_READS})`;
@@ -1377,6 +1387,8 @@ function maxAgeRefusal(command, head) {
1377
1387
  case "teams": return word(1) === undefined ? null : refuse(`teams ${word(1)}`);
1378
1388
  // `soul teams` only reads (its edit flags were removed in 0.38.0, and refuse as such).
1379
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(" "));
1380
1392
  default: {
1381
1393
  const sub = ["package", "schedule", "session", "trigger", "automations", "launch-config", "server", "instance", "operation", "pane"].includes(command) ? word(1) : undefined;
1382
1394
  return refuse([command, sub].filter(Boolean).join(" "));
@@ -1718,7 +1730,9 @@ async function addWorkspaceAutomation(desc, { id, body, description }) {
1718
1730
  const content = A.automationFileText(desc, { id, description: description || undefined, runsOn, owner, body });
1719
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 });
1720
1732
  if (parsed.problem) bail(parsed.problem.code, parsed.problem.message, { path: parsed.problem.path });
1721
- 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 });
1722
1736
  const sameRepo = (url) => { try { return remoteModule.parseRepoRef(url).key === row.key; } catch { return false; } };
1723
1737
  const at = A.memberCheckoutFor(dirFlag(), desc, id, { sameRepo });
1724
1738
  const file = { member: name, repoKey: row.key, path: `${desc.folder}/${id}.yaml`, content };
@@ -2155,6 +2169,17 @@ async function capabilityShowCmd(bail) {
2155
2169
  if (skill.filesTruncated) console.log(` … more files (the first ${S.FILES_PER_SKILL} are listed)`);
2156
2170
  }
2157
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
+ }
2158
2183
  for (const p of doc.problems) console.log(` problem: ${p.code}${p.path ? ` ${p.path}` : ""} — ${p.message}`);
2159
2184
  for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
2160
2185
  console.log(`\n a file's text: oats capabilities show ${doc.name}${doc.kind === "package" ? ` --package ${doc.package}` : ""} --file <path>`);
@@ -2623,8 +2648,13 @@ async function spawnCmd() {
2623
2648
  if (f !== undefined) {
2624
2649
  if (!existsSync(f)) bail("E_BAD_ARGS", `--trigger-event not found: ${f}`);
2625
2650
  try { triggerEvent = JSON.parse(readFileSync(f, "utf8")); } catch (e) { bail("E_BAD_ARGS", `--trigger-event is not valid JSON: ${e.message}`); }
2626
- 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";
2627
- 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)");
2628
2658
  } }
2629
2659
  const relativeRoot = flag("relative-root");
2630
2660
  if (relativeRoot !== undefined && (relativeRoot === true || !String(relativeRoot).trim())) bail("E_BAD_ARGS", "--relative-root needs an agents-root path");
@@ -2844,27 +2874,42 @@ function retireCmd() {
2844
2874
  // resolved the home). A guarded apply acts on the children of the plan it
2845
2875
  // revalidated; a plain or --self retire computes them as the plan does, and
2846
2876
  // passes none when there are none.
2847
- let replayPath = null, plannedExtraWorktrees, fresh, children;
2877
+ let replayPath = null, fresh, revalidate, stalePlan, planFailure;
2848
2878
  if (planRev !== undefined) {
2849
2879
  if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
2850
2880
  // Replay first: after a successful retire the home is gone, so the receipt
2851
2881
  // (beside the instances dir, keyed by the idempotency key) is the answer.
2852
2882
  const replay = (dir) => { const p = join(dir, `.oats-retire-receipt.${idemKey}.json`); if (!existsSync(p)) return false; try { const prior = JSON.parse(readFileSync(p, "utf8")); if (prior.retired !== name) return false; if (args.includes("--json")) jsonOk({ ...prior, replayed: true }); else console.log(`retire ${name}: replayed receipt for key ${idemKey}`); return true; } catch { return false; } };
2853
2883
  for (const a of listAgents(root)) if (replay(join(a._dir, "instances"))) return;
2854
- try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message); }
2855
- replayPath = join(dirname(fresh.home), `.oats-retire-receipt.${idemKey}.json`);
2856
- // The extra trees the confirmed plan names, as it names them: the retire refuses as stale rather than
2857
- // move or remove one that no longer reads that way when it gets to them.
2858
- plannedExtraWorktrees = fresh.facts.extraWorktrees;
2859
- if (fresh.planRevision !== planRev) return args.includes("--json") ? jsonFail("E_PLAN_STALE", `the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`, { plan: fresh }) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
2860
- children = fresh.facts.children;
2884
+ // Before the claim, only the home: where the receipt goes, and the answers of a name that
2885
+ // resolves to no home, to several or to another one.
2886
+ let target;
2887
+ try { target = resolveInstanceForCli(dirFlag(), root, name, { home: homeFlag }); } catch (e) { return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message); }
2888
+ replayPath = join(dirname(target.home), `.oats-retire-receipt.${idemKey}.json`);
2889
+ // The plan the revision is checked against is read once, by retireInstance, when it holds the
2890
+ // home's claim (RETIRE_UNDER_CLAIM): nobody else is retiring the home by then, so the plan is
2891
+ // the state the retire starts from. Against another retire of this home the answer is that one
2892
+ // is running (E_LIFECYCLE_BUSY), and no plan is read. A revision that no longer matches is
2893
+ // refused there, and nothing was done. What the retire takes from the plan: its children, and
2894
+ // its extra trees as it names them (the retire refuses as stale rather than move or remove one
2895
+ // that no longer reads that way when it gets to them).
2896
+ revalidate = () => {
2897
+ try { fresh = planRetire(dirFlag(), root, name, { home: homeFlag }); } catch (e) { planFailure = e; throw e; }
2898
+ if (fresh.planRevision !== planRev) throw (stalePlan = Object.assign(new Error(`the retire plan changed since it was shown (${planRev} → ${fresh.planRevision}); review the fresh plan`), { code: "E_PLAN_STALE", details: { plan: fresh } }));
2899
+ return { plannedExtraWorktrees: fresh.facts.extraWorktrees, children: fresh.facts.children };
2900
+ };
2861
2901
  } else {
2862
- const recorded = descendantsOf(root, name);
2863
- if (recorded.length) children = recorded;
2902
+ // A plain or --self retire reads its recorded children the same way: under the claim, as they
2903
+ // are when the retire starts (an earlier retire that kept the home has repaired lineage by
2904
+ // then), and none when there are none.
2905
+ revalidate = () => { const recorded = descendantsOf(root, name); return recorded.length ? { children: recorded } : {}; };
2864
2906
  }
2865
2907
  let r;
2866
- try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), ...(plannedExtraWorktrees ? { plannedExtraWorktrees } : {}), ...(children ? { children } : {}) }); }
2908
+ try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force"), [RETIRE_UNDER_CLAIM]: revalidate }); }
2867
2909
  catch (e) {
2910
+ // The plan could not be read, or its revision is not the one shown: the answers they always had.
2911
+ if (e === planFailure) return args.includes("--json") ? jsonFail(e.code || "E_LIFECYCLE_FAILED", e.message, e.details) : die(e.message);
2912
+ if (e === stalePlan) return args.includes("--json") ? jsonFail(e.code, e.message, e.details) : die(`the retire plan changed since it was shown; re-run oats retire ${name} --plan`);
2868
2913
  if (!e?.code) throw e;
2869
2914
  // A child still running (or whose stop could not be established) refused the retirement: the
2870
2915
  // guarded apply returns the plan it acted on, and the text names each child's reason.
@@ -3031,13 +3076,24 @@ async function triggerCmd() {
3031
3076
  const sub = args[1];
3032
3077
  const id = args[2] && !args[2].startsWith("--") ? args[2] : undefined;
3033
3078
  const T = await import("../lib/triggers.mjs");
3079
+ const { REFUSED_TEXT, safeText } = await import("../lib/refused-text.mjs");
3034
3080
  let scope;
3035
3081
  const ws = () => (scope ??= scheduleScopeOf(dirFlag()));
3036
- const out = (result, text) => { if (JSON_MODE) jsonOk(result); else console.log(text ? text(result) : JSON.stringify(result, null, 2)); };
3082
+ // A stored definition that fails validation is still listed and shown, as it was written: what a
3083
+ // terminal gets of it never carries a refused character. In a row's text it is replaced (`shown`);
3084
+ // in the JSON `show` prints as text it is escaped (\uXXXX; the layout's own newlines stay), so the document's value is unchanged.
3085
+ const shown = (v, max) => safeText(typeof v === "string" ? v : JSON.stringify(v) ?? String(v), max);
3086
+ 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("")));
3087
+ const out = (result, text) => { if (JSON_MODE) jsonOk(result); else console.log(text ? text(result) : escaped(JSON.stringify(result, null, 2))); };
3037
3088
  const needId = () => { if (!id) throw T.triggerError("E_BAD_ARGS", `oats trigger ${sub} <id>`); return id; };
3038
- 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>)";
3089
+ 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)";
3039
3090
  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");
3040
- 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}` : ""}`;
3091
+ // A capability source names its params where the built-in names its repository.
3092
+ 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 ?? "?"}`);
3093
+ // One row, one line, whatever an invalid stored definition holds (its id, labels and soul are as written too).
3094
+ 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);
3095
+ // A source's own words are printed only under this label, never as the kernel's (docs/schedules.md).
3096
+ const said = (x) => (x ? `source says: ${x.code}${x.message ? `: ${x.message}` : ""}` : "");
3041
3097
  // The workspace automations of this deployment (the snapshot) placed on this host.
3042
3098
  let actx;
3043
3099
  const ctx = () => (actx ??= scopeAutomations(ws(), {}));
@@ -3065,7 +3121,31 @@ async function triggerCmd() {
3065
3121
  return out({ trigger: T.updateTriggerDescription(ws(), needId(), description, ctx()) }, (r) => line(r.trigger));
3066
3122
  }
3067
3123
  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(", ")})` : ""}`);
3068
- 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)");
3124
+ case "status": return out(T.triggerStatus(ws(), id, ctx()), (r) => r.triggers.map((t) => {
3125
+ 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}` : ""}`;
3126
+ const lp = t.lastPoll;
3127
+ 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"}`,
3128
+ ...(t.invalid ? [` INVALID ${t.invalid.at}: ${t.invalid.code}: ${t.invalid.message}`] : []),
3129
+ ...(lp && !lp.ok && lp.source ? [` ${said(lp.source)}`] : []),
3130
+ ...t.invalidEvents.map((x) => ` invalid event (${x.rule}): ${x.text}`),
3131
+ ...t.skipped.map((x) => ` skipped ${x.subject}, source says: ${x.why}`),
3132
+ ...(t.lastError && !t.invalid ? [` last error ${t.lastError.at}: ${t.lastError.message}`] : [])].join("\n");
3133
+ }).join("\n") || "(no triggers)");
3134
+ case "poll": {
3135
+ // Runs the capability's source command now (records nothing, spawns nothing), and so only with
3136
+ // --run-source: the caller's intent, never trust consent (the tick's child passes it). The tick's own
3137
+ // child gets OATS_TRIGGER_POLL_DEADLINE (epoch ms; internal between the tick and its child,
3138
+ // not a contract): its source gets only what is left before it (lib/triggers.mjs pollViaChild).
3139
+ const raw = process.env.OATS_TRIGGER_POLL_DEADLINE;
3140
+ const deadline = raw && /^\d+$/.test(raw) ? Number(raw) : null;
3141
+ const r = await T.pollSource(ws(), needId(), { ctx: ctx(), remoteOptions: remoteOptionsFromEnv(), deadline, runSource: args.includes(T.RUN_SOURCE_FLAG) });
3142
+ if (JSON_MODE) { jsonOk(withObservation(r)); return; }
3143
+ return out(r, (x) => [`trigger ${x.id}: ${x.source.capability}:${x.source.name} listed ${x.events.length} event(s) (nothing recorded, nothing spawned)`,
3144
+ ...x.events.map((ev) => ` ${ev.event} ${ev.subject} ${ev.key}`),
3145
+ ...(x.filtered ? [` ${x.filtered} filtered (events the trigger does not select)`] : []),
3146
+ ...x.invalidEvents.map((v) => ` invalid event (${v.rule}): ${v.text}`),
3147
+ ...x.skipped.map((k) => ` skipped ${k.subject}, source says: ${k.why}`)].join("\n"));
3148
+ }
3069
3149
  case "test": {
3070
3150
  let workspaceTeams = null;
3071
3151
  try {
@@ -3075,7 +3155,23 @@ async function triggerCmd() {
3075
3155
  const shared = typeof local.workspace === "string" && !local.standalone ? (await observeWorkspace(local.workspace, { remoteOptions: remoteOptionsFromEnv() })).workspace : null;
3076
3156
  workspaceTeams = [...teamModel(shared, local).labels.keys()];
3077
3157
  } catch { /* reported as unknown (null) */ }
3078
- return out(T.testTrigger(ws(), needId(), { workspaceTeams, ctx: ctx() }), (r) => [
3158
+ // --run-source: a capability source's command runs only when asked (inert for the built-in).
3159
+ const tested = await T.testTrigger(ws(), needId(), { workspaceTeams, ctx: ctx(), remoteOptions: remoteOptionsFromEnv(), runSource: args.includes(T.RUN_SOURCE_FLAG) });
3160
+ if (tested.source) return out(tested, (r) => [
3161
+ `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)`,
3162
+ ` 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)"}`,
3163
+ ...(r.gh ? [` gh auth ${r.gh.ok ? `ok — ${r.gh.account ?? "?"} via ${r.gh.credentialSource}` : `FAILED${r.gh.detail ? ` — ${r.gh.detail}` : ""}`}`] : []),
3164
+ ` 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}`}`,
3165
+ ...(r.source.source ? [` ${said(r.source.source)}`] : []),
3166
+ ...r.source.invalidEvents.map((v) => ` invalid (${v.rule}) ${v.text}`),
3167
+ ...r.source.skipped.map((k) => ` skipped ${k.subject}, source says: ${k.why}`),
3168
+ ` 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}`}`,
3169
+ ` teams ${r.teams.requested.join(", ") || "(none)"}${r.teams.undeclared?.length ? ` undeclared: ${r.teams.undeclared.join(", ")}` : ""}`,
3170
+ ` 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"}`,
3171
+ ...r.problems.map((p) => ` problem ${p}`),
3172
+ ...(r.warnings ?? []).map((w) => ` warning ${w}`),
3173
+ ].join("\n"));
3174
+ return out(tested, (r) => [
3079
3175
  `trigger ${r.id}: ${r.ok ? "ready" : "NOT ready"} (nothing was spawned)`,
3080
3176
  ` 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)"}`,
3081
3177
  ` gh auth ${r.gh.ok ? `ok — ${r.gh.account ?? "?"} via ${r.gh.credentialSource}` : `FAILED${r.gh.detail ? ` — ${r.gh.detail}` : ""}`}`,
@@ -3118,7 +3214,9 @@ async function triggerCmd() {
3118
3214
  return out(r, printWorkspaceAdd);
3119
3215
  }
3120
3216
  if (spec === undefined) spec = await triggerFromPackage(T, String(from), sets, idFlag);
3121
- 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)`);
3217
+ // A capability source's meaning needs the soul's resolution (asynchronous, so here, before the write).
3218
+ await T.checkAddMeaning(ws(), T.validateTrigger({ ...spec, kind: spec?.kind ?? "trigger" }), { remoteOptions: remoteOptionsFromEnv() });
3219
+ 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)"}`);
3122
3220
  }
3123
3221
  default: throw T.triggerError("E_BAD_ARGS", usage);
3124
3222
  }
@@ -3141,7 +3239,9 @@ async function sessionCmd() {
3141
3239
  let result;
3142
3240
  if (args[1] === "attach") {
3143
3241
  if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
3144
- process.exitCode = await attachInstanceSession(home);
3242
+ // --detach-key (feature session-attach-detach-key): the one key that leaves this viewer, with
3243
+ // status 20. Without it every key reaches the agent and there is no keyboard exit.
3244
+ process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key") });
3145
3245
  return;
3146
3246
  }
3147
3247
  if (args[1] === "inspect") result = inspectInstanceSession(home);
@@ -3181,7 +3281,7 @@ async function sessionCmd() {
3181
3281
  const file = flag("file");
3182
3282
  if (!file || file === true) throw Object.assign(new Error("session upload needs --file <local path>"), { code: "E_BAD_ARGS" });
3183
3283
  result = uploadAttachment({ file, home: home === true ? undefined : home });
3184
- } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
3284
+ } else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--detach-key key] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
3185
3285
  if (JSON_MODE) jsonOk(result);
3186
3286
  else {
3187
3287
  console.log(JSON.stringify(result, null, 2));
@@ -4008,8 +4108,14 @@ async function serverRouteCmd() {
4008
4108
  return;
4009
4109
  }
4010
4110
  if (args[1] !== "attach") bail("E_USAGE", "--server routes `session inspect`, `session start`, `session restart`, `session upload` and `session attach`; input runs on the execution host (the wake broker calls it there)");
4111
+ // --detach-key travels only to a host that advertises session-attach-detach-key (attachArgv
4112
+ // probes for it, under --print too). The key may be C-\, the tty's QUIT character: pressed
4113
+ // once ssh has given the tty back, it reaches this process as SIGQUIT, whose default action
4114
+ // would replace the relayed status with 131. Held from here until this process exits.
4115
+ const detachKey = valueFlag("detach-key");
4116
+ if (detachKey !== undefined) process.on("SIGQUIT", () => {});
4011
4117
  let route;
4012
- try { route = attachArgv(id, addr, { skipVersionCheck: args.includes("--print") }); }
4118
+ try { route = attachArgv(id, { ...addr, detachKey }, { skipVersionCheck: args.includes("--print") }); }
4013
4119
  // ssh failing before the viewer (the version probe, a name resolved through the host's roster)
4014
4120
  // is the failure ssh has under it: exit 255, on which a caller reconnects. Every other refusal,
4015
4121
  // and an ssh that never started (no link can come back), exits 1.
@@ -4019,7 +4125,7 @@ async function serverRouteCmd() {
4019
4125
  // ssh exits 255 for its own failures: a link that died under the viewer
4020
4126
  // (keepalives unanswered, the master or the host's sshd gone), or one
4021
4127
  // never made. Say what is known rather than ending silently.
4022
- if (r.status === 255) console.error(`\noats: ssh to ${route.target.sshHost} ended with an error (exit 255); if the link was lost, the instance keeps running on ${id}. Reattach with: oats session attach --server ${id} --home ${shellQuote(route.home)}`);
4128
+ if (r.status === 255) console.error(`\noats: ssh to ${route.target.sshHost} ended with an error (exit 255); if the link was lost, the instance keeps running on ${id}. Reattach with: oats session attach --server ${id} --home ${shellQuote(route.home)}${detachKey !== undefined ? ` --detach-key ${shellQuote(detachKey)}` : ""}`);
4023
4129
  process.exit(r.status ?? 1);
4024
4130
  }
4025
4131
  // A spawn's argv is checked here, before the server is contacted.
@@ -4303,7 +4409,9 @@ Usage:
4303
4409
  --instance <name> [--json] saved home on its host
4304
4410
  oats session inspect|attach --server <id> inspect (envelope) or attach a viewer (ssh PTY) for a
4305
4411
  --instance <name> | --home <abs> remote instance, by its saved route or the server's
4306
- roster (--print shows attach); oats 0.22.2 or later
4412
+ [--detach-key <key>] roster (--print shows attach); oats 0.22.2 or later.
4413
+ attach --detach-key: as below; the server must
4414
+ advertise session-attach-detach-key
4307
4415
  oats session start --server <id> start a stopped remote instance in its existing home
4308
4416
  --instance <name> | --home <abs> by its saved route or the server's roster; it must advertise
4309
4417
  [--model <m>] [--json] session-start (oats 0.22.9 or later)
@@ -4326,6 +4434,11 @@ Usage:
4326
4434
  [--check] --check: write nothing; report <dir> (~ = this home),
4327
4435
  its state and whether Git reads the workspace remote
4328
4436
  oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
4437
+ oats session attach --home <absolute-home> [--detach-key <key>]
4438
+ a viewer of one instance. <key> (C-<letter>, M-<letter
4439
+ or digit>, F1 to F12; 'C-\\' is the suggested one)
4440
+ leaves it with exit status 20; without one no key
4441
+ leaves it: every key goes to the agent
4329
4442
  oats schedule list|show <id>|test <id>|add <id> --file <spec.json>|update <id> --file <spec.json>
4330
4443
  enable|disable|run|remove|reconcile <id> workspace-scoped, host-owned schedules (spawn,
4331
4444
  tick [--dry-run] [--host] command or wake jobs on a five-field cron with an
@@ -4335,9 +4448,12 @@ Usage:
4335
4448
  oats schedule add|update <id> … --description=<text> a one-line summary (1-200 characters)
4336
4449
  oats schedule update <id> --description=<text> change only it (--description= clears it)
4337
4450
  oats trigger add (--file <json> | --from <package>:<template> [--set k=v]) | list | show | enable
4338
- | disable | remove <id> | test <id> | status [<id>] event-driven spawns (github.pull_request
4339
- polled with the host's gh by the schedule tick;
4340
- see docs/schedules.md#triggers)
4451
+ | disable | remove <id> | test <id> | poll <id> | status [<id>] event-driven spawns, polled
4452
+ by the schedule tick: github.pull_request (the
4453
+ host's gh) or a capability's <capability>:<source>;
4454
+ see docs/schedules.md#triggers
4455
+ oats trigger test|poll <id> --run-source run a capability source's command on this host: by
4456
+ hand, test and poll do it only when asked
4341
4457
  oats trigger add … --description=<text> a one-line summary (1-200 characters)
4342
4458
  oats trigger update <id> --description=<text> change only it (--description= clears it)
4343
4459
  oats trigger|schedule add … --workspace <member> --runs-on <host> --owner <host>/<login>
@@ -205,8 +205,9 @@ A self-contained package has an `oats.json`:
205
205
  Whether the process exists is the operating system's answer (`kill -0`:
206
206
  "no such process" is gone, another user's process exists), the same on
207
207
  every host. Only then is its start time read: from `/proc`, or with `ps`
208
- (in a fixed `LC_ALL=C`, `TZ=UTC` environment) where there is no `/proc`,
209
- as on macOS. A start that cannot be read is never taken to mean the process is
208
+ where there is no `/proc`, as on macOS: the system `ps`, from
209
+ `/usr/bin:/bin` whatever the caller's `PATH` holds, in a fixed `LC_ALL=C`,
210
+ `TZ=UTC` environment. A start that cannot be read is never taken to mean the process is
210
211
  gone, nor shown as alive: `oats status` shows the quarantine
211
212
  (`rollbackIncomplete`, whose `inProgress` names the pid), and `oats retire`
212
213
  refuses with `E_LIFECYCLE_BUSY`, naming the recorded pid and start for a
@@ -353,6 +354,9 @@ A self-contained package has an `oats.json`:
353
354
  separate from declaring the package.
354
355
  - `environment` lists the exact launch variables the capability may set;
355
356
  spawn hook output must be a subset and use the capability vendor prefix.
357
+ - `triggerSources` (optional) declares the capability's
358
+ [trigger sources](#trigger-sources-triggersources). It is checked only
359
+ where a source is used, never when the capability loads.
356
360
  - Target names never appear in a package manifest.
357
361
 
358
362
  `capability` is the only manifest identity field; it may also carry
@@ -1264,3 +1268,169 @@ checks in one readiness read share 60 s, and checks the budget does not reach
1264
1268
  are not run (`unknown`, `time-budget-exhausted`). Answer from configuration
1265
1269
  and local state. A provider that must call a remote service should bound that
1266
1270
  call well inside the 30 s.
1271
+
1272
+ ## Trigger sources (`triggerSources`)
1273
+
1274
+ A capability may declare **trigger sources**: each is one of its own commands
1275
+ that, at each poll, lists the events that are due now. A
1276
+ [trigger](schedules.md#capability-sources) names one as `on.source:
1277
+ "<capability>:<source>"`, and the kernel keeps everything after the list:
1278
+ event keys, at-least-once recording, pending events, concurrency, the
1279
+ instance name, the event file and the spawn.
1280
+
1281
+ ```json
1282
+ "commands": { "review-source": "bin/graph.mjs review-source" },
1283
+ "triggerSources": {
1284
+ "harvest-branches": {
1285
+ "command": "review-source",
1286
+ "description": "Ready harvest/* branches, one event per judged head",
1287
+ "events": ["opened", "updated"],
1288
+ "parameters": { "prefix": { "default": "harvest/", "description": "Branch prefix", "pattern": "^[A-Za-z0-9._/-]{1,80}$" } },
1289
+ "fields": { "graph": { "pattern": "^[a-z0-9-]{1,40}$" }, "branch": {} },
1290
+ "urlHosts": ["graph.example.org"]
1291
+ }
1292
+ }
1293
+ ```
1294
+
1295
+ - **The source name** is 1 to 40 lowercase letters, digits and dashes,
1296
+ starting with a letter or digit. At most 16 sources.
1297
+ - **`command`** names one of `commands`. Its script must resolve to a regular
1298
+ file inside the module directory.
1299
+ - **`description`** (optional): one line of at most 200 characters.
1300
+ - **`events`**: 1 to 16 distinct names, each 1 to 40 lowercase letters,
1301
+ digits and underscores, starting with a letter.
1302
+ - **`parameters`** (optional, at most 16), named with a letter then letters,
1303
+ digits and underscores (at most 40): `{ required?, default?, description?,
1304
+ pattern? }`. A value is a string of at most 200 characters matching
1305
+ `pattern`, by default `^[A-Za-z0-9._/:@ ,*-]{0,200}$`; a `default` must
1306
+ match it too. Parameters reach the source only, never a task.
1307
+ - **`fields`** (optional, at most 16, named as parameters): `{ pattern? }`, by
1308
+ default `^[A-Za-z0-9._/:@-]{1,200}$`. A trigger's template may name a
1309
+ declared field as `{fields.<name>}`; the value is the event's, validated.
1310
+ Whatever the pattern admits (`.*` included), a value longer than 200
1311
+ characters (code points), or carrying a control character, a line or
1312
+ paragraph separator, a bidi control, U+200B, U+2060, U+FEFF or a tag
1313
+ character, makes its event invalid, and the pattern is never run on one.
1314
+ - **Patterns** are JavaScript regular expressions with the `u` flag (the flag
1315
+ JSON Schema's `pattern` uses), compiled once and always matched whole: the
1316
+ kernel wraps each as `^(?:…)$`. One that does not compile makes the source
1317
+ malformed.
1318
+ - **`urlHosts`** (optional, at most 16): the exact lowercase hostnames an
1319
+ event's `url` may name. With none declared, an event's `url` is invalid.
1320
+ The allow-list lives here, never on an event. An event's `url` must also be
1321
+ printable ASCII with no space (`0x21`–`0x7e`) as written: percent-encode
1322
+ anything else.
1323
+
1324
+ **Containment.** A malformed `triggerSources` **never refuses the
1325
+ capability**. It is not part of the manifest contract that spawn, discovery
1326
+ and the lock check: they ignore it. It is validated only where a source is
1327
+ used, by `trigger add`, a poll, `trigger test` and `trigger poll`, **per
1328
+ source**: a malformed source fails only the triggers naming it
1329
+ (`E_TRIGGER_SOURCE`, `details: { capability, source, pointer }`, the pointer
1330
+ into the manifest), and a well-formed sibling keeps working. A malformed top
1331
+ level (not an object, or more than 16 sources) fails every trigger naming the
1332
+ capability. `oats capabilities show <name> --json` adds `triggerSources`,
1333
+ exactly as declared, and, when the declaration has any, the problems a trigger
1334
+ would get as `triggerSourceProblems: [{ source, pointer, message }]`
1335
+ (`source` `null` for the top level); it never refuses the command. The
1336
+ closed sub-schema is in
1337
+ [`capability-manifest.schema.json`](capability-manifest.schema.json); what a
1338
+ schema cannot say (a pattern compiles, `command` names a command, a default
1339
+ matches its pattern) is checked at use only.
1340
+
1341
+ **Schema tooling.** The runtime ignores manifest keys it does not know, but
1342
+ until this release the published `capability-manifest.schema.json` was closed
1343
+ at the top level (`additionalProperties: false`). A tool validating a manifest
1344
+ against an older copy of the schema flags `triggerSources`: the repository's
1345
+ own `validate-project`, the package dry-run checks, a provider's CI that pins
1346
+ the schema. Validate against this release's schema, or declare the key once
1347
+ your tooling uses it. A provider declaring `triggerSources` does not need to
1348
+ raise `compatibility.oats`: every workspace-model kernel ignores the key, and
1349
+ only the host that runs a trigger naming the source needs this release.
1350
+
1351
+ **Invocation.** A poll runs the command's script with `node`, from the
1352
+ capability's directory in the deployment's verified module store (the
1353
+ capability at its resolved commit, digest-verified, for a member capability
1354
+ as for a package one), with the command's words after the script as
1355
+ arguments and no shell. The host tick runs it through a child `oats trigger
1356
+ poll <id> --run-source --max-age 600`; a person, through `oats trigger poll
1357
+ <id> --run-source` or `oats trigger test <id> --run-source`. Those
1358
+ **execute the capability's source command** whatever the host's trust and
1359
+ the trigger's `runsOn` say, and so only with `--run-source`: without it they
1360
+ are refused (`E_TRIGGER_SOURCE_RUN`) before anything of the capability runs
1361
+ or is written. The flag is caller intent, never trust consent: see
1362
+ [schedules.md](schedules.md#capability-sources). A poll records nothing on
1363
+ its own; the tick records what it folds.
1364
+
1365
+ **Request** — one JSON document on stdin, with exactly these keys:
1366
+
1367
+ ```json
1368
+ {"schemaVersion":1,"phase":"poll","capability":"acme.graph","source":"harvest-branches","trigger":"local/harvest-review",
1369
+ "params":{"prefix":"harvest/"},"settings":{"store":"~/.graph"},
1370
+ "input":{"context":{"kind":"workspace","workspace":"github.com/acme/agents","deployment":"/srv/acme",
1371
+ "soul":"graph-reviewer","host":"kb-bot-server"}}}
1372
+ ```
1373
+
1374
+ - `trigger` is the qualified trigger id.
1375
+ - `params` are the trigger's, with the declared defaults applied (a parameter
1376
+ with neither a value nor a default is absent).
1377
+ - `settings` is the merged provider payload the trigger's soul resolves for
1378
+ the capability.
1379
+ - `host` is this host's `host.name`, or `null`.
1380
+
1381
+ **Environment:** the one a `--soul` [readiness check](#readiness-check-bindingcheck)
1382
+ gets, for the trigger's soul: every ambient `OATS_*`, `OAS_*` and `PI_*`
1383
+ variable removed, the rest inherited, and the kernel's `OATS_CAPABILITY`,
1384
+ `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, `OATS_CLI_BIN`, `OATS_WORKSPACE`,
1385
+ the team variables, `OATS_AGENT`, `OATS_SOUL_ID` and `OATS_SOUL`. There is no
1386
+ `OATS_INSTANCE` or `OATS_INSTANCE_HOME`, and the kernel passes no credential.
1387
+ Under the host timer, the inherited environment is the timer's (only `PATH`
1388
+ and `OATS_HOME_DIR`): keep the source's login in its own store under `HOME`,
1389
+ not in an exported variable.
1390
+
1391
+ **Answer** — exit 0, and exactly one JSON document on stdout, at most 1 MiB
1392
+ (whitespace around it is fine; progress text is not):
1393
+
1394
+ ```json
1395
+ {"schemaVersion":1,"phase":"poll","capability":"acme.graph","source":"harvest-branches","ok":true,
1396
+ "result":{"events":[{"key":"harvest/x:9f2c41d","subject":"harvest/x","event":"opened",
1397
+ "url":"https://graph.example.org/x","fields":{"graph":"kb","branch":"harvest/x"}}],
1398
+ "skipped":[{"subject":"harvest/y","why":"not judged yet"}]}}
1399
+ ```
1400
+
1401
+ - **The envelope** has exactly `schemaVersion, phase, capability, source, ok,
1402
+ result`; `schemaVersion`, `phase`, `capability` and `source` echo the
1403
+ request. `result` is `{ events, skipped? }`, exactly.
1404
+ - **A refusal** is `{…, "ok": false, "error": { "code", "message"? }}`.
1405
+ - **An event** is `{ key, subject, event, url?, fields? }`: the rules are in
1406
+ [schedules.md](schedules.md#capability-sources). An invalid event is
1407
+ dropped alone; the others go on.
1408
+ - **`skipped`** (optional) is `[{ subject, why }]`: what the source looked at
1409
+ and chose not to list, shown in `trigger status` and `trigger test`.
1410
+
1411
+ | Outcome | `E_TRIGGER_POLL` `details.cause` | recorded |
1412
+ |---|---|---|
1413
+ | nonzero exit or a signal | `exit` | nothing; pending events kept |
1414
+ | not exactly one JSON document, unknown keys, a wrong echo, a malformed `result`, over 1 MiB | `result` | nothing |
1415
+ | more than 500 events, or more than 100 skipped | `too-many-events` | nothing |
1416
+ | over 30 s (killed) | `timeout` | nothing |
1417
+ | `ok: false` | `refused`, with `details.source: { code, message? }` | nothing |
1418
+ | the soul does not resolve | `resolution` | nothing |
1419
+ | the trigger's meaning does not hold | (`E_TRIGGER_SOURCE` / `E_TRIGGER_INVALID`) | nothing; the source does not run |
1420
+
1421
+ **Your text is untrusted.** A skipped item's `why`, a refusal's `message` and
1422
+ its `code` are never composed into a task or any kernel sentence. They are
1423
+ kept only in fields that name the source and printed under `source says:`,
1424
+ capped (`why` 200 characters, `message` 500, `code` 128) and with every
1425
+ control character, line or paragraph separator, bidi control, U+200B,
1426
+ U+2060, U+FEFF and tag character replaced by U+FFFD. What a task may carry
1427
+ (`{subject}`, `{key}`, `{url}`, `{fields.<name>}`) is refused rather than
1428
+ replaced: an event whose `url` is not printable ASCII, or whose field value
1429
+ is longer than 200 characters or carries one of those characters whatever
1430
+ its pattern admits, is an invalid event.
1431
+
1432
+ **Time.** A source gets at most 30 s and is killed after that; the tick's
1433
+ whole poll, resolution included, gets 35 s, and polls run only while they can
1434
+ end within 50 s of the tick's start. Answer from a cache or a quick query: a
1435
+ source slower than that should cache.
1436
+