@awebai/oats 0.39.4 → 0.40.1

package/bin/oats.mjs

@@ -46,7 +46,7 @@ import { attachArgv, checkRemote, connectServer, forgetSnapshot, getServer, insp
 import { spawnSync as spawnSyncProc } from "node:child_process";
 import { tickTriggers } from "../lib/triggers.mjs";
 import * as A from "../lib/automations.mjs";
-import { parseEnvelopeText, scheduleScopeOf, listSchedules, describe as describeSchedule, testSchedule, addSchedule, updateSchedule, setEnabled as setScheduleEnabled, removeSchedule, runNow as runScheduleNow, reconcile as reconcileSchedule, tickHost, tickWorkspace, scopeAutomations, scheduleKind, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } from "../lib/schedule.mjs";
+import { parseEnvelopeText, unresolvedScheduleAttempts, scheduleScopeOf, listSchedules, describe as describeSchedule, testSchedule, addSchedule, updateSchedule, setEnabled as setScheduleEnabled, removeSchedule, runNow as runScheduleNow, reconcile as reconcileSchedule, tickHost, tickWorkspace, scopeAutomations, scheduleKind, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } from "../lib/schedule.mjs";
 import { hostUnitStatus, installHostUnit, uninstallHostUnit } from "../lib/schedule-host.mjs";
 import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
 
@@ -54,7 +54,7 @@ import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
 import { planStop, applyStop, planRetire, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
 const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
 import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
-import { readEvents } from "../lib/instance-events.mjs";
+import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
 
 const rawArgs = process.argv.slice(2);
 /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
@@ -63,19 +63,25 @@ const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear"
  *  routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
  *  `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
  *  expanded, it would be a flag token every reader sees, which the spaced form can never carry. */
+/** Free-text flags whose inline value may start with `--` (`--message=--deploy failed`). Such a
+ *  value is kept out of argv, where it would read as a flag (`--message=--clear` must not
+ *  clear), and flag() answers it from `inline`. */
+const INLINE_TEXT_FLAGS = new Set(["message"]);
 function expandInlineValues(argv) {
   const out = [];
+  const inline = new Map();
   let problem;
   for (const a of argv) {
     const eq = a.indexOf("=");
     if (!a.startsWith("--") || eq <= 2) { out.push(a); continue; }
     const name = a.slice(2, eq), value = a.slice(eq + 1);
+    if (INLINE_TEXT_FLAGS.has(name) && value.startsWith("--")) { inline.set(name, value); out.push(`--${name}`); continue; }
     problem ??= KERNEL_SWITCHES.has(name) ? `--${name} takes no value (got ${a})` : value === "" ? `--${name}= needs a value` : value.startsWith("--") ? `--${name}= takes a value, not an option (got ${a})` : undefined;
     out.push(`--${name}`, value);
   }
-  return { argv: out, problem };
+  return { argv: out, problem, inline };
 }
-const { argv: args, problem: argvProblem } = expandInlineValues(rawArgs);
+const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
 let cmd = args[0];
 const HELP_WORDS = new Set(["help", "--help", "-h"]);
 const KERNEL_COMMANDS = new Set(["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"]);
@@ -85,6 +91,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental"]
 const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
 const flag = (name) => {
   const i = args.indexOf(`--${name}`);
+  if (i >= 0 && inlineValues.has(name)) return inlineValues.get(name);
   return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
 };
 function yoloFlag() {
@@ -601,12 +608,13 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
   const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
   const agentsRoot = join(dirname(ws.local.path), "agents");
   const localTeams = doctorLocalTeams(ws.local.value);
-  const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...localTeams.problems].filter(Boolean);
+  const schedules = unresolvedScheduleAttempts(dirname(ws.local.path));
+  const problems = [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot), ...localTeams.problems, ...schedules.problems].filter(Boolean);
   return {
     schemaVersion: 1, workspaceApi: 2, context: ctx,
     workspace: { file: ws.local.path, ref: ws.local.workspace },
     workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
-    information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information],
+    information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information],
     composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
     ...(problems.length ? { problems } : {}),
   };
@@ -644,7 +652,9 @@ async function doctor(dir) {
   const localTeams = doctorLocalTeams(ws.local.value);
   for (const p of [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean)) console.log(`\n! ${p.code}: ${p.message}`);
   for (const p of localTeams.problems) console.log(`\n! ${p.code} (${p.condition}): ${p.message}`);
-  for (const line of localTeams.information) console.log(`\nINFO: ${line}`);
+  const schedules = unresolvedScheduleAttempts(dirname(ws.local.path));
+  for (const p of schedules.problems) console.log(`\n! ${p.code}: ${p.message}`);
+  for (const line of [...localTeams.information, ...schedules.information]) console.log(`\nINFO: ${line}`);
   if (soulName) {
     const information = operationalKnowledgeNote(composition, soulName);
     if (information) console.log(`\nINFO: ${information}`);
@@ -913,6 +923,60 @@ async function launchConfigCmd() {
 }
 
 
+/** `oats instance waiting <set|clear>` and `oats instance attention` (feature
+ *  waiting-on-you): a producer's claim that an instance is blocked on a human,
+ *  recorded as a `waiting` event only when the producer's live claim changes
+ *  (lib/instance-events.mjs setWaiting). `waiting` addresses a home like
+ *  `instance events` (--home, else $OATS_INSTANCE_HOME, else the home enclosing
+ *  the cwd; it must be a home of its name under the scope); `attention` is the
+ *  agent's own sugar for `waiting --producer agent --reason attention` and acts
+ *  only on $OATS_INSTANCE_HOME. Local only (no --server route). A claim is
+ *  display-only evidence: nothing in the kernel acts on it. */
+function instanceWaitingCmd(sub, bail) {
+  dropAmbientRoot();
+  const usage = sub === "attention"
+    ? "usage: oats instance attention [--message <text>] [--clear] [--json]"
+    : "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--dir <d>] [--json]";
+  const value = (name) => { const v = flag(name); if (v === true) throw Object.assign(new Error(`--${name} needs a value${name === "message" ? " (a message that starts with -- goes as --message=<text>)" : ""}`), { code: "E_BAD_ARGS" }); return v; };
+  let home, producer, waiting, reason, message;
+  try {
+    message = value("message");
+    if (sub === "attention") {
+      if (args[2] && !args[2].startsWith("--")) return bail("E_BAD_ARGS", usage);
+      for (const f of ["home", "dir", "producer", "reason"]) if (args.includes(`--${f}`)) return bail("E_BAD_ARGS", `oats instance attention has no --${f}: it records the agent's own claim on the instance it runs in ($OATS_INSTANCE_HOME); ${usage}`);
+      home = process.env.OATS_INSTANCE_HOME;
+      if (!home || !isAbsolute(home) || incarnationOf(home) === null) return bail("E_USAGE", `oats instance attention runs inside an instance session: $OATS_INSTANCE_HOME is ${home ? `${home}, which is not an instance home (no readable instance.json)` : "unset"}`);
+      producer = "agent"; waiting = !args.includes("--clear");
+      if (waiting) reason = "attention";
+    } else {
+      const verb = args[2];
+      if (!["set", "clear"].includes(verb)) return bail("E_BAD_ARGS", usage);
+      waiting = verb === "set";
+      producer = value("producer"); reason = value("reason");
+      if (producer === undefined) return bail("E_BAD_ARGS", `--producer is required; ${usage}`);
+      // Producer `agent` is the agent's own claim: only `attention` writes it.
+      if (producer === "agent") return bail("E_BAD_ARGS", "--producer agent is reserved for the agent's own claim: use `oats instance attention [--message <text>]` or `oats instance attention --clear` from its session");
+      const homeOpt = flag("home");
+      if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
+      home = homeOpt ?? (process.env.OATS_INSTANCE_HOME || enclosingInstanceHome(logicalCwd()));
+      if (!home) return bail("E_BAD_ARGS", `no instance home: pass --home <abs>, or run it inside an instance; ${usage}`);
+      if (!isAbsolute(home)) return bail("E_BAD_ARGS", `$OATS_INSTANCE_HOME must be an absolute instance home (${home})`);
+    }
+    if (sub === "attention" && !waiting && message !== undefined) return bail("E_BAD_ARGS", "--message is for setting attention, not --clear");
+    if (incarnationOf(home) === null) return bail("E_SESSION_UNKNOWN", `${home} is not an instance home (no readable instance.json)`);
+    // The home must be a home of its own name under the scope: --dir when
+    // given, else the agents root the home sits in.
+    const root = flag("dir") !== undefined ? ensureRoot(dirFlag()) : agentsRootOfHome(home);
+    const { resolveInstance } = await_import_lifecycle();
+    try { resolveInstance(dirFlag(), root, basename(home), { home }); }
+    catch (e) { if (sub === "attention") return bail("E_USAGE", `$OATS_INSTANCE_HOME (${home}) is not an instance home under ${root}: ${e.message}`); throw e; }
+    const r = setWaiting(home, { producer, waiting, ...(reason !== undefined ? { reason } : {}), ...(message !== undefined ? { message } : {}) });
+    if (JSON_MODE) { jsonOk(r); return; }
+    const w = r.waitingOnYou;
+    console.log(`${r.instance}: ${r.changed ? "recorded" : "unchanged"} — ${r.producer} ${w ? `needs input (${w.reason})${w.message ? `: ${w.message}` : ""}` : "not waiting"}`);
+  } catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
+}
+
 /** `oats instance <git|diff> <instance>` — K1: read-only Git observation of one
  *  instance's work tree. The instance is addressed qualified: an explicit
  *  --home, or a name under the --dir scope (team roots included) that resolves
@@ -920,7 +984,8 @@ async function launchConfigCmd() {
 function instanceCmd() {
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
   const sub = args[1], name = args[2];
-  const usage = "usage: oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json]";
+  if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
+  const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message <text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json]";
   if (!["git", "diff", "stop", "events"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
   dropAmbientRoot();
   if (sub === "events") {
@@ -2040,6 +2105,9 @@ async function status() {
     if (a.description) console.log(`      ${a.description}`);
     for (const i of a.instances) {
       console.log(`      • ${i.instance}  ${i.retirePending ? "RETIRING" : livenessWord(i)}  (branch ${i.branch || "?"}, ${i.work || "?"})${i.runtimeError ? `  ${i.runtimeError}` : ""}`);
+      // Feature waiting-on-you: non-null only on a running row; the reader has
+      // already validated the message (one line, no control characters).
+      if (i.running === true && i.waitingOnYou) console.log(`          ! needs input (${i.waitingOnYou.reason ?? "unknown"})${i.waitingOnYou.message ? `: ${i.waitingOnYou.message}` : ""}`);
       const key = i.home ?? `${a.name}/${i.instance}`;
       if (i.identity) console.log(`          identity: ${servedIdentityLine(i.identity)}`);
       // The kernel the home's plain `oats` runs (its last launch's), when it is not this one.
@@ -2561,12 +2629,27 @@ async function scheduleCmd() {
       }
       case "host": {
         const op = args[2];
-        if (op === "install") { registerWorkspace(ws()); installHostUnit(); return out({ scheduler: schedulerStatus(ws(), io) }); }
+        if (op === "install") {
+          const cap = (name, reset) => {
+            const occurrences = args.filter((arg) => arg === `--${name}`);
+            if (occurrences.length > 1) throw scheduleError("E_BAD_ARGS", `use --${name} <N|${reset}> once`);
+            const value = flag(name);
+            if (value === undefined || value === reset) return value;
+            if (typeof value !== "string" || !/^[0-9]+$/.test(value) || !Number.isSafeInteger(Number(value)) || Number(value) < 1) {
+              throw scheduleError("E_BAD_ARGS", `--${name} requires a positive safe integer or ${reset}`);
+            }
+            return Number(value);
+          };
+          const caps = { maxConcurrent: cap("max-concurrent", "default"), triggersMaxConcurrent: cap("triggers-max-concurrent", "none") };
+          registerWorkspace(ws(), caps);
+          installHostUnit();
+          return out({ scheduler: schedulerStatus(ws(), io) });
+        }
         if (op === "uninstall") { unregisterWorkspace(ws()); if (!readRegistry().workspaces.length) uninstallHostUnit(); return out({ scheduler: schedulerStatus(ws(), io) }); }
         if (op === "status") return out({ scheduler: schedulerStatus(ws(), io) });
         throw scheduleError("E_BAD_ARGS", "oats schedule host install|uninstall|status");
       }
-      default: throw scheduleError("E_BAD_ARGS", "usage: oats schedule list|show <id>|test <id>|add <id> --file <spec.json> [--workspace <member> --runs-on <host> --owner <host>/<login>]|update <id> --file <spec.json>|enable <id>|disable <id>|run <id> [--force]|remove <id> [--force]|reconcile <id> [--clear]|tick [--dry-run] [--host]|host install|uninstall|status [--dir <workspace>|--server <id>] [--json]");
+      default: throw scheduleError("E_BAD_ARGS", "usage: oats schedule list|show <id>|test <id>|add <id> --file <spec.json> [--workspace <member> --runs-on <host> --owner <host>/<login>]|update <id> --file <spec.json>|enable <id>|disable <id>|run <id> [--force]|remove <id> [--force]|reconcile <id> [--clear]|tick [--dry-run] [--host]|host install [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>]|uninstall|status [--dir <workspace>|--server <id>] [--json]");
     }
   } catch (e) {
     // K8b: typed refusal details travel (identity mismatch: key/declared; a refused file: its integrity source).
@@ -3179,7 +3262,7 @@ function versionCmd() {
     // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
     // runs on resolve/materialize (contract §6); a feature the binary does not implement is
     // never listed.
-    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", "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"], 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 }));
+    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"], 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 }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3847,6 +3930,7 @@ Usage:
       tick [--dry-run] [--host]                  command or wake jobs on a five-field cron with an
       host install|uninstall|status              explicit IANA tz; see docs/schedules.md); --server
                                                 routes to that host's workspace
+        install [--max-concurrent N|default] [--triggers-max-concurrent N|none]
   oats trigger add (--file <json> | --from <package>:<template> [--set k=v]) | list | show | enable
       | disable | remove <id> | test <id> | status [<id>]   event-driven spawns (github.pull_request
                                                 polled with the host's gh by the schedule tick;
@@ -3978,6 +4062,12 @@ Usage:
                                              typed lifecycle events (spawned, launched, stopped,
                                              restarted, retired, worktree-retained…) written by
                                              the action that made them true; nothing inferred
+  oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--json]
+                                             a producer's claim that the instance needs input
+                                             from a human; appended only on change; display only
+  oats instance attention [--message <text>] [--clear] [--json]
+                                             run by the agent from its home: "I need a human's
+                                             answer" (waiting --producer agent --reason attention)
   oats instance stop <instance> --plan [--no-recursive] [--json]
                                              what Stop would touch: session state, recorded
                                              children, dirty work; a planRevision to apply

package/docs/capabilities.md

@@ -158,7 +158,10 @@ A self-contained package has an `oats.json`:
   A harness package is **verified at spawn, never installed there**: installing
   would mutate the operator's harness configuration without asking, in the
   middle of a spawn. A missing, uninstalled or disabled package fails the spawn
-  with the consent command that fixes it.
+  with direct package-manager guidance for the operator. The command uses the
+  selected harness executable and resource directory, with Claude marketplace
+  registration before plugin installation. Run it in the indicated context
+  with the same launch environment; spawn and restart never install packages.
 - OATS never installs a host requirement silently. A missing host command is
   the operator's to install; `oats doctor` reports it. Consent to install is
   separate from declaring the package.
@@ -504,6 +507,217 @@ carrying its expert soul. The framework's own souls say
 `oats.okf: { from: package }`: membership never turns a package into a
 latest-state capability.
 
+### oats.core: needs input
+
+oats.core (2.4.0 and later, kernel 0.40.0 and later) tells the deployment
+when an instance is blocked on a human, in two independent ways. Each shows
+on `oats status` and in `oats instance events`. The verbs' contract
+(`oats instance waiting`, `oats instance attention`, the `waiting` event) is
+in [desktop-cli-api.md](desktop-cli-api.md#waiting-on-you). Claims are
+display-only: nothing in the kernel acts on them.
+
+**The agent's own claim.** The oats.core inject and `/oats-operate` teach
+every instance this protocol. When it has asked a human something and cannot
+continue without the answer, it runs
+`oats instance attention --message "<one line>"` from its home and ends its
+turn. Once it has the answer, it runs `oats instance attention --clear`. The
+claim belongs to producer `agent`. Only `--clear` or the next session start,
+restart or stop clears it. The message is one line of at most 200
+characters; control characters, the Unicode line and paragraph separators,
+bidi controls (U+202A–202E, U+2066–2069), U+200B, U+2060, U+FEFF and tag
+characters (U+E0000–E007F) are refused, and everything else (emoji ZWJ
+sequences, ZWNJ, LRM, RLM, ALM) is allowed.
+
+**The Claude Code emitter.** For a Claude instance, oats.core's spawn and
+launch hooks (`bin/oats-core.mjs`, preview-aware) write Claude Code hooks
+into the home's project settings, `<home>/.claude/settings.json`. Each one
+runs `bin/claude-waiting.sh` from the home's module copy, which calls
+`oats instance waiting set|clear --producer oats.core`:
+
+| Claude Code event | Matcher | Action |
+| --- | --- | --- |
+| `Notification` | `permission_prompt` | set `permission` |
+| `Notification` | `elicitation_dialog` | set `question` |
+| `PreToolUse` | `AskUserQuestion` | set `question` |
+| `PreToolUse` | `^(?!AskUserQuestion$).*` (every other tool) | clear, unless a subagent made the call |
+| `PostToolUse` | `*` | clear, unless a subagent made the call |
+| `PostToolUseFailure` | `*` | clear, unless a subagent made the call |
+| `UserPromptSubmit`, `Stop`, `SessionEnd` | none | clear, not debounced (a turn boundary) |
+
+Claude Code shows an AskUserQuestion through its permission dialog, so that
+dialog's own `permission_prompt` follows the question's set: the script keeps
+the current reason in its marker, and a permission prompt never relabels an
+open question. A granted tool that fails fires `PostToolUseFailure`, not
+`PostToolUse`, so that clears too.
+
+**Subagents' tool calls do not clear.** Background and parallel subagents
+in the same session fire the same tool hooks, so the main thread's prompt
+could be cleared while the human is still on it. On Claude Code 2.1.288 a
+subagent's tool event carries a top-level `agent_id` (main-thread events
+have none), so a tool clear reads the hook's JSON input and skips the clear
+when it finds one. The read happens only when there is a claim to clear,
+takes at most 64 KiB and 1 s, and looks only at the text before
+the first `"hook_event_name"`: a string value escapes its quotes, so that
+text holds top-level keys only. Anything else (no key, an input cut short,
+another key order, nothing read) means the main thread, and the clear goes
+ahead. A permission `Notification` carries no `agent_id` and no tool id,
+even when a subagent asked, so a claim never knows who set it.
+
+**A refused permission prompt is not observable.** On Claude Code 2.1.288,
+answering "No" at a permission prompt interrupts the turn and fires no hook
+(no `PostToolUse`, `PostToolUseFailure`, `PostToolBatch` or `Stop`; probed).
+Claude then waits for the human ("What should Claude do instead?"), and the
+claim stays, still labelled `permission`, until the human's next prompt
+clears it.
+
+- **Its own entries only.** oats.core marks its entries by the absolute
+  path of its `claude-waiting.sh`. Each run removes only the entries that
+  name that path (and any matcher group or event array the removal
+  empties), then appends its current ones. Every other key and entry stays
+  as it was, in order. The file is written atomically, mode 0600, and only
+  when its content changes. A temp file an interrupted write left behind
+  (`.claude/.settings.json.oats-core-<pid>-<ms>.tmp`) is removed by the next
+  spawn or start once its writer is gone, so it needs no retirement
+  exclusion. If the file is a symlink, not a regular file,
+  not valid JSON, or not a JSON object with a well-formed `hooks` map,
+  oats.core leaves it alone and warns. The same applies when `.claude` is a
+  symlink or not a directory.
+- **When it writes.** It writes at spawn, because `oats spawn` runs no
+  launch hook, and at every `oats session start|restart`, so the node and
+  CLI paths it bakes in follow the current kernel. A launch preview writes
+  nothing. Every pass answers `{}`: no launch arguments and no env. Codex
+  and pi homes get nothing.
+- **It never hurts the session.** Claude Code reads a hook's stdout and exit
+  code as decisions. So every command runs the script through `/bin/sh`
+  with stdout and stderr on `/dev/null` and ends in `; exit 0`, under a 5 s
+  Claude hook timeout. Stdin, Claude's JSON input, reaches the script, which
+  moves it to a private descriptor and detaches its own stdin, stdout and
+  stderr first. It reads the input only for a tool clear, bounded as above,
+  always exits 0, and kills the CLI after 2 s: with no call starting 2 s
+  after the hook began, the worst case is about 4 s, well under Claude's 5 s
+  hook timeout.
+- **Debounce.** The script keeps private state outside the home, in a file
+  per home: `<dir>/<first 16 hex of sha256(home)>.claude`, where `<dir>`
+  is per user: `$XDG_RUNTIME_DIR/oats-waiting` when that is set and
+  absolute, else `$TMPDIR/oats-waiting-<uid>` when `TMPDIR` is absolute,
+  else `/tmp/oats-waiting-<uid>`. The spawn and launch
+  hook computes that path and vets the directory once: it creates it 0700
+  and uses it only when it is a real directory the user owns, mode exactly
+  0700, with no ACL (also one macOS shows only as `@`). An existing directory
+  is never changed. The hook passes the marker path to every command (or
+  `''` when the directory is refused), so the script, which runs on every
+  tool call, needs no `ls` or hash: it only re-checks that the directory is
+  still a real directory the user owns (only the user could have changed its
+  mode since). The marker holds the latest intent (`permission`, `question`
+  or `clear`), `<marker>.applied` what the CLI last recorded, and
+  `<marker>.lock` is the reconciler's lock. A tool clear when both say clear
+  (and no forced call is due) does nothing and starts no node process, so
+  the hooks that fire on every tool call cost a `/bin/sh` and a few file
+  reads. The turn-boundary clears (`UserPromptSubmit`, `Stop`,
+  `SessionEnd`) are not debounced: each gets a CLI call (see Order and
+  retry), a node process per prompt and per stop. A symlink is never followed. An
+  unusable marker (a refused, missing or replaced directory, a state path
+  that is not a regular file, a lock path that is not a directory) means no
+  debounce: set and clear then always call the (idempotent) CLI. The launch
+  hook resets the state at every spawn and start, as the kernel's session
+  boundary voids the claims. The script runs the CLI from the home, so its
+  cwd never matters.
+- **Order and retry.** Each event writes its intent to the marker at once,
+  so the marker is always the latest intent. Then, if the lock is free, it
+  reconciles: one process at a time brings the recorded claim to the latest
+  intent, re-reading it after each CLI call (at most 3), so the calls land
+  in the order the events came, whatever their speed. Before each call it
+  records the claim as `unknown`, and records the intent only once the call
+  succeeds: a call that fails or is killed may still have written the claim
+  (the kernel writes the home log before the workspace log), so the next
+  event always calls the CLI after one. An event that finds the lock held
+  never waits: it exits, and the holder applies its intent on its next
+  read, or on the read it makes after letting the lock go. The lock is a
+  directory holding its holder's token (pid and start time); one whose
+  holder is gone (pid dead, or taken over 5 s ago, past Claude's hook
+  timeout, which also covers a reused pid and a machine that slept) is
+  broken by the next event, as is one a minute old with no pid yet.
+  Reapers take turns under a second lock, `<marker>.lock.reap`, and judge
+  the lock again there, so a stale judgement never removes the lock another
+  reaper has just taken; a reap lock a minute old (a reaper killed in its
+  instant) is removed. A holder records a call and lets the lock go only
+  while the lock still holds its token. A failed call, or a reconciliation
+  the time budget stops (no call starts 2 s after the hook began), leaves
+  the recorded claim and the intent apart, and the next event finishes it.
+  A turn-boundary clear writes `<marker>.force` beside its intent; the call
+  that next applies the intent consumes it. A turn-boundary clear gets a CLI
+  call: from that hook, or, if another hook holds the lock, from that holder
+  if it still has time; otherwise from the next event. The state files are
+  only ever deleted by the launch hook.
+- **It never touches the agent's claim.** The script only ever passes
+  `--producer oats.core`.
+- **Not "unknown work" at retirement.** Harness project settings in the home
+  are configuration, not work: the retirement fingerprint of a home ignores
+  exactly `.claude/settings.json`. oats.core writes it at spawn before the
+  retirement baseline is taken, and again at every start.
+
+**Why the project settings file, not `--settings`.** On Claude Code
+2.1.288, Claude honours only the last `--settings` flag on a command line:
+that file replaces earlier ones wholesale, even one with no hooks. The
+project `.claude/settings.json` composes with the user's settings (under any
+`CLAUDE_CONFIG_DIR`) and with a `--settings`. So any capability that needs
+Claude settings uses the same managed `<home>/.claude/settings.json` with
+its own marker, never `--settings`. oats.core leaves
+`.claude/settings.local.json` to Claude Code, which writes its "don't ask
+again" permission rules there.
+
+**Limits.**
+
+- If the user's Claude configuration sets `disableAllHooks` or
+  `allowManagedHooksOnly`, the emitter's hooks never run, so there is no
+  claim: the waiting state reads null, not "not waiting".
+- The kernel's write is not fenced against an obsolete writer
+  ([#568](https://github.com/awebai/oats/issues/568)), so two rare paths can
+  leave the claim wrong while the emitter's state says it is right; the next
+  tool clear then skips it. (1) A hook suspended past 5 s mid-call (the
+  machine slept, the process was stopped) has its lock broken, and its call
+  can land after its successor's. (2) A reaper killed at a precise instant
+  can leave a reap lock that two later hooks remove at once, letting two
+  reconcilers run. Either can show a claim when nothing waits, or hide a
+  question. A turn-boundary clear gets a CLI call: from that hook, or, if
+  another hook holds the lock, from that holder if it still has time;
+  otherwise from the next event. So a wrongly shown claim lasts until the
+  end of the turn, or, if the turn's last hook found a reconciliation out
+  of time, until the next event (the human's next prompt). A hidden
+  question lasts until the human answers it (their prompt or the answer's
+  tool event clears it).
+- **A permission prompt can stay hidden until it is answered**, with no
+  suspension or crash: when the prompt opens while another hook's
+  reconciliation is under way and that hook then runs out of time (a slow
+  clear on a loaded machine: the turn's forced `Stop` clear, or a
+  `PostToolUse` clear while a background subagent's prompt opens), the
+  prompt's hook has already exited, leaving its intent to the holder, and
+  the holder stops without applying it. The next event applies it, and
+  while the prompt is open that is usually the answer itself.
+- Parallel tool calls in the main thread **may** clear a claim early: if one
+  waits at a permission prompt while a parallel one finishes after the
+  prompt's notification, that one's `PostToolUse` is a main-thread clear.
+  The notification carries no tool id, so there is no cheap fix. Not
+  observed on Claude Code 2.1.288: a parallel `Read` and a backgrounded
+  `Agent` call each finished before the notification (which came several
+  seconds after the dialog appeared), and the claim stayed.
+- If the marker and the claim disagree (someone deleted the marker by hand,
+  say), a stale claim can remain until the turn ends, or the next set or
+  clear or session boundary.
+- When a subagent asks for permission and the human approves, the
+  subagent's own tool events are skipped too, so the claim stays until the
+  next main-thread event: the main thread's next tool call, the subagent's
+  completion (Claude submits it as a `<task-notification>` prompt), a
+  `Stop` or the human's prompt. A foreground subagent holds the main thread
+  until it finishes, so after its prompt is approved the claim can last the
+  whole subagent run. That shows "needs input" too long, never hides a real
+  block.
+- A `Stop` or `UserPromptSubmit` always clears, even one the main thread
+  produces while a subagent's prompt is open (a background subagent's
+  completion is submitted as a prompt).
+- A Claude instance spawned before the upgrade gets the emitter only when
+  it is respawned. Its launch hook comes from its recorded module copy.
+
 ## Operations a capability declares
 
 A manifest may declare `operations`: named actions or views that a GUI, a