@awebai/oats 0.39.4 → 0.40.1

package/docs/schedules.md

@@ -38,7 +38,7 @@ The design is in the
 | `<deployment>/oats-schedules.json` | This machine's local definitions, `{version: 1, jobs: {<id>: …}}`, local triggers included (`kind: "trigger"`). |
 | `<deployment>/.agents/automations/snapshot.json` | The workspace definitions discovered from the members. |
 | `<deployment>/.agents/schedules/` | Run state: `state.json` (last minute and recent runs per job), `triggers.json` (polls, pending events, fired keys) and one lock directory per running job. |
-| `~/.oats/schedules/registry.json` | The deployments this host ticks, `maxConcurrent` (default 1: running scheduled jobs) and `triggersMaxConcurrent` (absent: no host cap on trigger-spawned live instances). The two caps are separate. |
+| `~/.oats/schedules/registry.json` | The deployments this host ticks, `maxConcurrent` (absent: default 5 running scheduled jobs) and `triggersMaxConcurrent` (absent: no host cap on trigger-spawned live instances). The two caps are separate. |
 
 One host lock serializes ticks, run-now, reconcile and remove. It is never
 reclaimed by another process: a lock whose owner is gone is reported with the
@@ -48,7 +48,18 @@ directory to remove.
 
 Every definition carries `id`, `enabled`, `cron`, `tz` and `kind`. `cron` has
 five fields (minute hour day month weekday) and `tz` is a required IANA zone;
-both are evaluated by the croner library.
+both are evaluated by the croner library. Schedule IDs use lowercase letters,
+digits and dashes, from 1 to 100 characters. Spawn schedules with a long ID
+need an explicit shorter `purpose` to fit the instance-name limit below.
+
+Any kind may carry `description`: what the job is for, in words, for the
+people reading `oats schedule list`, `show` and the Desktop. It is one line of
+1 to 200 characters with no control characters (no CR, LF, TAB or any other
+C0 or C1 character, nor a Unicode line or paragraph separator); anything else
+is `E_SCHEDULE_INVALID` with `field: "description"`. It is stored as given and
+is informational only: it never reaches a run's argv, environment, task or
+reconcile. A capability that registers jobs (knowledge harvest's `run-source`
+jobs) sets it so that its command jobs can be told apart.
 
 - **spawn** `{…, agent, agentsRoot?, repo?, backend?, purpose?, task,
   launchConfig?, harness?, model?, yolo?, wake?}` — every due minute launches
@@ -70,7 +81,13 @@ both are evaluated by the croner library.
   no shell; `oats schedule` itself is refused) in `cwd`, an existing directory
   inside the deployment. The runner tracks any instance the command's
   envelope names, including an independent worker it reports, until its home
-  is gone. A command's return is not task completion.
+  is gone. A command's return is not task completion. Command/operation runs and
+  workspace-spawn launches have a five-minute child timeout. The supervisor
+  sends SIGTERM to the child's process group, allows two seconds for cleanup,
+  then sends SIGKILL if the group remains. It observes the direct child's exit
+  before returning; inherited output pipes cannot hold the tick indefinitely.
+  A timeout leaves effects unconfirmed even if the child printed an envelope.
+  Spawn previews use the same bounded runner.
 - **wake** `{…, home, message}` — every due minute inspects the instance at
   `home`. Running: `message` is delivered once as terminal input (bracketed
   paste plus Enter), never an interrupt. Not running: the home is started with
@@ -220,7 +237,8 @@ owner: github.com/ana
   is an `E_AUTOMATION_SCHEMA` problem, never silently skipped.
 - **The id** is `id:`, else the filename stem. The same id twice in one member
   for one kind is `E_AUTOMATION_DUPLICATE`, naming both paths; the second file
-  is not listed. A trigger and a schedule may share an id. A member named
+  is not listed. Schedule IDs allow 1 to 100 lowercase letters, digits and dashes; trigger
+  IDs allow 1 to 40. A trigger and a schedule may share an id. A member named
   `local` is refused, because `local/<id>` names this host's own definitions.
 - **A workspace schedule is `run: spawn` or `run: command`.** A command's
   `cwd` is relative to the deployment and must stay inside it. `wake` and
@@ -288,6 +306,8 @@ oats schedule test <id>           # dry run: where it runs, whether its soul res
 oats schedule tick [--dry-run]    # evaluate this deployment now; --dry-run launches nothing
 oats schedule reconcile <id> [--clear]   # resolve an attempt whose result was never recorded
 oats schedule host install        # register this deployment and install the one host timer (idempotent)
