@awebai/oats 0.42.0 → 0.43.0

package/bin/oats.mjs

@@ -47,13 +47,13 @@ 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, 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 { parseEnvelopeText, unresolvedScheduleAttempts, scheduleScopeOf, listSchedules, describe as describeSchedule, testSchedule, addSchedule, updateSchedule, updateScheduleDescription, 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";
 
 import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
 import { planStop, applyStop, planRetire, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
-import { formatBytes, workRecoveryLines } from "../lib/retire-output.mjs";
+import { extraWorktreeLines, formatBytes, workRecoveryLines } from "../lib/retire-output.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, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
@@ -69,6 +69,9 @@ const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear"
  *  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"]);
+/** Free-text flags whose inline value is always kept whole, the empty one included:
+ *  `--description=` clears a trigger's or schedule's description. */
+const INLINE_WHOLE_FLAGS = new Set(["description"]);
 function expandInlineValues(argv) {
   const out = [];
   const inline = new Map();
@@ -77,7 +80,7 @@ function expandInlineValues(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; }
+    if (INLINE_WHOLE_FLAGS.has(name) || (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);
   }
@@ -105,6 +108,20 @@ function valueFlag(name) {
   if (value === true) cmdFail("E_BAD_ARGS", `--${name} needs a value`);
   return value;
 }
+/** `--description=<text>` on the trigger and schedule verbs: undefined when absent, the text
+ *  otherwise (`""` clears). The spaced form works too, but only `=` carries an empty value or one
+ *  that starts with `--`. */
+function descriptionFlag() {
+  const value = flag("description");
+  if (value === true) throw Object.assign(new Error("--description needs a value: --description=<text> (--description= clears it)"), { code: "E_BAD_ARGS" });
+  return value;
+}
+/** A spec with the --description flag applied: it sets or overrides `description`; `""` removes it. */
+function withDescription(spec, description) {
+  if (description === undefined || !spec || typeof spec !== "object" || Array.isArray(spec)) return spec;
+  const { description: _d, ...rest } = spec; void _d;
+  return description === "" ? rest : { ...rest, description };
+}
 const die = (msg, exit = 1) => { console.error(`oats: ${msg}`); process.exit(exit); };
 /** A command's harness: --harness, or --runtime, its pre-0.27 name (the released okf worker and
  *  a 0.26-era Desktop pass it) — read either, with the deprecation warning. Both, disagreeing,
@@ -1430,9 +1447,11 @@ async function automationsCmd() {
 /** `oats trigger|schedule add --workspace <member> --runs-on <host> --owner <host>/<login>`: the
  *  workspace file, written into the member's checkout when `--dir` (or the cwd) is inside one, else
  *  printed. What is written must read back as the same automation (parseAutomationFile + expand). */
-async function addWorkspaceAutomation(desc, { id, body }) {
+async function addWorkspaceAutomation(desc, { id, body, description }) {
   const bail = (code, msg, details) => { throw Object.assign(new Error(msg), { code, details }); };
-  const member = flag("workspace"), runsOn = flag("runs-on"), owner = flag("owner"), description = flag("description");
+  const member = flag("workspace"), runsOn = flag("runs-on"), owner = flag("owner");
+  // The header's description: refused here when out of the rule (discovery would only warn).
+  if (description !== undefined && description !== "") A.validateDescription(description, desc.kind === "trigger" ? "E_TRIGGER_INVALID" : "E_SCHEDULE_INVALID");
   if (typeof member !== "string" || !member) bail("E_BAD_ARGS", "--workspace needs a member name");
   if (typeof runsOn !== "string" || !A.HOST_NAME_RE.test(runsOn)) bail("E_BAD_ARGS", "--runs-on <host>: the host.name (oats-local.yaml) of the machine that runs it");
   if (!A.parseOwner(owner)) bail("E_BAD_ARGS", "--owner <host>/<login>: the GitHub account it acts as, e.g. github.com/acme-kb-bot");
@@ -1441,7 +1460,7 @@ async function addWorkspaceAutomation(desc, { id, body }) {
   const row = (discovery.members || []).find((m) => m.confirmed && (memberLabel(m.key) === member || m.key === member));
   if (!row) bail("E_AUTOMATION_MEMBER", `${member} is not a confirmed member of this workspace (members: ${(discovery.members || []).filter((m) => m.confirmed).map((m) => memberLabel(m.key)).join(", ") || "none"})`, { member });
   const name = memberLabel(row.key);
-  const content = A.automationFileText(desc, { id, description: typeof description === "string" ? description : undefined, runsOn, owner, body });
+  const content = A.automationFileText(desc, { id, description: description || undefined, runsOn, owner, body });
   const parsed = A.parseAutomationFile(desc, { stem: id, path: `${desc.folder}/${id}.yaml`, bytes: Buffer.from(content), member: name, repoKey: row.key, commit: row.commit });
   if (parsed.problem) bail(parsed.problem.code, parsed.problem.message, { path: parsed.problem.path });
   await desc.expand(parsed.entry);
@@ -2498,7 +2517,7 @@ function retireCmd() {
   const planRev = flag("plan-revision"), idemKey = flag("idempotency-key");
   if (planRev === true || idemKey === true) die("--plan-revision and --idempotency-key need values");
   if ((planRev !== undefined) !== (idemKey !== undefined)) die("--plan-revision and --idempotency-key go together");
-  let replayPath = null, childrenStopped = null;
+  let replayPath = null, childrenStopped = null, plannedExtraWorktrees;
   if (planRev !== undefined) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(idemKey)) die("--idempotency-key: 1-128 chars of [A-Za-z0-9._:-]");
     // Replay first: after a successful retire the home is gone, so the receipt
@@ -2508,6 +2527,9 @@ function retireCmd() {
     let fresh;
     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); }
     replayPath = join(dirname(fresh.home), `.oats-retire-receipt.${idemKey}.json`);
+    // The extra trees the confirmed plan names, as it names them: the retire refuses as stale rather than
+    // move or remove one that no longer reads that way when it gets to them.
+    plannedExtraWorktrees = fresh.facts.extraWorktrees;
     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`);
     // The plan promised: recorded children are STOPPED first (bounded, never
     // escalated) and retained. A child still running after the grace refuses
@@ -2521,7 +2543,7 @@ function retireCmd() {
     if (running.length) return args.includes("--json") ? jsonFail("E_CHILDREN_RUNNING", `${running.map((k) => k.instance).join(", ")} ${running.length === 1 ? "is" : "are"} still running after a bounded stop; nothing was retired and nothing was escalated`, { childrenStopped, plan: fresh }) : die(`children still running: ${running.map((k) => k.instance).join(", ")}; nothing retired`);
   }
   let r;
-  try { r = retireInstance(root, name, { home: homeFlag, self: isSelf, discardWorktree: args.includes("--discard-worktree"), keepDir: args.includes("--keep-dir"), force: args.includes("--force") }); }
+  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 } : {}) }); }
   catch (e) { if (!e?.code) throw e; return args.includes("--json") ? jsonFail(e.code, e.message, e.candidates ? { ...e.details, candidates: e.candidates } : e.details) : die(e.message); }
   if (childrenStopped) r.childrenStopped = childrenStopped;
   if (replayPath) { r.planRevision = planRev; r.idempotencyKey = idemKey; r.replayed = false; try { writeFileAtomic(replayPath, JSON.stringify(r, null, 2)); } catch { /* receipt is evidence, not authority */ } }
@@ -2563,6 +2585,7 @@ function retireCmd() {
   // Preserving work and not saying so leaves the operator believing it is gone,
   // which is most of the harm of deleting it. Name the classes and the path.
   for (const line of workRecoveryLines(r)) console.log(line);
+  for (const line of extraWorktreeLines(r)) console.log(line);
   for (const w of r.warnings || []) console.log(`  WARNING: ${w}`);
   if (isSelf) console.log("This window dies in ~8s — say any goodbyes now.");
 }
@@ -2599,19 +2622,25 @@ async function scheduleCmd() {
       case "show": return out({ schedule: describeSchedule(ws(), needId(), io, { ctx: ctx() }) });
       case "test": return out({ test: testSchedule(ws(), needId(), io, { ctx: ctx() }) }, (r) => `${r.test.qualifiedId}: ${r.test.placement.runsHere ? "runs here" : `not here (${r.test.placement.reason ?? "disabled here"})`}${r.test.soul ? `; soul ${r.test.soul.name} ${r.test.soul.resolves ? "resolves" : `does NOT resolve (${r.test.soul.error?.code})`}` : ""}; next due ${r.test.nextDue ?? "never"}${r.test.problems.length ? `\n  ${r.test.problems.join("\n  ")}` : ""}\n(spawned nothing)`);
       case "add": {
-        const spec = readSpec();
+        const spec = withDescription(readSpec(), descriptionFlag());
         if (flag("workspace") !== undefined) {
           const wid = id ?? spec.id;
           if (typeof wid !== "string") throw scheduleError("E_BAD_ARGS", "oats schedule add <id> --workspace <member> …: the id names the file (oats-schedules/<id>.yaml)");
-          const { id: _i, enabled: _e, kind, ...rest } = spec; void _i; void _e;
-          const r = await addWorkspaceAutomation(scheduleKind({ dep: ws() }), { id: wid, body: { run: kind ?? "spawn", ...rest } });
+          // A description is the file header's, never the body's.
+          const { id: _i, enabled: _e, kind, description, ...rest } = spec; void _i; void _e;
+          const r = await addWorkspaceAutomation(scheduleKind({ dep: ws() }), { id: wid, body: { run: kind ?? "spawn", ...rest }, description });
           return out(r, printWorkspaceAdd);
         }
         if (id && spec.id === undefined) spec.id = id;
         if (id && spec.id !== id) throw scheduleError("E_SCHEDULE_INVALID", `id ${JSON.stringify(spec.id)} in the file does not match ${JSON.stringify(id)}`, { field: "id" });
         return out({ schedule: addSchedule(ws(), spec, io) });
       }
-      case "update": return out({ schedule: updateSchedule(ws(), needId(), readSpec(), io) });
+      case "update": {
+        const description = descriptionFlag();
+        // --description alone (no --file/--spec-json) changes only the description.
+        if (description !== undefined && flag("file") === undefined && flag("spec-json") === undefined) return out({ schedule: updateScheduleDescription(ws(), needId(), description, io) });
+        return out({ schedule: updateSchedule(ws(), needId(), withDescription(readSpec(), description), io) });
+      }
       case "enable":
       case "disable": {
         const on = sub === "enable";
@@ -2654,7 +2683,7 @@ async function scheduleCmd() {
         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 [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>]|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> [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>]|update <id> (--file <spec.json> [--description=<text>] | --description=<text>)|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).
@@ -2673,7 +2702,7 @@ async function triggerCmd() {
   const ws = () => (scope ??= scheduleScopeOf(dirFlag()));
   const out = (result, text) => { if (JSON_MODE) jsonOk(result); else console.log(text ? text(result) : JSON.stringify(result, null, 2)); };
   const needId = () => { if (!id) throw T.triggerError("E_BAD_ARGS", `oats trigger ${sub} <id>`); return id; };
-  const usage = "usage: oats trigger add (--file <trigger.json> | --from <package>:<template> [--set <name>=<value>]… [--id <id>]) [--workspace <member> --runs-on <host> --owner <host>/<login>] | list | show <id> | enable <id> | disable <id> | remove <id> | test <id> | status [<id>]  [--dir <deployment>] [--json]   (<id>: local/<id> or <member>/<id>)";
+  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>)";
   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");
   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}` : ""}`;
   // The workspace automations of this deployment (the snapshot) placed on this host.
@@ -2693,6 +2722,15 @@ async function triggerCmd() {
         actx = undefined;
         return out({ trigger: T.describeTrigger(ws(), id, ctx()) }, (r) => line(r.trigger));
       }
+      case "update": {
+        // Description only, for now (0.43.0): a full trigger update is remove + add.
+        const known = new Set(["--description", "--dir", "--json"]);
+        const other = args.slice(2).find((a) => a.startsWith("--") && !known.has(a));
+        if (other) throw T.triggerError("E_BAD_ARGS", `oats trigger update: only --description is supported for now (got ${other}); to change anything else, remove the trigger and add it again`);
+        const description = descriptionFlag();
+        if (description === undefined) throw T.triggerError("E_BAD_ARGS", "oats trigger update <id> --description=<text> (--description= clears it)");
+        return out({ trigger: T.updateTriggerDescription(ws(), needId(), description, ctx()) }, (r) => line(r.trigger));
+      }
       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(", ")})` : ""}`);
       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)");
       case "test": {
@@ -2727,6 +2765,7 @@ async function triggerCmd() {
         }
         const idFlag = flag("id");
         if (idFlag === true) throw T.triggerError("E_BAD_ARGS", "--id needs a trigger id");
+        const description = descriptionFlag();
         let spec;
         if (file !== undefined) {
           if (file === true || !existsSync(file)) throw T.triggerError("E_BAD_ARGS", `--file ${file === true ? "needs a path" : `not found: ${file}`}`);
@@ -2739,12 +2778,14 @@ async function triggerCmd() {
           const kinds = await automationKinds(ws(), readLock(ws()), remoteOptionsFromEnv());
           const wid = typeof idFlag === "string" ? idFlag : from !== undefined ? String(from).split(":")[1] : spec?.id;
           if (typeof wid !== "string") throw T.triggerError("E_BAD_ARGS", "--workspace: name the trigger with --id (or an id in the file)");
-          const body = from !== undefined ? { from: String(from), ...(Object.keys(sets).length ? { set: sets } : {}) } : (({ id: _i, kind: _k, enabled: _e, template: _t, createdAt: _c, updatedAt: _u, ...rest }) => rest)(spec);
-          const r = await addWorkspaceAutomation(kinds.trigger, { id: wid, body });
+          // A description is the file header's (the flag, else the file's), never the body's; made
+          // from a template without one, the row shows the template's.
+          const body = from !== undefined ? { from: String(from), ...(Object.keys(sets).length ? { set: sets } : {}) } : (({ id: _i, kind: _k, enabled: _e, template: _t, createdAt: _c, updatedAt: _u, description: _d, ...rest }) => rest)(spec);
+          const r = await addWorkspaceAutomation(kinds.trigger, { id: wid, body, description: description ?? spec?.description });
           return out(r, printWorkspaceAdd);
         }
         if (spec === undefined) spec = await triggerFromPackage(T, String(from), sets, idFlag);
-        return out({ trigger: T.addTrigger(ws(), spec) }, (r) => `added ${line(r.trigger)}\n(\`oats trigger test ${r.trigger.id}\` checks gh, the repository, the soul and the teams on this host)`);
+        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)`);
       }
       default: throw T.triggerError("E_BAD_ARGS", usage);
     }
@@ -3267,7 +3308,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", "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 }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions"], 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)`);
@@ -3571,6 +3612,8 @@ async function serverRouteCmd() {
         rest.push("--spec-json", readFileSync(f, "utf8"));
         continue;
       }
+      // An inline --description travels inline (it may be empty, or start with --).
+      if (a === "--description" && inlineValues.has("description")) { rest.push(`--description=${inlineValues.get("description")}`); continue; }
       rest.push(a);
     }
     let out;
