@awebai/oats 0.42.1 → 0.43.0

package/bin/oats.mjs

@@ -47,7 +47,7 @@ import { attachArgv, checkRemote, connectServer, forgetSnapshot, getServer, insp
 import { spawnSync as spawnSyncProc } from "node:child_process";
 import { tickTriggers } from "../lib/triggers.mjs";
 import * as A from "../lib/automations.mjs";
-import { parseEnvelopeText, 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";
 
@@ -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);
@@ -2603,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";
@@ -2658,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).
@@ -2677,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.
@@ -2697,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": {
@@ -2731,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}`}`);
@@ -2743,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);
     }
@@ -3271,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)`);
@@ -3575,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;
@@ -3947,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
@@ -2862,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
@@ -2888,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,
@@ -2907,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
@@ -2964,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
@@ -3007,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`,
@@ -3032,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

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
 

package/docs/release-notes/v0.43.0.md

@@ -0,0 +1,93 @@
+# OATS 0.43.0
+
+## Added
+
+- **A one-line summary for every schedule and trigger** (feature
+  `automation-descriptions`). One rule covers every kind and level. A
+  `description` is one line of 1 to 200 characters with no control characters
+  (no `\p{Cc}`, U+2028 or U+2029). Before this, only local schedules could
+  carry one.
+  - **Local triggers take `description`.** Out of the rule it is refused as
+    `E_TRIGGER_INVALID {field: "description"}`. `oats trigger list` and `show`
+    used to send `null` for every local trigger; they now show it.
+  - **Package trigger templates may carry `definition.description`.** It is
+    validated like any trigger's. `oats trigger add --from` copies it, and
+    `--description=<text>` overrides it. A workspace trigger made `from:` a
+    template shows its file header's description, or the template's when the
+    header has none. A kernel before 0.43.0 refuses the key, so a package
+    whose template sets it needs `compatibility.oats: ">=0.43.0"`.
+  - **`--description=<text>` on `oats schedule add` and `oats trigger add`**
+    sets the description, or overrides the one in the spec. `--description=`
+    with an empty value leaves it out. With `--workspace`, the description goes
+    to the file header, never into the body.
+  - **Change only the description:**
+
+    ```sh
+    oats schedule update <id> --description=<text>   # without --file/--spec-json
+    oats trigger update <id> --description=<text>
+    ```
+
+    `--description=` clears it. Both work on local schedules and triggers
+    only; a workspace one is changed in Git (`E_AUTOMATION_WORKSPACE`). A
+    schedule's description may change while the job runs or has an unresolved
+    attempt, and the update runs under the same locks as any other. A
+    trigger's fired and pending events are untouched. `oats trigger update`
+    takes no other flag for now (`E_BAD_ARGS`): a full trigger update is still
+    a remove and an add. `oats schedule … --server <id>` with `--description`
+    needs the destination to advertise `automation-descriptions`
+    (`E_REMOTE_INCOMPATIBLE` otherwise).
+
+  The Desktop gates its summary writes on the feature. See
+  [schedules](../schedules.md#kinds) and the
+  [Desktop CLI API](../desktop-cli-api.md#automations-shared-rows).
+
+### Desktop
+
+- **Schedules and Triggers show each item's summary.** A row shows the item's
+  name beside its origin tag (`local`, or the member), in place of
+  `local/<id>`, and its summary under it. Without a summary, the row shows the
+  first non-empty line of the task or wake message in muted italics, titled "No
+  summary set — first line of the prompt". A command or operation row without
+  one shows "No summary": the Desktop never makes a label from argv.
+- **A detail page shows everything an item does**
+  ([#545](https://github.com/awebai/oats/issues/545)). The title is the name,
+  with the qualified id under it, and then the summary or "No summary".
+  - **What it sends, in full:** a spawn's or trigger's task; a wake's whole
+    message and the home it wakes (before, a wake said "No prompt"); a
+    command's argv exactly as written, one argument per chip, and its working
+    directory; an operation and the home it runs in.
+  - **Spawns** also shows a spawn schedule's purpose (never shown before),
+    harness and model, launch configuration, permissions, session backend, and
+    the spawn's own recurring wake.
+  - **Run state** shows a schedule that is running and since when. It also
+    shows a run whose state is unknown and since when, with its exit facts,
+    whether it still holds a host slot, *Check run state* and the
+    `oats schedule reconcile <id> [--clear]` command to paste. A held job lock
+    no longer hides an unknown run. It also shows a wake waiting to be delivered.
+  - **An Invalid or Unreadable item** gets a card with its code, field and
+    message. Before, they appeared only in a tag's tooltip.
+  - **Comes from** adds the package template an item was made from (package,
+    version, commit) and a local item's created and updated times.
+- **Set a summary from the Desktop** (needs a CLI with
+  `automation-descriptions`). The schedule form has an optional **Summary**
+  field. **Edit summary** sets or clears the summary of any local schedule
+  (command ones included) or local trigger, from the detail page or the row
+  menu; it runs `oats <kind> update <id> --description=<text>`. The text is
+  saved as typed, and an empty value removes it. A workspace item's summary is
+  its file's `description:` in Git. With an older CLI, the Desktop shows the
+  summaries it reports and the form keeps a stored summary unchanged.
+
+## Changed
+
+- **A workspace file header whose `description` breaks the rule is a warning,
+  not a refusal.** Before, a non-string header description stopped the entry
+  (`E_AUTOMATION_SCHEMA`), and any other value was accepted unchecked. Now the
+  entry still loads and runs, with `description: null`, and the snapshot
+  reports an `E_AUTOMATION_SCHEMA` problem at `<path>#/description`:
+  "description: one line of 1 to 200 characters without control characters —
+  shorten it or remove it; the automation keeps running without one". A label
+  never stops a job. `oats trigger|schedule add --workspace` refuses an
+  out-of-rule description before it writes the file.
+- **The Desktop accepts OATS CLIs `>=0.25.8 <0.44.0`**, so it runs against
+  this release's kernel; the Desktop 0.42.x refuses a 0.43 CLI. Upgrade the
+  Desktop and the CLI together.

package/docs/schedules.md

@@ -52,14 +52,21 @@ 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.
+Every schedule and trigger, of any kind, may carry `description`: what it is
+for, in words, for the people reading `oats schedule list`, `oats trigger
+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). A local schedule or trigger that breaks
+the rule is refused, `E_SCHEDULE_INVALID` or `E_TRIGGER_INVALID` with `field:
+"description"`; a workspace file's header that breaks it is only a warning
+(see [the header](#workspace-triggers-and-schedules)). It is stored as given
+and is informational only: it never reaches a run's argv, environment, task,
+template or reconcile. A capability that registers jobs (knowledge harvest's
+`run-source` jobs) sets it so that its command jobs can be told apart. Set it
+in the definition or with `--description=<text>` on `add`; change only it with
+`update <id> --description=<text>` (see [Commands](#commands)). Local triggers
+take it from OATS 0.43.0 (feature `automation-descriptions`); an older kernel
+refuses the key on a trigger.
 
 - **spawn** `{…, agent, agentsRoot?, repo?, backend?, purpose?, task,
   launchConfig?, harness?, model?, yolo?, wake?}` — every due minute launches
@@ -131,6 +138,7 @@ when the timer cannot reach it.
 
 ```json
 { "id": "okf-harvest-review", "enabled": true, "kind": "trigger",
+  "description": "Review every harvest PR on the knowledge base",
   "on": { "source": "github.pull_request", "repo": "github.com/acme/knowledge",
           "events": ["opened", "reopened", "ready_for_review"],
           "labels": ["okf-harvest"], "base": "main", "poll": "2m" },
@@ -178,15 +186,19 @@ when the timer cannot reach it.
   harness, and is recorded in `instance.json.trigger`.
 
 ```sh
-oats trigger add --file trigger.json                 # or:
-oats trigger add --from oats.okf:harvest-review --set repo=github.com/acme/knowledge [--id <id>]
+oats trigger add --file trigger.json [--description=<text>]   # or:
+oats trigger add --from oats.okf:harvest-review --set repo=github.com/acme/knowledge [--id <id>] [--description=<text>]
+oats trigger update <id> --description=<text>   # the description only; --description= clears it
 oats trigger list | show <id> | enable <id> | disable <id> | remove <id>
 oats trigger test <id>      # dry run: gh credentials, repo permissions, the soul, what WOULD fire
 oats trigger status [<id>]  # last poll, next due, pending and fired events, live vs max, last error
 ```
 
 All take `--dir` and `--json` (`triggerApi: 1`). `remove` leaves the instances
-it spawned running. `oats schedule list` does not list triggers but counts
+it spawned running. `update` changes only a local trigger's description (any
+other flag is `E_BAD_ARGS`: a full trigger update is a remove and an add); it
+sets `updatedAt` and leaves the trigger's fired and pending events as they
+are. A workspace trigger is changed in Git (`E_AUTOMATION_WORKSPACE`). `oats schedule list` does not list triggers but counts
 them (`triggers: { count, command: "oats trigger list" }`, and a line in text
 mode). Errors: `E_TRIGGER_INVALID { field }`, `E_TRIGGER_EXISTS`,
 `E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `E_BAD_ARGS`.
@@ -196,8 +208,10 @@ in `oats-package.json`, each file `{ parameters: { <name>: { path, required?,
 default?, description? } }, definition }`. `oats trigger add --from
 <package>:<id>` reads it at the locked commit, and `--set <name>=<value>`
 fills a parameter at its dotted `path` (a list value is comma-separated; a
-missing required one is `E_BAD_ARGS { missing }`). See
-[packages.md](packages.md#trigger-templates).
+missing required one is `E_BAD_ARGS { missing }`). A template's `definition`
+may carry `description` (validated like any trigger's): `add --from` copies
+it, and `--description=<text>` overrides it (`--description=` leaves it out).
+See [packages.md](packages.md#trigger-templates).
 
 ## Workspace triggers and schedules
 
@@ -246,6 +260,15 @@ owner: github.com/ana
   `runsOn` and `owner`, and optionally `id`, `description` and `enabled`. A
   candidate of the wrong kind (a schedule in `oats-triggers/`) or without one
   is an `E_AUTOMATION_SCHEMA` problem, never silently skipped.
+- **The description** follows the [one rule](#kinds), but a header that
+  breaks it does not stop the job: the entry still loads and runs as if it
+  had none (`description: null`), and the snapshot reports an `E_AUTOMATION_SCHEMA`
+  problem at `<path>#/description` ("description: one line of 1 to 200
+  characters without control characters — shorten it or remove it; the
+  automation keeps running without one"). A trigger made `from:` a package
+  template shows the header's description, else the template's. It lives in
+  the header only: `add --workspace` writes the flag's (else the spec's) there,
+  never into the body.
 - **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. Schedule IDs allow 1 to 100 lowercase letters, digits and dashes; trigger
@@ -312,8 +335,9 @@ check the placement and everything else on this host.
 ## Commands
 
 ```sh
-oats schedule add <id> --file spec.json [--dir <deployment>] [--json]
-oats schedule update <id> --file spec.json
+oats schedule add <id> --file spec.json [--description=<text>] [--dir <deployment>] [--json]
+oats schedule update <id> --file spec.json [--description=<text>]
+oats schedule update <id> --description=<text>   # the description only; --description= clears it
 oats schedule list | show <id> | enable <id> | disable <id> | remove <id> [--force]
 oats schedule run <id> [--force]  # now, under the same lock and bound
 oats schedule test <id>           # dry run: where it runs, whether its soul resolves, when it is next due
@@ -326,6 +350,16 @@ oats schedule host status | uninstall
 oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?"   # or --wake-file spec.json
 ```
 
+`--description=<text>` sets the spec's `description`, or overrides it;
+`--description=` (empty) removes it. Take the `=` form: it is the one that
+carries an empty value, or one that starts with `-`. With `--file` or
+`--spec-json`, `update` replaces the whole definition as before (one without a
+description drops it). Without them, `update <id> --description=<text>`
+changes only the description of a local schedule, under the same locks, and
+is allowed while the job runs or has an unresolved attempt. With `--server`,
+the destination must advertise `automation-descriptions`
+(`E_REMOTE_INCOMPATIBLE` otherwise, before anything is forwarded).
+
 `<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

package/lib/automations.mjs

@@ -19,7 +19,8 @@
  *    `.git/` or `node_modules/`. One recursive tree listing per member commit serves both kinds.
  *  - THE HEADER: `kind: <fileKind>` + `schemaVersion: 1` (a wrong or missing kind is
  *    E_AUTOMATION_SCHEMA), `id:` or the filename stem, `runsOn` (a host name), `owner` (a GitHub
- *    account, `<host>/<login>`), `description?`, `enabled?`. A duplicate id within one member and
+ *    account, `<host>/<login>`), `description?` (out of the one rule, validateDescription, it is a
+ *    warning and the entry runs without one), `enabled?`. A duplicate id within one member and
  *    one kind is E_AUTOMATION_DUPLICATE.
  *  - PLACEMENT: a host runs one ONLY when `runsOn` is its `host.name` (oats-local.yaml), its
  *    authenticated `gh` account is `owner` AND its `automations.trust` admits it (0.30: both
@@ -59,6 +60,21 @@ const LOCAL = "local";
 const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
 export function automationError(code, message, details) { return Object.assign(new Error(message), { code, ...(details ? { details } : {}) }); }
 
+// ------------------------------------------------------------ descriptions
+
+/** A trigger's or schedule's `description`: a one-line label for people (list, show, the
+ *  Desktop), never read by a run. One rule for every kind and level (0.43.0): local schedules
+ *  and triggers refuse what breaks it; a workspace file header that breaks it is a warning. */
+export const DESCRIPTION_MAX = 200;
+export const DESCRIPTION_RULE = `one line of 1 to ${DESCRIPTION_MAX} characters, without control characters`;
+/** Throws `code` (the kind's own: E_SCHEDULE_INVALID, E_TRIGGER_INVALID) with field `description`
+ *  when `description` is not one line of 1 to 200 characters (code points) free of \p{Cc}, U+2028
+ *  and U+2029. */
+export function validateDescription(description, code = "E_AUTOMATION_SCHEMA") {
+  if (typeof description !== "string" || !description.length || [...description].length > DESCRIPTION_MAX || /[\p{Cc}\u2028\u2029]/u.test(description)) throw Object.assign(new Error(`description: ${DESCRIPTION_RULE}`), { code, field: "description", details: { field: "description" } });
+  return description;
+}
+
 // ------------------------------------------------------------ names
 
 /** `local/<id>` for a machine-private trigger or schedule, `<member>/<id>` for a workspace one. */
@@ -94,7 +110,9 @@ export function candidateOf(path, kinds) {
 }
 
 /** Parse one candidate file: the shared header here, the body by the kind's descriptor. The
- *  definition is not expanded yet. Never throws: → { entry } | { problem } */
+ *  definition is not expanded yet. Never throws: → { entry, warning? } | { problem }. A header
+ *  `description` out of the rule is a `warning` (the same shape as a problem): the entry still
+ *  loads and runs, with `description: null` — a label never stops a job. */
 export function parseAutomationFile(desc, { stem, path, bytes, member, repoKey, commit }) {
   const origin = { kind: "workspace", repoKey, path, commit };
   const problem = (message, field) => ({ problem: { code: "E_AUTOMATION_SCHEMA", kind: desc.kind, repoKey, path: field ? `${path}#/${field}` : path, message } });
@@ -113,12 +131,16 @@ export function parseAutomationFile(desc, { stem, path, bytes, member, repoKey,
   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");
-  if (doc.description !== undefined && typeof doc.description !== "string") return problem("description: text", "description");
   if (doc.enabled !== undefined && typeof doc.enabled !== "boolean") return problem("enabled: boolean", "enabled");
   let source;
   try { source = desc.parseBody(Object.fromEntries(Object.entries(doc).filter(([k]) => !HEADER_KEYS.includes(k)))); }
   catch (e) { return problem(e.message, e.field); }
-  return { entry: { kind: desc.kind, id: `${member}/${name}`, name, member, description: doc.description ?? null, runsOn: doc.runsOn, owner: `${owner.host}/${owner.login}`, enabled: doc.enabled !== false, origin, source } };
+  let description = null, warning;
+  if (doc.description !== undefined) {
+    try { description = validateDescription(doc.description); }
+    catch { warning = problem(`description: one line of 1 to ${DESCRIPTION_MAX} characters without control characters — shorten it or remove it; the automation keeps running without one`, "description").problem; }
+  }
+  return { entry: { kind: desc.kind, id: `${member}/${name}`, name, member, description, runsOn: doc.runsOn, owner: `${owner.host}/${owner.login}`, enabled: doc.enabled !== false, origin, source }, ...(warning ? { warning } : {}) };
 }
 
 /** Discover the workspace triggers and schedules of the confirmed members: one tree listing per
@@ -157,6 +179,7 @@ export async function discoverAutomations(discovery, { remote, memberName, kinds
       catch (e) { problems.push({ code: e?.code || "E_REMOTE_UNREADABLE", kind: c.kind, repoKey: m.key, path, message: e.message }); continue; }
       const parsed = parseAutomationFile(desc, { stem: c.stem, path, bytes, member: name, repoKey: m.key, commit: m.commit });
       if (parsed.problem) { problems.push(parsed.problem); continue; }
+      if (parsed.warning) problems.push(parsed.warning);
       const a = parsed.entry;
       const first = seen[a.kind].get(a.name);
       if (first) { problems.push({ code: "E_AUTOMATION_DUPLICATE", kind: a.kind, repoKey: m.key, path, message: `${a.kind} id ${JSON.stringify(a.name)} is declared by both ${first} and ${path}; ${path} is not listed` }); continue; }
@@ -387,9 +410,12 @@ export function memberCheckoutFor(dir, desc, id, { sameRepo }) {
 /** The fields every trigger row and every schedule row share (docs/desktop-cli-api.md): identity,
  *  origin, who and where. Each kind's module adds its own (`kind`, the soul, the task, the event
  *  or the cron, the last and next run). */
+const ruledDescription = (d) => { try { return d === undefined || d === null ? null : validateDescription(d); } catch { return null; } };
 export function baseRow(a) {
   return {
-    id: a.id, name: a.name, origin: a.origin, description: a.description ?? null,
+    // The header's (a workspace file), else the definition's (a local one; a package template's),
+    // never a stored one that breaks the rule (a hand-edited, invalid definition).
+    id: a.id, name: a.name, origin: a.origin, description: a.description ?? ruledDescription(a.definition?.description),
     owner: a.owner ?? null, runsOn: a.runsOn ?? null,
     runsHere: a.placement.runsHere, reason: a.placement.reason, ...(a.placement.detail ? { reasonDetail: a.placement.detail } : {}),
     enabledHere: a.placement.enabledHere,

package/lib/schedule.mjs

@@ -34,7 +34,7 @@ import { herdrSettingRemoved } from "./errors.mjs";
 import { withDirLock as withSharedDirLock } from "./dir-lock.mjs";
 import { tickTriggers } from "./triggers.mjs";
 import { resolveMemberClone } from "./instance-resolution.mjs";
-import { SCHEDULE_NAME_RE, readSnapshot, MODEL_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId } from "./automations.mjs";
+import { SCHEDULE_NAME_RE, readSnapshot, MODEL_RE, automationContext, automationError, baseRow, localEntry, localId, soulOriginOf, splitId, validateDescription } from "./automations.mjs";
 import { RESERVED_LAUNCH_ENV, MAX_INSTANCE_NAME, shq, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
 
 export const SCHEDULE_FILE = "oats-schedules.json";
@@ -323,11 +323,6 @@ export function validateCron(cron, tz, field = "cron") {
   try { return new Cron(cron.trim(), { timezone: tz, paused: true }); }
   catch (e) { throw scheduleError("E_SCHEDULE_INVALID", `${field}: ${e.message}`, { field }); }
 }
-/** A definition's `description`: a label for people (list, show, the Desktop), never read by a run. */
-const DESCRIPTION_MAX = 200;
-function validateDescription(description) {
-  if (typeof description !== "string" || !description.length || [...description].length > DESCRIPTION_MAX || /[\p{Cc}\u2028\u2029]/u.test(description)) throw scheduleError("E_SCHEDULE_INVALID", `description: one line of 1 to ${DESCRIPTION_MAX} characters, without control characters`, { field: "description" });
-}
 function validateMessage(message, field) {
   if (typeof message !== "string" || !message.trim() || message.includes("\0") || Buffer.byteLength(message) > MESSAGE_MAX) throw scheduleError("E_SCHEDULE_INVALID", `${field}: non-empty text without NUL, at most 256 KiB`, { field });
 }
@@ -351,7 +346,8 @@ export function validateDefinition(ws, def, { checkAgent = true, backendSource }
   if (typeof enabled !== "boolean") throw scheduleError("E_SCHEDULE_INVALID", "enabled: boolean", { field: "enabled" });
   validateCron(def.cron, def.tz);
   const out = { id, enabled, cron: def.cron.trim(), tz: def.tz.trim(), kind: def.kind };
-  if (def.description !== undefined) { validateDescription(def.description); out.description = def.description; }
+  // A label for people (list, show, the Desktop), never read by a run (lib/automations.mjs).
+  if (def.description !== undefined) out.description = validateDescription(def.description, "E_SCHEDULE_INVALID");
   if (def.kind === "spawn") {
     if (typeof def.agent !== "string" || !def.agent.trim() || def.agent.trim().startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", "agent: soul name required (not an option)", { field: "agent" });
     out.agent = def.agent.trim();
@@ -1190,7 +1186,7 @@ export function describe(ws, qid, io, { defs, st, now = new Date(), ctx = null }
   const { workspace: _w, ...stored } = def; void _w;
   const base = { ...stored, id, scope: ws, scheduleApi: 2, scheduleHistoryApi: SCHEDULE_HISTORY_API, executionStatus: scheduleExecutionStatus(def, intent, lock), nextRun, lastRun: js.lastRun ? { ...js.lastRun, runId: runIdOf(js.lastRun), session: sessionProvenanceOf(js.lastRun) } : null, history, recentRuns, running: !!lock, ...(js.attempt ? { attempt: js.attempt } : {}), ...(js.pendingWake ? { pendingWake: js.pendingWake } : {}) };
   const herdr = entry ? null : storedHerdrBackend(ws, id, def);
-  return scheduleRow(ws, entry ?? { ...localEntry("schedule", { ...def, id: name }, { dep: ws, ...(herdr ? { invalid: { code: herdr.code, message: herdr.message, field: herdr.field } } : {}) }), description: def.description ?? null }, base, ctx);
+  return scheduleRow(ws, entry ?? localEntry("schedule", { ...def, id: name }, { dep: ws, ...(herdr ? { invalid: { code: herdr.code, message: herdr.message, field: herdr.field } } : {}) }), base, ctx);
 }
 /** A schedule's list row: its stored facts, the fields every trigger and schedule row share
  *  (lib/automations.mjs baseRow) and the schedule's own: `kind` is its run (spawn, command, wake,
@@ -1256,6 +1252,23 @@ export function updateSchedule(ws, qid, spec, io) {
     return describe(ws, localId(id), io);
   }), { retryMs: 3000 });
 }
+/** Change only a local schedule's description (`oats schedule update <id> --description=<text>`),
+ *  under the same locks as an update. A label is not what a run is tracked by, so it may change
+ *  while the job runs or has an unresolved attempt; nothing else of the stored job is touched or
+ *  re-validated. `""` or null removes it. */
+export function updateScheduleDescription(ws, qid, description, io) {
+  const id = localScheduleId(qid, "update");
+  const clear = description === "" || description === null || description === undefined;
+  if (!clear) validateDescription(description, "E_SCHEDULE_INVALID");
+  return withHostLock(() => withScopeLock(ws, () => {
+    const defs = readDefinitions(ws);
+    if (!defs.jobs[id] || defs.jobs[id].kind === "trigger") throw scheduleError("E_SCHEDULE_UNKNOWN", `no schedule ${JSON.stringify(id)} in ${ws}${defs.jobs[id] ? " (it is a trigger: use oats trigger)" : ""}`);
+    const { description: _d, ...rest } = defs.jobs[id]; void _d;
+    defs.jobs[id] = { ...rest, ...(clear ? {} : { description }), updatedAt: new Date().toISOString() };
+    writeDefinitions(ws, defs);
+    return describe(ws, localId(id), io);
+  }), { retryMs: 3000 });
+}
 export function setEnabled(ws, qid, enabled, io) {
   const id = localScheduleId(qid, "change");
   return withScopeLock(ws, () => {

package/lib/servers.mjs

@@ -1103,6 +1103,11 @@ export function scheduleRemote(serverId, oatsArgs, io = {}) {
     throw e;
   }
   if (setsHostCaps && !remote.features.includes("schedule-host-caps")) throw capsUnsupported();
+  // --description on add/update (0.43.0): an older kernel would ignore it on add, or refuse a
+  // description-only update as a missing --file; refused here before anything is forwarded.
+  if (["add", "update"].includes(oatsArgs[0]) && oatsArgs.some((a) => a === "--description" || a.startsWith("--description=")) && !remote.features.includes("automation-descriptions")) {
+    throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} (${serverId}) does not advertise automation-descriptions, so it cannot take --description; upgrade oats on that destination, or put description in the spec`);
+  }
   if (["add", "update"].includes(oatsArgs[0])) {
     const indexes = oatsArgs.flatMap((arg, index) => arg === "--spec-json" ? [index] : []);
     if (indexes.length > 1) throw serverError("E_BAD_ARGS", "remote schedule spec must be unambiguous");

package/lib/triggers.mjs

@@ -30,7 +30,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry, definitionsPath } from "./schedule.mjs";
 import { herdrSettingRemoved } from "./errors.mjs";
-import { MODEL_RE, automationError, baseRow, localEntry, localId, parseOwner, qualifiedId, soulOriginOf } from "./automations.mjs";
+import { MODEL_RE, automationError, baseRow, localEntry, localId, parseOwner, qualifiedId, soulOriginOf, validateDescription } from "./automations.mjs";
 import { lockedPackageRef } from "./packages.mjs";
 
 export const TRIGGER_API = 1;
@@ -91,11 +91,13 @@ function checkTemplate(text, field) {
  *  spawn.backend, for the refusal of `herdr` (Herdr was removed in 0.31.0). */
 export function validateTrigger(def, { backendSource = "the trigger's spawn.backend" } = {}) {
   if (!isObject(def)) throw invalid("definition", "must be an object");
-  onlyKeys(def, ["id", "enabled", "kind", "on", "spawn", "concurrency", "template", "createdAt", "updatedAt"], "");
+  onlyKeys(def, ["id", "enabled", "kind", "description", "on", "spawn", "concurrency", "template", "createdAt", "updatedAt"], "");
   if (typeof def.id !== "string" || !ID_RE.test(def.id)) throw invalid("id", "lowercase letters, digits and dashes, 1 to 40 characters");
   if (def.kind !== "trigger") throw invalid("kind", "must be \"trigger\"");
   const enabled = def.enabled === undefined ? true : def.enabled;
   if (typeof enabled !== "boolean") throw invalid("enabled", "boolean");
+  // A label for people (list, show, the Desktop), never templated or read by a poll or a spawn.
+  if (def.description !== undefined) validateDescription(def.description, "E_TRIGGER_INVALID");
   const on = def.on;
   if (!isObject(on)) throw invalid("on", "{ source, repo, events, labels?, base?, poll? }");
   onlyKeys(on, ["source", "repo", "events", "labels", "base", "poll"], "on.");
@@ -133,7 +135,7 @@ export function validateTrigger(def, { backendSource = "the trigger's spawn.back
   for (const [k, v] of [["max", max], ["perKey", perKey]]) if (!Number.isInteger(v) || v < 1 || v > 100) throw invalid(`concurrency.${k}`, "a whole number from 1 to 100");
   if (def.template !== undefined && !isObject(def.template)) throw invalid("template", "the package template this trigger was made from");
   return {
-    id: def.id, enabled, kind: "trigger",
+    id: def.id, enabled, kind: "trigger", ...(def.description !== undefined ? { description: def.description } : {}),
     on: { source: on.source, repo: repo.key, events: [...on.events], labels: [...labels], ...(on.base !== undefined ? { base: on.base.trim() } : {}), poll },
     spawn: { soul: sp.soul, purpose, task: sp.task, teams: [...teams], ...(sp.launchConfig ? { launchConfig: sp.launchConfig } : {}), ...(sp.harness ? { harness: sp.harness } : {}), ...(sp.model ? { model: sp.model } : {}), ...(sp.yolo !== undefined ? { yolo: sp.yolo } : {}), ...(sp.backend ? { backend: sp.backend } : {}) },
     concurrency: { max, perKey },
@@ -601,6 +603,23 @@ export function setTriggerEnabled(ws, id, enabled, ctx = null) {
     return describeTrigger(ws, e.id, ctx);
   });
 }
+/** Change only a LOCAL trigger's description (`oats trigger update <id> --description=<text>`):
+ *  `""` or null removes it. Its fired and pending state is untouched; a workspace trigger is
+ *  changed in Git. */
+export function updateTriggerDescription(ws, id, description, ctx = null) {
+  const e = requireTrigger(ws, id, ctx);
+  refuseWorkspace(e, "change");
+  const clear = description === "" || description === null || description === undefined;
+  if (!clear) validateDescription(description, "E_TRIGGER_INVALID");
+  return withScopeLock(ws, () => {
+    const defs = readDefinitions(ws);
+    if (defs.jobs[e.name]?.kind !== "trigger") throw triggerError("E_TRIGGER_UNKNOWN", `no trigger ${JSON.stringify(id)} in ${ws}`, { details: { id: e.id } });
+    const { description: _d, ...rest } = defs.jobs[e.name]; void _d;
+    defs.jobs[e.name] = { ...rest, ...(clear ? {} : { description }), updatedAt: new Date().toISOString() };
+    writeDefinitions(ws, defs);
+    return describeTrigger(ws, e.id, ctx);
+  });
+}
 /** Remove the definition and its state. Live instances it spawned are untouched. */
 export function removeTrigger(ws, id, ctx = null) {
   const e = requireTrigger(ws, id, ctx);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.42.1",
+  "version": "0.43.0",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",