+oats schedule host install --max-concurrent 3 --triggers-max-concurrent 2
+oats schedule host install --max-concurrent default --triggers-max-concurrent none
 oats schedule host status | uninstall
 oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?"   # or --wake-file spec.json
 ```
@@ -295,7 +315,26 @@ oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?"   # or --w
 `<id>` is `local/<id>` (or the bare id) or `<member>/<id>`. `host uninstall`
 unregisters the deployment and removes the timer once none is registered.
 Every `oats schedule` subcommand takes `--server <id>` instead of `--dir` to
-run on that registered server.
+run on that registered server. Setting or resetting host caps remotely requires
+the destination to advertise both `schedule` and `schedule-host-caps`; an older
+or unknown peer is refused with `E_REMOTE_INCOMPATIBLE` before host install is
+forwarded. Upgrade OATS on the destination to use these options. A remote
+install without cap options retains its existing behavior.
+
+The host allows five running scheduled jobs by default. Use `host install
+--max-concurrent N` to choose a positive integer, or `--max-concurrent default`
+to restore the default. `--triggers-max-concurrent N` independently limits live
+trigger-spawned instances; `none` removes that cap. Omitted flags preserve the
+current choices. Invalid values fail with `E_BAD_ARGS` before registration or
+timer changes. `host status` reports the effective `maxConcurrent` and
+`triggersMaxConcurrent` (`null` when uncapped).
+
+The registry stores explicit choices only. On the first registry read after
+upgrade, a legacy stored `maxConcurrent: 1` without the new choice marker is
+migrated to the default under the registry lock; other explicit values survive.
+If you need a cap of one, run `oats schedule host install --max-concurrent 1`
+after upgrading. That explicit choice survives later reads and reinstalls.
+Set these values through the CLI; do not edit the registry by hand.
 
 `oats schedule list --json` answers:
 
@@ -306,14 +345,14 @@ run on that registered server.
   schedules: [ <row> ],
   triggers: { count, command: "oats trigger list" },
   snapshot: { takenAt, problems } | null,
-  scheduler: { installed, active, unit?, lastTick, maxConcurrent, tickIntervalSec,
+  scheduler: { installed, active, unit?, lastTick, maxConcurrent, triggersMaxConcurrent, tickIntervalSec,
                workspace, registered, workspaces, live } }
 ```
 
 Each row is the stored definition plus `id` (bare for a local schedule,
-`<member>/<id>` for a workspace one), `qualifiedId`, `origin`, `owner`,
-`runsOn`, `runsHere`, `reason`, `enabledHere`, `soul`, `nextDue`, `lastRun`,
-`recentRuns` and `running`; an unreadable row carries `unreadable: { code,
+`<member>/<id>` for a workspace one), `qualifiedId`, `description` (`null`
+when there is none), `origin`, `owner`, `runsOn`, `runsHere`, `reason`,
+`enabledHere`, `soul`, `nextDue`, `lastRun`, `recentRuns` and `running`; an unreadable row carries `unreadable: { code,
 message }` instead of failing the list. `scheduler.active` is what the OS
 reports about the timer. `oats trigger list --json` carries the same
 `scheduler`. The field-level contract is in
@@ -328,12 +367,42 @@ you), `launch-failed`, `unknown`, and for wake jobs `delivered`, `started` or
 `skipped`. The kernel never claims a task succeeded.
 
 `unknown` means the launch's side effects are unconfirmed: a command timed out
-or answered no envelope, or an attempt was never recorded. The job keeps its
-slot and is skipped until `oats schedule reconcile <id>`, which adopts only an
-attributable receipt (a spawn job's instance, named for its minute, or the
-instance a command's answer named). When nothing is attributable, check the
-roster and the host by hand, then `reconcile <id> --clear` records
-`launch-failed` and frees the slot.
+or answered no envelope, or an attempt was never recorded. The job is skipped
+until `oats schedule reconcile <id>`, which adopts only an attributable
+receipt (a spawn job's instance, named for its minute, or the instance a
+command's answer named). When nothing is attributable, check the roster and
+the host by hand, then `reconcile <id> --clear` records `launch-failed` and
+frees the slot. The unresolved attempt shows in `show` as `attempt:
+{scheduledFor, startedAt, error?, exited?, exitStatus?, exitSignal?}`;
+`error` is the first run's cause, which later skipped ticks keep in `lastRun`.
+
+`oats doctor` warns about each unresolved attempt, in this deployment and in
+the other deployments this host ticks (they share its slots). The text form
+is `! schedule-unresolved: …`; in `--json` it is a `problems[]` item:
+
+```text
+{ code: "schedule-unresolved", severity: "warning", scope, id, kind,
+  scheduledFor, startedAt, ageSeconds, holdsSlot, exited, error, remedy, message }
+```
+
+`holdsSlot` says whether the job counts against `maxConcurrent`. `remedy` is
+`oats schedule reconcile <id>`, with `--clear` for a command or operation
+whose effects no named home proves (check the roster and the host by hand
+first), and with `--dir <scope>` for another deployment. A warning never
+changes doctor's exit status. Workspace command kinds come from the last
+saved automations snapshot, without a refresh or an account lookup. Unresolved
+workspace state is reported even if its definition is no longer available.
+
+Whether an `unknown` job keeps its host slot depends on what is still running:
+
+- A `command` or `operation` job whose process exit the kernel observed (it
+  returned, or was stopped at the five-minute timeout) holds no slot: the
+  process runs nothing any more, and an instance it spawned has its own
+  lifecycle. Its attempt shows `exited: true` with the exit status or
+  signal, and other jobs keep running.
+- A `spawn` job keeps its slot, which stands for the instance it may have
+  launched. So does a command whose exit was not observed (the runner threw,
+  the process never started) and a legacy attempt without exit evidence (no `exited`), until reconcile.
 
 **Slots.** A wake job that starts a stopped home holds a launch slot until the
 harness is proven stopped or the home is gone; delivering to a running home
@@ -344,7 +413,7 @@ continues.
 
 **Changing a job.** `disable` never stops anything. `update` never touches a
 running instance, and while a job holds a slot or has an unresolved attempt
-only `cron`, `tz` and `enabled` can change. `remove` refuses while the job's
+only `cron`, `tz`, `enabled` and `description` can change. `remove` refuses while the job's
 instance is tracked or its effects are unresolved (`--force` forgets the job
 without stopping anything). Retiring an instance removes the wake jobs bound
 to its home.

package/docs/workspaces.md

@@ -54,7 +54,7 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
   - git:github.com/acme/tools              # a member that ALSO publishes a package (see below)
 
 packages:                                  # the ONLY versioned things
-  oats.framework: v1.5.0                   # bare version → resolves through the official catalog
+  oats.framework: v1.6.0                   # bare version → resolves through the official catalog
   oats.okf: v4.1.1
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 

package/lib/automations.mjs

@@ -45,6 +45,8 @@ export const PLACEMENT_REASONS = Object.freeze(["host-unnamed", "assigned-elsewh
 export const KIND_NAMES = Object.freeze(["trigger", "schedule"]);
 const NEVER_SCANNED = new Set(["oats-package", ".git", "node_modules"]);
 export const AUTOMATION_ID_RE = /^[a-z0-9-]{1,40}$/;
+/** Schedule definition names have a wider bound than trigger names. */
+export const SCHEDULE_NAME_RE = /^[a-z0-9-]{1,100}$/;
 /** A model id an automation may pass to `oats spawn --model`: a provider/model id, never an option.
  *  The first character is alphanumeric (or the spawn CLI's own `@native-default`), so no value can
  *  be read as a flag (re-review B #1). `[` `]` admit a harness's context-size alias (`opus[1m]`). */
@@ -106,7 +108,8 @@ export function parseAutomationFile(desc, { stem, path, bytes, member, repoKey,
   const unknown = Object.keys(doc).filter((k) => !allowed.includes(k));
   if (unknown.length) return problem(`unknown field${unknown.length > 1 ? "s" : ""} ${unknown.join(", ")} (a ${desc.fileKind} carries ${allowed.join(", ")})`, unknown[0]);
   const name = doc.id === undefined ? stem : doc.id;
-  if (typeof name !== "string" || !AUTOMATION_ID_RE.test(name)) return problem(`the id (${doc.id === undefined ? "the filename stem" : "id:"} ${JSON.stringify(name)}) must be lowercase letters, digits and dashes, 1 to 40 characters`, "id");
+  const namePattern = desc.kind === "schedule" ? SCHEDULE_NAME_RE : AUTOMATION_ID_RE;
+  if (typeof name !== "string" || !namePattern.test(name)) return problem(`the id (${doc.id === undefined ? "the filename stem" : "id:"} ${JSON.stringify(name)}) must be lowercase letters, digits and dashes, 1 to ${desc.kind === "schedule" ? 100 : 40} characters`, "id");
   if (typeof doc.runsOn !== "string" || !HOST_NAME_RE.test(doc.runsOn)) return problem("runsOn: the host name that runs it (oats-local.yaml host.name: lowercase letters, digits and dashes)", "runsOn");
   const owner = parseOwner(doc.owner);
   if (!owner) return problem("owner: the GitHub account it acts as, <host>/<login> (e.g. github.com/acme-kb-bot)", "owner");

package/lib/core.mjs

@@ -32,6 +32,7 @@ import {
   chmodSync, closeSync, copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, readlinkSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, symlinkSync, writeFileSync,
 } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { homedir } from "node:os";
 import { accessSync, constants as fsConstants } from "node:fs";
 import { recordLocalInput } from "./local-inputs.mjs";
 import { createHash, randomUUID } from "node:crypto";
@@ -40,7 +41,7 @@ import { initializeNativeHistory, prepareNativeStart } from "../packages/record/
 import { noteRuntimeName } from "./deprecation.mjs";
 import { attachSessionTarget } from "./session-viewer.mjs";
 import { inspectSessionTarget, inputSessionTarget } from "./session-input.mjs";
-import { appendEvent } from "./instance-events.mjs";
+import { appendEvent, liveWaiting, recordStartBoundary } from "./instance-events.mjs";
 import { killGroup } from "./process-group.mjs";
 
 import { oatsError, herdrInstanceBusy, herdrInstanceRemoved, herdrSettingRemoved, HERDR_REMOVED } from "./errors.mjs";
@@ -204,7 +205,7 @@ function shIn(cwd, cmdline, timeout = 45000) {
   return execSync(cmdline, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout }).trim();
 }
 function shInTry(cwd, cmdline, timeout) { try { return shIn(cwd, cmdline, timeout); } catch { return undefined; } }
-function shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
+export function shq(s) { return `'${String(s).replace(/'/g, `'\\''`)}'`; }
 export function slug(s) {
   const r = String(s).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   return r || "agent";
@@ -2008,7 +2009,7 @@ export const RELATIONS = ["child", "sibling", "parent", "unrelated"];
 /** Verify the harness packages that ACTIVE capabilities require for `harness`.
  *
  * Each comes from a declared harness-package requirement, so the capability has
- * stated the dependency and the user has consented to install it (`oats install`).
+ * stated the dependency. Installing it remains the operator's responsibility.
  * We verify PRESENCE and record provenance; we deliberately do NOT resolve the
  * extension's entry file. pi owns that resolution — its manifest supports globs
  * and exclusions, packages without a `pi` manifest use conventional directories,
@@ -2050,8 +2051,16 @@ function verifyHarnessPackages(harness, resolved, contextDir, { bin, env } = {})
       const status = harnessPackageStatus(harness, spec, probeEnv, probeOpts);
       const mgr = HARNESS_PACKAGE_MANAGERS[harness];
       const stepList = mgr?.steps ? mgr.steps(spec, raw, probeOpts) : [mgr?.argv(spec, raw, probeOpts) || []];
-      const direct = stepList.filter((a) => a.length).map((a) => a.join(" ")).join(" && ");
-      const remedy = `run \`oats install --accept-requirement ${harness}:${harnessPackageIdentity(harness, spec)} --dir ${contextDir}\`${direct ? ` (or \`${direct}\` directly)` : ""}`;
+      // Keep the remedy in the same resource directory and selected wrapper as
+      // the probe; quote argv, never turn a path or package selector into shell code.
+      // Pi expands ~ against the launch HOME; relative selectors are anchored
+      // to the probe cwd before the remedy changes to contextDir.
+      const piResourceDir = harness === "pi" ? piAgentDir(probeEnv).replace(/^~(?=$|\/)/, () => probeEnv.HOME || homedir()) : undefined;
+      const resourceEnv = harness === "pi" ? `PI_CODING_AGENT_DIR=${shq(resolve(piResourceDir))} `
+        : harness === "claude" && probeEnv.CLAUDE_CONFIG_DIR ? `CLAUDE_CONFIG_DIR=${shq(resolve(probeEnv.CLAUDE_CONFIG_DIR))} ` : "";
+      const direct = stepList.filter((a) => a.length).map((a) => resourceEnv + [bin || a[0], ...a.slice(1)].map(shq).join(" ")).join(" && ");
+      const remedy = direct ? `ask the operator to run \`cd ${shq(contextDir)} && ${direct}\` with the selected harness's environment; OATS does not install packages during spawn or restart`
+        : `ask the operator to install it with the selected harness's package manager`;
       // `ifInstalled: true`: the row constrains a package that may be absent
       // (an ambient extension must honour a contract IF it is there); absence
       // satisfies it. Without the flag, absence fails as before.
@@ -3948,7 +3957,18 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
           ...(meta.home !== undefined && meta.home !== home ? { recordedHome: meta.home } : {}),
           ...(meta.instance !== undefined && meta.instance !== e.name ? { recordedInstance: meta.instance } : {}),
         };
-        return { ...meta, ...claims, home, instance: e.name, ...facts, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
+        // Feature waiting-on-you: a producer's live claim that the instance is
+        // blocked on a human, read only for a running row (one bounded read of
+        // its home log); null otherwise, and null means unknown. `running` is
+        // the window's presence, which a crashed harness's fallback shell or a
+        // retained dead pane keeps: a row with a claim is shown only when its
+        // session is observed running a harness, as session inspect reports it.
+        let waitingOnYou = liveness.running === true ? liveWaiting(home) : null;
+        if (waitingOnYou) {
+          try { const s = instanceSessionTarget(home); if (!s.target || !harnessRunning(inspectSessionTarget(s.target))) waitingOnYou = null; }
+          catch { waitingOnYou = null; }
+        }
+        return { ...meta, ...claims, home, instance: e.name, ...facts, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
 
       });
   };
@@ -4324,6 +4344,12 @@ const GIT_MAX_BUFFER = 512 * 1024 * 1024;
  *  otherwise every stop or event write would read as "changed home bytes". */
 const KERNEL_HOME_RECEIPTS = new Set([".oats-events.jsonl", ".oats-stop.json", ".oats-stop-receipt.json", ".oats-restart.json"]);
 const KERNEL_HOME_RECEIPT_PATTERNS = [/^\.oats-stop-receipt\..+\.json$/, /^\.oats-agents-md\..+\.previous$/];
+/** Harness project settings in the home are configuration, not work: the
+ *  home's `.claude/` is harness layout the kernel already shapes (the skills
+ *  alias), and capabilities keep their own entries current in its
+ *  settings.json at every launch. A retirement fingerprint ignores exactly
+ *  that path, home-relative. */
+const HARNESS_HOME_SETTINGS = new Set([join(".claude", "settings.json")]);
 function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = false, instanceHome = false } = {}) {
   const hash = createHash("sha256");
   const rootStat = lstatSync(root);
@@ -4338,6 +4364,7 @@ function fingerprintTree(root, { excludeRoot = new Set(), excludeGitMetadata = f
     for (const e of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
       if ((!rel && excludeRoot.has(e.name)) || (instanceHome && !rel && (KERNEL_HOME_RECEIPTS.has(e.name) || KERNEL_HOME_RECEIPT_PATTERNS.some((p) => p.test(e.name)))) || (excludeGitMetadata && e.name === ".git")) continue;
       const childRel = rel ? join(rel, e.name) : e.name;
+      if (instanceHome && HARNESS_HOME_SETTINGS.has(childRel)) continue;
       const path = join(dir, e.name);
       const st = lstatSync(path);
       hash.update(childRel); hash.update("\0"); hash.update(String(st.mode & 0o7777)); hash.update("\0");
@@ -4565,12 +4592,18 @@ function instanceSessionTarget(home) {
 }
 
 export function inspectInstanceSession(home) {
-  if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped" };
+  if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped", waitingOnYou: null };
   const s = instanceSessionTarget(home);
-  if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched" };
-  try { return { home: s.home, ...inspectSessionTarget(s.target) }; }
+  if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched", waitingOnYou: null };
+  let observed;
+  try { observed = inspectSessionTarget(s.target); }
   catch (e) { throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${e.message}`); }
+  // Feature waiting-on-you: beside `state`, whose enum is unchanged.
+  return { home: s.home, ...observed, waitingOnYou: harnessRunning(observed) ? liveWaiting(s.home) : null };
 }
+/** Whether an observed session runs a harness: present, and neither a
+ *  fallback shell nor a dead pane. Only such a session can be waiting on a human. */
+function harnessRunning(observed) { return observed?.present === true && observed.state !== "shell" && observed.state !== "stopped"; }
 
 /** K3: quiesce one instance's session and RETAIN everything else — home,
  *  worktree, transcript, launch configuration — so `restart` can bring it back.
@@ -5125,6 +5158,9 @@ export function startInstanceSession(home, o = {}) {
       // Reconcile even an exited target: the independent baseline may
       // already name it while metadata still names the old allocation.
       const meta = readMeta();
+      // The adopted start's session boundary, at its launch time, completed
+      // in whichever log the interrupted start did not record it.
+      recordStartBoundary(realHome, { startId: pending.id, startedAt: pending.startedAt, harness: pending.harness ?? meta.harness ?? null, backend: "tmux", launchConfig: pending.launch?.launchConfig ?? meta.launch?.launchConfig ?? null, phase: "recovered" });
       const done = record(meta, { ...pending, model: pending.model ?? undefined, reused: "adopted" }, !st.present || st.state === "shell");
       if (st.present && st.state !== "shell") {
         if (o.restart) { rmSync(pendingPath, { force: true }); }
@@ -5305,6 +5341,10 @@ export function startInstanceSession(home, o = {}) {
       catch (e) { throw launchFailure(e); }
     }
     target = { backend: "tmux", session, window, socket: resolve(socket) };
+    // The session exists: its boundary (lib/instance-events.mjs) is recorded
+    // now, before the metadata, so a start whose metadata write fails still
+    // voids the claims of the session it replaced; its adoption only completes a log it missed.
+    recordStartBoundary(realHome, { startId: id, startedAt, harness: launchPlan?.harness || harness, backend: "tmux", launchConfig: launchPlan?.recipe?.launchConfig ?? meta.launch?.launchConfig ?? null, phase: o.restart ? "restart" : "start" });
     // Keep launch evidence until the command exits or the target disappears.
     // A transient child (for example the native-start recorder) is not proof that startup
     // has finished. A later start reconciles the receipt without a watcher.

package/lib/instance-events.mjs

@@ -18,7 +18,15 @@
  *    recreated same-address instance's earlier rows are visible as earlier;
  *  - `waitingOnYou` is a producer STATE per (producer, current incarnation):
  *    that producer's latest row carrying the field decides, an explicit `false`
- *    clears, and it is computed over the full admitted read, before windowing. */
+ *    clears, and it is computed over the full admitted read, before windowing;
+ *  - a claim is LIVE only after the incarnation's latest kernel session
+ *    boundary (`launched` | `restarted` | `stopped`): a claim written before
+ *    the boundary belongs to a session that has ended (WAITING_BOUNDARY_KINDS).
+ *
+ * Producers write claims as `waiting` rows through `setWaiting` (the CLI's
+ * `oats instance waiting` and `oats instance attention`): data
+ * `{waitingOnYou, reason?, message?}`, appended only on a change. A claim is
+ * evidence for display, never authority: nothing in the kernel acts on it. */
 import { appendFileSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 
@@ -26,7 +34,33 @@ export const EVENTS_API = 2;
 const HOME_LOG = ".oats-events.jsonl";
 const MAX_BYTES = 4 * 1024 * 1024;
 
-export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "worktree-retained", "worktree-removed", "branch-deleted", "child-spawn-refused", "launch-warning", "recomposed"];
+export const EVENT_KINDS = ["spawned", "launched", "restarted", "stopped", "stop-refused", "retire-planned", "retired", "worktree-retained", "worktree-removed", "branch-deleted", "child-spawn-refused", "launch-warning", "recomposed", "waiting"];
+
+/** Kernel rows that end or begin a session: a waiting claim older than the
+ *  incarnation's latest one is not live. */
+export const WAITING_BOUNDARY_KINDS = ["launched", "restarted", "stopped"];
+/** The closed set of reasons a positive claim carries. */
+export const WAITING_REASONS = ["permission", "question", "attention"];
+/** A producer id: what `--producer` accepts (`kernel` is reserved). */
+export const WAITING_PRODUCER_RE = /^[a-z0-9][a-z0-9._/-]{0,63}$/;
+export const WAITING_MESSAGE_MAX = 200;
+/** Characters a claim's message may not contain (the maintainer's set): control
+ *  characters (Cc: C0, DEL, C1), the Unicode line and paragraph separators, the bidi
+ *  embeddings, overrides and isolates (U+202A-202E, U+2066-2069), the invisible hiders
+ *  U+200B, U+2060 and U+FEFF, and the tag characters (U+E0000-E007F). Everything else is
+ *  allowed, ZWJ and ZWNJ (U+200C/D, emoji sequences, Persian and Indic text) and the marks
+ *  LRM, RLM and ALM (U+200E/F, U+061C) included. The Desktop uses the identical set. */
+const WAITING_MESSAGE_REFUSED = /[\p{Cc}\u2028\u2029\u202A-\u202E\u2066-\u2069\u200B\u2060\uFEFF\u{E0000}-\u{E007F}]/u;
+/** A claim's message: a non-empty string of 1 to 200 code points with none of
+ *  WAITING_MESSAGE_REFUSED. The writer refuses anything else; the reader turns a stored
+ *  message that fails it (a hand-edited log) into null. */
+export function validWaitingMessage(m) {
+  return typeof m === "string" && m.length > 0 && [...m].length <= WAITING_MESSAGE_MAX && !WAITING_MESSAGE_REFUSED.test(m);
+}
+// A reason read back from a log is shown as given only when it is one of the
+// closed set; anything else reads as null, and the claim still counts.
+/** A stored reason outside the closed set (a hand-edited or foreign row) reads as null. */
+const readReason = (r) => (WAITING_REASONS.includes(r) ? r : null);
 
 function workspaceLogPath(home) {
   // <workspace>/.agents/events/<agent>--<instance>.jsonl — deployment-private
@@ -43,9 +77,12 @@ export function incarnationOf(home) {
 
 /** Append one typed event. Never throws into the caller's action: an event is
  *  evidence, not authority — a failed write is reported in the return value. */
-export function appendEvent(home, event, { workspaceOnly = false, incarnation } = {}) {
+export function appendEvent(home, event, { workspaceOnly = false, incarnation, at } = {}) {
   if (!EVENT_KINDS.includes(event.kind)) return { ok: false, reason: `unknown event kind ${event.kind}` };
-  const row = { eventsApi: EVENTS_API, at: new Date().toISOString(), instance: basename(home), home, incarnation: incarnation === undefined ? incarnationOf(home) : incarnation, producer: event.producer || "kernel", kind: event.kind, ...(event.data !== undefined ? { data: event.data } : {}) };
+  // `at`: the time the fact became true, when it is recorded later (a start
+  // boundary reconciled from its receipt); readers order rows by it.
+  if (at !== undefined && (typeof at !== "string" || !Number.isFinite(Date.parse(at)))) return { ok: false, reason: `invalid event time ${at}` };
+  const row = { eventsApi: EVENTS_API, at: at ?? new Date().toISOString(), instance: basename(home), home, incarnation: incarnation === undefined ? incarnationOf(home) : incarnation, producer: event.producer || "kernel", kind: event.kind, ...(event.data !== undefined ? { data: event.data } : {}) };
   const line = JSON.stringify(row) + "\n";
   const results = [];
   // Retirement fingerprints the home against its baseline and preserves any
@@ -96,32 +133,68 @@ function readLog(path, label) {
   return { rows, unreadable, source: { path: label, status: tail ? "tail" : "ok", bytes: st.size } };
 }
 
-/** Events for one instance ADDRESS, newest last, from both logs, with a bounded
- *  window; integrity is reported independently of the selected rows. */
-export function readEvents(home, { limit = 200, since = null } = {}) {
+/** The ADDRESS's rows from the given log reads: foreign rows dropped and
+ *  counted, oldest first. The logs are merged as a multiset union: a row in
+ *  both logs (the same fact, written to each) is kept once, but rows that
+ *  genuinely repeat within one log (a set, a clear and the same set again in
+ *  one millisecond) are all kept, as many times as the log holding the most
+ *  copies has them. */
+function admit(home, reads) {
   const instance = basename(home);
-  const incarnation = incarnationOf(home);
-  const a = readLog(join(home, HOME_LOG), "home"), b = readLog(workspaceLogPath(home), "workspace");
-  const seen = new Set(); const rows = []; let foreign = 0;
-  for (const r of [...a.rows, ...b.rows]) {
-    if (r.instance !== instance || r.home !== home) { foreign++; continue; } // another address's row in this log: history of THIS address only
-    const k = `${r.producer ?? "kernel"}|${r.at}|${r.kind}|${r.incarnation ?? ""}|${JSON.stringify(r.data ?? null)}`; // same facts from two producers are two rows
-    if (seen.has(k)) continue; seen.add(k); rows.push({ ...r, incarnation: r.incarnation ?? null });
+  const admitted = new Map(); const rows = []; let foreign = 0;
+  for (const read of reads) {
+    const inThisLog = new Map();
+    for (const r of read.rows) {
+      if (r.instance !== instance || r.home !== home) { foreign++; continue; } // another address's row in this log: history of THIS address only
+      const k = `${r.producer ?? "kernel"}|${r.at}|${r.kind}|${r.incarnation ?? ""}|${JSON.stringify(r.data ?? null)}`; // same facts from two producers are two rows
+      const n = (inThisLog.get(k) ?? 0) + 1; inThisLog.set(k, n);
+      if (n <= (admitted.get(k) ?? 0)) continue; // this copy is already in from another log
+      admitted.set(k, n); rows.push({ ...r, incarnation: r.incarnation ?? null });
+    }
   }
   rows.sort((x, y) => x.at.localeCompare(y.at));
-  // Waiting: a producer STATE for the CURRENT incarnation, decided by that
-  // producer's latest row that carries the field, over the FULL admitted read.
-  // An UNKNOWN current incarnation (unreadable instance.json) admits NO claim:
-  // unknown stays unknown, it never resurrects an earlier incarnation's positive.
+  return { rows, foreign };
+}
+
+/** Waiting: a producer STATE for the CURRENT incarnation, decided by that
+ *  producer's latest row that carries the field, over the FULL admitted read.
+ *  An UNKNOWN current incarnation (unreadable instance.json) admits NO claim:
+ *  unknown stays unknown, it never resurrects an earlier incarnation's
+ *  positive. A row older than the incarnation's latest kernel session
+ *  boundary belongs to an ended session and is not a claim at all, nor is a
+ *  row whose producer is neither `kernel` nor a valid producer id. */
+function claimsOf(rows, incarnation) {
   const claims = new Map();
-  for (const r of (incarnation === null ? [] : rows)) {
-    if (r.incarnation !== incarnation) continue;
+  if (incarnation === null) return claims;
+  const current = rows.filter((r) => r.incarnation === incarnation);
+  // Positional: rows are time-sorted with a stable sort, so rows of the same
+  // millisecond keep their append order, and a claim appended before the
+  // boundary in that millisecond is still before it.
+  const boundary = current.findLastIndex((r) => (r.producer ?? "kernel") === "kernel" && WAITING_BOUNDARY_KINDS.includes(r.kind));
+  for (const r of current.slice(boundary + 1)) {
     if (!r.data || typeof r.data.waitingOnYou !== "boolean") continue;
     const p = r.producer ?? "kernel";
-    claims.set(p, r.data.waitingOnYou ? { producer: p, waiting: true, since: r.at, reason: typeof r.data.reason === "string" ? r.data.reason : null } : { producer: p, waiting: false, since: r.at, reason: null });
+    // A producer the writer would refuse (a hand-edited log) is never shown as one.
+    if (p !== "kernel" && !(typeof p === "string" && WAITING_PRODUCER_RE.test(p))) continue;
+    claims.set(p, r.data.waitingOnYou
+      ? { producer: p, waiting: true, since: r.at, reason: readReason(r.data.reason), message: validWaitingMessage(r.data.message) ? r.data.message : null }
+      : { producer: p, waiting: false, since: r.at, reason: null, message: null });
   }
+  return claims;
+}
+const positiveOf = (claims) => [...claims.values()].filter((c) => c.waiting).sort((x, y) => x.since.localeCompare(y.since)).at(-1) ?? null;
+const waitingShape = (c) => (c ? { since: c.since, producer: c.producer, reason: c.reason, message: c.message } : null);
+
+/** Events for one instance ADDRESS, newest last, from both logs, with a bounded
+ *  window; integrity is reported independently of the selected rows. */
+export function readEvents(home, { limit = 200, since = null } = {}) {
+  const instance = basename(home);
+  const incarnation = incarnationOf(home);
+  const a = readLog(join(home, HOME_LOG), "home"), b = readLog(workspaceLogPath(home), "workspace");
+  const { rows, foreign } = admit(home, [a, b]);
+  const claims = claimsOf(rows, incarnation);
   const waitingClaims = [...claims.values()];
-  const positive = waitingClaims.filter((c) => c.waiting).sort((x, y) => x.since.localeCompare(y.since)).at(-1) ?? null;
+  const positive = positiveOf(claims);
   const filtered = since ? rows.filter((r) => r.at > since) : rows;
   const window = filtered.slice(-limit);
   const last = window.at(-1) ?? null;
@@ -130,13 +203,95 @@ export function readEvents(home, { limit = 200, since = null } = {}) {
     truncated: filtered.length > window.length || a.source.status === "tail" || b.source.status === "tail",
     integrity: { unreadableRows: a.unreadable + b.unreadable, foreignRows: foreign, sources: [a.source, b.source] },
     events: window, lastEvent: last ? { kind: last.kind, at: last.at, producer: last.producer ?? "kernel", incarnation: last.incarnation } : null,
-    waitingOnYou: positive ? { since: positive.since, producer: positive.producer, reason: positive.reason } : null,
+    waitingOnYou: waitingShape(positive),
     waitingClaims,
     notes: [
       "events are producer-attributed facts written by the kernel action that made them true; nothing is inferred from transcripts or task files",
       "this is the ADDRESS's history: rows tagged with an earlier incarnation belong to a previous instance at this address",
       "waitingOnYou is null unless a producer reported it for the current incarnation — null means unknown, not 'not waiting'; an explicit false clears that producer's claim; an unknown current incarnation (null) admits no claim at all",
+      "a claim older than the incarnation's latest kernel launched, restarted or stopped row belongs to an ended session and is not counted",
       "integrity counts torn and foreign rows and names each source's status; truncated is true when the window cut rows or a source was read as a tail",
     ],
   };
 }
+
+/** The instance's live waiting state, `{since, producer, reason, message}` or
+ *  null: what `oats status` rows and `oats session inspect` carry. The same
+ *  bounded read and the same claim rule as readEvents, over the home log only
+ *  (the workspace log only when the home log is absent): every row a producer
+ *  or a session boundary writes goes to both. */
+export function liveWaiting(home) {
+  const incarnation = incarnationOf(home);
+  if (incarnation === null) return null;
+  let log = readLog(join(home, HOME_LOG), "home");
+  if (log.source.status === "absent") log = readLog(workspaceLogPath(home), "workspace");
+  return waitingShape(positiveOf(claimsOf(admit(home, [log]).rows, incarnation)));
+}
+
+const waitingError = (code, message) => Object.assign(new Error(message), { code });
+
+/** Set or clear one producer's waiting claim on an instance home; appends a
+ *  `waiting` row only when the producer's LIVE claim changes (a positive set
+ *  whose reason or message differs is a change; a clear of a claim that is
+ *  not positive is not). Each log is judged on its own, so a row that reached
+ *  only one log earlier is repaired by the next call rather than hidden by the
+ *  other log; success means both logs took the row. Validates its input
+ *  (E_BAD_ARGS); a home without a readable instance.json is
+ *  E_SESSION_UNKNOWN; a write either log refused is E_EVENTS_FAILED (a retry
+ *  repairs it). Evidence, not authority: nothing else is touched. */
+export function setWaiting(home, { producer, waiting, reason, message } = {}) {
+  if (typeof producer !== "string" || !WAITING_PRODUCER_RE.test(producer)) throw waitingError("E_BAD_ARGS", `--producer must match ${WAITING_PRODUCER_RE.source}`);
+  if (producer === "kernel") throw waitingError("E_BAD_ARGS", "--producer kernel is reserved for the kernel's own events");
+  if (typeof waiting !== "boolean") throw waitingError("E_BAD_ARGS", "waiting must be set or clear");
+  if (waiting) {
+    if (!WAITING_REASONS.includes(reason)) throw waitingError("E_BAD_ARGS", `--reason must be one of ${WAITING_REASONS.join(", ")}`);
+    if (message !== undefined && !validWaitingMessage(message)) throw waitingError("E_BAD_ARGS", `--message must be one line of 1 to ${WAITING_MESSAGE_MAX} characters with no control character, line separator, bidi control (U+202A-202E, U+2066-2069), U+200B, U+2060, U+FEFF or tag character`);
+  } else {
+    if (reason !== undefined) throw waitingError("E_BAD_ARGS", "--reason is for set, not clear");
+    if (message !== undefined) throw waitingError("E_BAD_ARGS", "--message is for set, not clear");
+  }
+  const incarnation = incarnationOf(home);
+  if (incarnation === null) throw waitingError("E_SESSION_UNKNOWN", `${home} is not an instance home (no readable instance.json)`);
+  const live = [readLog(join(home, HOME_LOG), "home"), readLog(workspaceLogPath(home), "workspace")]
+    .map((log) => { const c = claimsOf(admit(home, [log]).rows, incarnation).get(producer); return c?.waiting ? c : null; });
+  const agrees = (c) => (waiting ? !!c && c.reason === reason && c.message === (message ?? null) : !c);
+  const answer = (changed, claim) => ({ eventsApi: EVENTS_API, instance: basename(home), home, producer, changed, waitingOnYou: waitingShape(claim) });
+  if (live.every(agrees)) return answer(false, waiting ? live[0] : null);
+  const data = waiting ? { waitingOnYou: true, reason, ...(message !== undefined ? { message } : {}) } : { waitingOnYou: false };
+  const res = appendEvent(home, { producer, kind: "waiting", data }, { incarnation });
+  const failed = (res.results || []).filter((r) => !r.ok);
+  if (!res.ok || failed.length) throw waitingError("E_EVENTS_FAILED", `could not record the waiting claim in ${failed.map((r) => `${r.path} (${r.reason})`).join(", ") || res.reason}; retry to complete it`);
+  return answer(true, waiting ? { producer, since: res.row.at, reason, message: message ?? null } : null);
+}
+
+/** The kernel session boundary of one start receipt: a `launched` row tagged
+ *  `startId`, dated at the receipt's `startedAt`, written once to each log. A
+ *  start records it as soon as its session exists; recovering an interrupted
+ *  start (its receipt adopted later) completes it: a log that already has the
+ *  row is left alone, a log missing it gets a copy of the same row (same time,
+ *  same data), and only when neither has it is the row made, still at the
+ *  launch time, so a claim the new session made since is kept. `ok` is true
+ *  only when every log holds the row; evidence, never authority. */
+export function recordStartBoundary(home, { startId, startedAt, ...data }) {
+  const paths = [join(home, HOME_LOG), workspaceLogPath(home)];
+  const instance = basename(home);
+  const isIt = (r) => r.instance === instance && r.home === home && (r.producer ?? "kernel") === "kernel" && r.kind === "launched" && r.data?.startId === startId;
+  const found = paths.map((path) => readLog(path, "log").rows.find(isIt) ?? null);
+  if (found.every(Boolean)) return { ok: true, existed: true };
+  const existing = found.find(Boolean);
+  if (!existing) {
+    const res = appendEvent(home, { kind: "launched", data: { ...data, startId } }, { at: startedAt });
+    return { ...res, ok: res.ok && (res.results || []).every((r) => r.ok) };
+  }
+  // The row exactly as the other log holds it: same time, incarnation and data.
+  const line = JSON.stringify(existing) + "\n";
+  const results = paths.filter((_, i) => !found[i]).map((path) => {
+    try {
+      if (path.startsWith(home) && !existsSync(home)) return { path, ok: false, reason: "home absent" };
+      mkdirSync(dirname(path), { recursive: true });
+      appendFileSync(path, line);
+      return { path, ok: true };
+    } catch (e) { return { path, ok: false, reason: e.message }; }
+  });
+  return { ok: results.every((r) => r.ok), repaired: true, row: existing, results };
+}