@@ -3714,6 +3757,7 @@ async function serverRouteCmd() {
     }
     console.log(`Retired ${r.retired} on ${id}${r.deferred ? " (deferred completion scheduled there)" : ""}${r.rollbackIncomplete ? " — cleanup INCOMPLETE on the server, home retained there" : ""}`);
     for (const line of workRecoveryLines(r, { host: target.sshHost })) console.log(line);
+    for (const line of extraWorktreeLines(r, { host: target.sshHost })) console.log(line);
     if (r.rollbackIncomplete) {
       for (const f of r.rollbackIncomplete) console.error(`  ${f}`);
       const branch = failedSpawnBranchLine(r, r.rollbackIncomplete, { host: target.sshHost });
@@ -3942,10 +3986,14 @@ Usage:
       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 schedule add|update <id> … --description=<text>   a one-line summary (1-200 characters)
+  oats schedule update <id> --description=<text>   change only it (--description= clears it)
   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;
                                                 see docs/schedules.md#triggers)
+  oats trigger add … --description=<text>    a one-line summary (1-200 characters)
+  oats trigger update <id> --description=<text>   change only it (--description= clears it)
   oats trigger|schedule add … --workspace <member> --runs-on <host> --owner <host>/<login>
                                                 a trigger/schedule declared in Git (<member>/<id>):
                                                 writes oats-triggers|oats-schedules/<id>.yaml in a

package/docs/desktop-cli-api.md

@@ -108,6 +108,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
 | `capability-route` | `oats <namespace> <command> … --server <id>` runs the capability command on the server, OATS 0.39.0 ([Capability commands on a server](#capability-commands-on-a-server)) | |
 | `operator-default-soul` | a capability command from a deployment without `--soul` runs as the first soul that provides its namespace (named on stderr); none is `E_BAD_ARGS`, OATS 0.39.0 ([capabilities.md](capabilities.md)) | |
 | `waiting-on-you` | the `waiting` event kind and the session boundary rule; `oats instance waiting` and `oats instance attention`; `waitingOnYou` (with `message`) on `oats status --json` instance rows, on `oats session inspect --json` and in the events read, OATS 0.40.0 ([Waiting on you](#waiting-on-you)) | `eventsApi: 2` |
+| `automation-descriptions` | a `description` on every trigger and schedule row, local or workspace, by one rule; `oats schedule update <id> --description=<text>` (the description only) and `oats trigger update <id> --description=<text>`; `--description=<text>` on `schedule add` and `trigger add`, OATS 0.43.0 ([Shared row fields](#automations-shared-rows)) | |
 
 Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
 `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -1923,7 +1924,11 @@ route target:
                "running":true,"identity":{"alias":"dev-a","address":"acme/dev-a"},"identityAddress":"acme/dev-a",
                "teams":[{"label":"default","team":"acme:team"}],"startedAt":"2026-09-29T10:00:00.000Z","createdAt":"2026-09-29T09:58:12.004Z",
                "model":"opus","runtimeState":null,"parentInstance":"lead","siblingInstance":null,"relation":"child","relativeTo":"lead",
-               "spawnOrigin":"instance","retirePending":false,"rollbackIncomplete":false,
+               "spawnOrigin":"instance","work":"worktree","repo":"/srv/team/ws","branch":"agents/dev-a","modelFrom":"soul",
+               "soul":{"repoKey":"github.com/acme/team","commit":"66566512…","current":"9c1e04ab…","status":"moved"},
+               "modules":[{"name":"oats.okf","from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"ab897841…","integrity":"sha256-bada35…","repoKey":"github.com/awebai/oats-okf"},
+                           "commit":"ab897841…","current":{"commit":"ab897841…","version":"2.1.3"},"status":"current"}],
+               "retirePending":false,"rollbackIncomplete":false,
                "savedRoute":false,"addressable":true,"missingRemotely":false}],
  "retireFailures":[]}
 ```
@@ -1940,9 +1945,16 @@ route target:
 - **Instance rows** relay the host's own `status --json` row: `identity`,
   `identityAddress`, `teams`, `startedAt`, `createdAt`, `model`,
   `runtimeState`, `parentInstance`, `siblingInstance`, `relation`,
-  `relativeTo` and `spawnOrigin` are always present, `null` when the host
-  does not supply them (a host before 0.31, a fact it never recorded, or a
-  saved route the host no longer lists). Nothing is derived on this side.
+  `relativeTo` and `spawnOrigin`, and (relayed from 0.42.1) `work`, `repo`,
+  `branch`, `modelFrom`, `soul` and `modules`, are always present, `null`
+  when the host does not supply them (an older host, a fact it never
+  recorded, or a saved route the host no longer lists). Each is the
+  [local row's](#the-roster-oats-status---json) fact of the same name,
+  relayed as the host answered it. Nothing is derived on this side: `repo`
+  is a path on the host, never read here, and `soul` and `modules` are the
+  host's own drift observation (against its own members and lock), not
+  recomputed: `modules` is the drift rows, or the recorded map when the host
+  could not read its workspace, as on a local row.
 - **`waitingOnYou`** (0.40.2, [Waiting on you](#waiting-on-you)) is on a row
   only when the host's kernel reports it: a row from a host before 0.40.0,
   and a saved route the host did not list, have no such key. Absent means
@@ -2219,6 +2231,15 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
   `--delete-branch` (since 0.41.0: `this self-retire was requested with
   --delete-branch by an older OATS; retirement no longer deletes branches, so
   the branch and the worktree were left`).
+- `worktree-retained` (`data: {movedTo, branch, recordedBranch}`) and
+  `worktree-removed` (`data: {branch}`) are written to the workspace log only,
+  by the retire's worktree step. Since 0.42.1 the retire also writes one per
+  extra tree it handled
+  ([extra trees at retire](souls-and-instances.md#extra-trees-at-retire)),
+  with `extra: true` and the tree's absolute `path` added:
+  `worktree-retained` `{movedTo, branch, recordedBranch: null, extra: true,
+  path}` and `worktree-removed` `{branch, extra: true, path}`. A row without
+  `extra` is about `work/`.
 - **Incarnation.** Each row carries the writing home's `createdAt` (or
   `null` for old rows); the top-level `incarnation` is the current home's (or
   `null`). Earlier incarnations are returned as this address's history.
@@ -2438,7 +2459,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
                   "upstream":{"ref":null,"ahead":null,"behind":null},"base":{"ref":null,"ahead":null,"behind":null},"remote":null},
           "workMode":"worktree","repo":"/w/one","recordedBranch":"agents/dev-1",
           "children":[{"instance":"dev-1-child","agent":"dev","home":"/w/agents/dev/instances/dev-1-child","session":{"state":"shell","present":true,"backend":"tmux","established":true}}],
-          "ambiguous":[],"pullRequest":"unknown"},
+          "ambiguous":[],"pullRequest":"unknown",
+          "extraWorktrees":[{"path":"/w/agents/dev/instances/dev-1/.work-docs","repo":"/w/docs","branch":"agents/dev-1-docs","detachedAt":null,
+                             "disposition":"retain","movedTo":"/w/.agents/worktrees/docs/agents-dev-1-docs","reason":"…"}]},
  "defaults":{"retainWorktree":true,"deleteBranch":false,"stopChildren":true,"retainChildren":true},
  "planRevision":"4e5f6a7b8c9d0e1f2a3b4c5d","notes":["the worktree is on feat/x, not the recorded agents/dev-1; …"]}
 ```
@@ -2476,10 +2499,35 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
   there when it is not empty` in directory mode, and absent in checkout,
   attached and workspace modes. They are strings in `notes`: no other key
   changes, and `planRevision` is unaffected.
+- `facts.extraWorktrees` (0.42.1) lists the instance's
+  [extra trees](souls-and-instances.md#extra-trees-at-retire): linked
+  worktrees at `<home>/.work-*` that Git confirms. It is an array, empty when
+  there are none, in every work mode. Each row is `{path, repo, branch,
+  detachedAt, disposition, movedTo, reason}`:
+  - `path`: the tree's absolute path in the home.
+  - `repo`: its repository, the first entry of that repository's `git
+    worktree list` (the main worktree, or the bare repository).
+  - `branch`: the branch its HEAD is on, or `null`. `detachedAt`: the commit
+    when HEAD is detached, else `null`.
+  - `disposition`: `"remove"` (the tree is clean: it would be removed, its
+    branch kept), `"retain"` (it would be moved to `movedTo`, as `work/` is
+    retained) or `"refuse"` (the retire would refuse with
+    `E_WORK_PRESERVATION_FAILED` and keep the home).
+  - `movedTo`: the target for `"retain"`, else `null`.
+  - `reason`: `null` for `"remove"`, why the tree is not clean for
+    `"retain"`, why it is refused for `"refuse"`.
+
+  `notes` also carries one string per tree that says the same. The trees are
+  part of `planRevision`: a tree created, removed, dirtied or cleaned between
+  the plan and the apply, or a change of its disposition or target (another
+  directory taking the `<leaf>-N` it would move to, for example), refuses a
+  guarded apply with `E_PLAN_STALE` before anything runs. A reader that does
+  not know the key can ignore it; the `notes` strings say the same.
 
 Plain `retire` keeps a worktree-mode instance's work: the worktree is moved
 (`git worktree move`) to `<deployment>/.agents/worktrees/<repo>/<branch>` (a
-`-2` suffix if taken; `detached-<oid12>` when detached), state intact.
+`-2` suffix if taken; `detached-<oid12>` when detached), state intact. An
+extra tree that is not clean is moved the same way; a clean one is removed.
 
 ```text
 oats retire <instance> [--plan-revision <rev> --idempotency-key <key>] [--discard-worktree] [--home <abs>] --json
@@ -2535,6 +2583,21 @@ A first retire prints the **raw receipt**, not an envelope:
   retire (hooks run, a recovery copied), and neither says that one happened:
   an error here is not proof that nothing happened, nor that a recovery
   exists.
+- `extraWorktrees` (0.42.1): the extra trees the retire handled, present only
+  when it handled at least one. Each row is the plan's row (`{path, repo,
+  branch, detachedAt, disposition, movedTo, reason}`) plus `outcome`:
+  `"removed"` or `"retained"`, with `movedTo` where a retained tree went. The
+  step runs only when the home is removed (not with `--keep-dir`, not when the
+  home is kept for a retry), after the hooks and before the worktree step of
+  `work/`. `--discard-worktree` does not apply to it. A locked tree
+  (`"refuse"` in the plan) stops the retire with `E_WORK_PRESERVATION_FAILED`
+  naming the tree before anything runs (no session stop, no retire hook);
+  a lock that appears during the hooks, or a move or removal Git refuses,
+  stops it at the step, after the hooks. `--force` does not bypass either;
+  the home and `work/` are kept, and trees already handled stay handled. A tree
+  that no longer matches what the applied plan said refuses with
+  `E_PLAN_STALE`, the home kept, rather than be moved or removed unplanned.
+  The key is additive.
 - `workRecovery`: `{path, classes, bytes, home, outputs?, repoCopy?,
   notCopied?, afterHooks?}`, present when a recovery was written. One retire
   writes at most one recovery directory, and `path` is that directory.
@@ -2560,10 +2623,12 @@ A first retire prints the **raw receipt**, not an envelope:
     names: a prefix that matches several entries lists each one, and a
     declared entry that does not exist is not listed. `owner` is the
     declaring capability; when two declare the same entry it is the first in
-    capability-name order. Each entry has exactly these three keys: names and
-    owners only, no sizes, hashes, modes or contents of what was left out.
-    `scope` is always `"home"` in this release. Present only when there is
-    at least one.
+    capability-name order. Since 0.42.1 the list also holds each verified
+    extra tree (`.work-<purpose>`), with `owner: "kernel:extra-worktree"`: the
+    retire handles it at its own step, never in the copy. Each entry has
+    exactly these three keys: names and owners only, no sizes, hashes, modes
+    or contents of what was left out. `scope` is always `"home"` in this
+    release. Present only when there is at least one.
   - `afterHooks`: `{home: boolean, work: boolean}`, saying which parts were
     copied again under `after-hooks/`: `after-hooks/home/` when a retire hook
     changed the home (its bytes and permission bits, the kernel's own
@@ -2615,8 +2680,9 @@ A first retire prints the **raw receipt**, not an envelope:
   `idempotencyKey` and `replayed: false`.
 
 Refusals (envelopes): `E_PLAN_STALE`, `E_CHILDREN_RUNNING`,
-`E_WORK_PRESERVATION_FAILED` (the home is kept; retry or
-`--discard-worktree`), `E_WORK_INSPECTION_FAILED` (the home is kept; the
+`E_WORK_PRESERVATION_FAILED` (the home is kept; retry, or
+`--discard-worktree` when it is `work/` that could not be re-homed: it does
+not apply to an extra tree), `E_WORK_INSPECTION_FAILED` (the home is kept; the
 message names the entry or the state that could not be read),
 `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
 `E_NO_ROOT`, `E_LIFECYCLE_FAILED`. A recovery whose Git status disagrees with
@@ -2797,6 +2863,7 @@ workspace item of a readable member. Render the rows; never re-derive them.
 ```text
 oats schedule list [--dir <d>] --json
 oats schedule show <id> --json
+oats schedule update <id> --description=<text> [--dir <d>] --json
 ```
 
 ```json
@@ -2823,6 +2890,14 @@ oats schedule show <id> --json
 - `list`: `{scope, scheduleApi, scheduleHistoryApi, integrity, host,
   triggers, snapshot, schedules, scheduler}`; `triggers` counts the trigger
   definitions left out. `show <id>`: `{schedule}`, without `integrity`.
+- `update <id> --description=<text>` without `--file`/`--spec-json` (feature
+  `automation-descriptions`) changes only a local schedule's description,
+  any kind's (a command schedule too), and is allowed while the job runs or
+  has an unresolved attempt. `--description=` (empty) removes it. It answers
+  `{schedule}` (the row `show` answers). A workspace schedule refuses
+  `E_AUTOMATION_WORKSPACE`; out of the rule is `E_SCHEDULE_INVALID {field:
+  "description"}`. Run it as argv, without a shell, always in the `=` form.
+  An older kernel refuses it as a missing `--file`.
 - **A readable row**: the definition (`id, kind, cron, tz, enabled, …`, and
   `agent/task/purpose/harness` for a spawn, `argv/cwd` for a command, the
   message for a wake, the operation for an operation) plus `scope,
@@ -2842,14 +2917,8 @@ oats schedule show <id> --json
   limit. Desktop accepts these schedule names for creation, editing and row
   actions (enable, disable, test, run and reconcile), including qualified IDs.
   A spawn's derived instance name still has a 64-character limit.
-- **`description`** (0.40.0): the shared row field is the local definition's
-  `description` when it has one, else `null` (a workspace schedule's comes
-  from its file header). It is one line of at most 200 characters with no
-  control characters; show it in place of the argv when present. Like `task`,
-  it is untrusted text: render it as text. Desktop preserves it unchanged
-  through edits to timing and other fields. A kernel before 0.40.0 sends
-  `null` for every local schedule, and drops a `description` given to `oats
-  schedule add` without refusing it.
+- **`description`**: the [shared row field](#automations-shared-rows).
+  Desktop preserves it unchanged through edits to timing and other fields.
 - **An unreadable row** (`list` only): `{id, scope, scheduleApi,
   scheduleHistoryApi, unreadable: {code, message}, history: {status:
   "corrupt", stored: null, truncated: false}, recentRuns: []}`. One bad job
@@ -2899,14 +2968,14 @@ oats schedule show <id> --json
 ### `oats trigger`
 
 ```text
-oats trigger list | show <id> | status [<id>] | test <id> | add (--file <json> | --from <package>:<template> [--set k=v]) | enable <id> | disable <id> | remove <id> --json
+oats trigger list | show <id> | status [<id>] | test <id> | add (--file <json> | --from <package>:<template> [--set k=v]) [--description=<text>] | update <id> --description=<text> | enable <id> | disable <id> | remove <id> --json
 ```
 
 Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
 "trigger"`).
 
 - `list`: `{triggerApi, scope, host, snapshot, triggers, scheduler}`.
-  `show`, `add`, `enable`, `disable` → `{trigger}`; `remove` → `{removed,
+  `show`, `add`, `update`, `enable`, `disable` → `{trigger}`; `remove` → `{removed,
   live: [instance]}`. A stored definition that no longer validates carries
   `invalid: {code, message, field?}`.
 - **A trigger row**: the [shared row fields](#automations-shared-rows) plus
@@ -2942,6 +3011,12 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
   cannot reach is a warning.
 - A triggered instance records `instance.json.trigger`; its event file is
   `OATS_TRIGGER_EVENT_FILE`.
+- `update <id> --description=<text>` (feature `automation-descriptions`)
+  changes only a local trigger's description; `--description=` (empty)
+  removes it. It sets `updatedAt` and leaves fired and pending events
+  untouched. `<id>` is `local/<id>` or the bare id; a workspace trigger
+  refuses `E_AUTOMATION_WORKSPACE`. Any other flag is `E_BAD_ARGS` ("only
+  --description is supported for now"). An older kernel has no `update`.
 - Errors: `E_TRIGGER_INVALID {field}`, `E_TRIGGER_EXISTS`,
   `E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `E_TRIGGER_POLL`,
   `E_TRIGGER_FAILED`, `E_BAD_ARGS`, `E_PACKAGE_MISSING`,
@@ -2967,7 +3042,18 @@ registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
   localPath}` or `{kind: "workspace", repoKey, path, commit, url,
   localPath}` (`url` for `github.com` only; `localPath` `null` when the
   member is not cloned here).
-- `description`, `owner`, `runsOn`, `runsHere`, `reason` (`null` |
+- `description`: what it is for, in words, or `null`. One rule for both kinds
+  and every level: one line of 1 to 200 characters with no control
+  characters (no `\p{Cc}`, U+2028 or U+2029). A local item's comes from its
+  definition; a workspace item's from its file header, and for a trigger made
+  `from:` a package template, the template's when the header has none. A
+  header out of the rule counts as none (the item still runs) and leaves a
+  snapshot problem at `<path>#/description`. Like `task`, it is untrusted
+  text: render it as text. A kernel before 0.43.0 (feature
+  `automation-descriptions`) sends `null` for every local trigger and refuses
+  a trigger `description`; one before 0.40.0 sends `null` for every local
+  schedule too.
+- `owner`, `runsOn`, `runsHere`, `reason` (`null` |
   `host-unnamed` | `assigned-elsewhere` | `owner-mismatch` | `untrusted`),
   `reasonDetail`, `enabledHere`.
 - `untrusted` (0.30, [automations.trust](configuration.md#who-runs-workspace-automations)):

package/docs/desktop.md

@@ -211,6 +211,17 @@ whether the host scheduler is enabled. Pause, edit, run now and delete operate
 on that workspace's saved jobs. Launching an agent is reported separately from
 the end of its run; neither means its task succeeded.
 
+Each schedule and trigger can carry a one-line **summary** (up to 200
+characters), shown under its name in the list. Without one, the list shows the
+first line of the task or wake message in italics, or "No summary" for a
+command or operation. Set it in the schedule form's Summary field, or with
+**Edit summary** on any local schedule or trigger (leave it empty to remove
+it); a workspace item's summary is its file's `description:` in Git. A detail
+page shows everything the item sends (the whole prompt or message, a command's
+arguments as written, an operation and its home), its run state and where it
+comes from. Writing summaries needs OATS 0.43 or later; an older OATS still
+shows the ones it reports.
+
 The Spawn dialog also has an optional **Recurring wake-up** setting. It binds
 the schedule to the newly created home, preserving that agent's identity and
 work. A wake starts that same home if it is stopped, then sends the saved
@@ -249,14 +260,18 @@ for a password or key, and never runs anything over ssh itself.
 
 Every instance a registered server reports shows in its workspace's roster, whoever spawned it. You
 can open its terminal, start, restart, stop and remove it, and read its readiness, activity, Git
-and diffs, as for a local one. Only its pull request is not read here, since the forge reads this
+and diffs, as for a local one. The context panel's Soul tab and its Messaging & Teams list read
+through the server too (`oats inspect --server <id> --home <path>`), and its Work card, "model
+from" line and "older build" chip show the facts the server relays. Only its pull request is not read here, since the forge reads this
 computer's clones. Every command goes to the server by the instance's home (`--server <id> --home
 <path>`), never by a bare name. Stop and Remove show the plan the server makes, and confirm
 against it.
 
 A read waits for the server: the view says "Reading from <server>…", and gives up after about
 45 seconds with "Couldn't reach <server>." When the server refuses, you see its code and message;
-nothing is read from this computer in its place. A row that can't be opened says why on the row:
+nothing is read from this computer in its place. When the server's OATS, or this computer's, lacks
+what a part of the panel needs, that part names the server and says which OATS to update, rather
+than showing nothing. A row that can't be opened says why on the row:
 Herdr no longer supported, gone from <server>, not reachable on <server>, or <server> not reached.
 For an instance a server no longer lists, the reason names the command that removes it from this
 computer (`oats server forget <server> --instance <name>`).

package/docs/packages.md

@@ -283,6 +283,12 @@ A package may also ship **trigger templates**: `triggers: [{ id,
 file }]` in `oats-package.json`, each file `{ parameters, definition }`.
 `oats trigger add --from <package>:<id> --set <name>=<value>` instantiates one
 at the locked commit; see [schedules.md#triggers](schedules.md#triggers).
+A template's `definition` may carry `description`, the one-line summary its
+triggers show (validated like any trigger's: one line of 1 to 200 characters
+without control characters). `add --from` copies it and `--description=<text>`
+overrides it; a workspace trigger made `from:` it shows its file header's
+description, else the template's. A kernel before 0.43.0 refuses the key, so
+a package whose template sets it needs `compatibility.oats: ">=0.43.0"`.
 
 ## Compatibility floors