@awebai/oats 0.42.0 → 0.43.0

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/core.mjs

@@ -71,7 +71,7 @@ export { exactTreeDigest, fingerprintTree, KERNEL_HOME_RECEIPTS };
 import { canonicalJson, lineAt, parseStrictJson } from "./canonical-json.mjs";
 import { readPortableBytes } from "./bounded-read.mjs";
 import { copyTreeSafe } from "./tree-copy.mjs";
-import { assertSameWorktreeHead, headName, worktreeCommitUnreached, worktreeHead } from "./instance-git.mjs";
+import { assertSameWorktreeHead, gitRead, gitRepoRead, gitRepoRun, headName, worktreeCommitUnreached, worktreeHead } from "./instance-git.mjs";
 /** The package and capability id grammar (namespaced, lowercase): an id names a
  *  directory (a home's module copy), so no path spelling fits it. */
 const PACKAGE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
@@ -5141,18 +5141,123 @@ function baselineDisposableHome(baseline) {
  *  that pass all use this one set. → { excludeRoot: Set (work/ and the covered
  *  names), notCopied: [{ scope: "home", path, owner }] sorted by path }: names
  *  and owners only. Two owners of one entry: the first in owner order. */
-function resolveHomeExclusions(home, disposableHome = []) {
+function resolveHomeExclusions(home, disposableHome = [], extraTrees = []) {
   const excludeRoot = new Set(["work"]);
   const notCopied = [];
-  if (!disposableHome.length) return { excludeRoot, notCopied };
+  const extra = new Set(extraTrees.map((t) => t.name));
+  if (!disposableHome.length && !extra.size) return { excludeRoot, notCopied };
   for (const name of readdirSync(home).sort(byCodeUnit)) {
-    const row = name === "work" ? undefined : disposableHome.find((r) => disposableHomeRootMatches(r.root, name));
-    if (!row) continue;
+    const owner = extra.has(name) ? EXTRA_WORKTREE_OWNER : name === "work" ? undefined : disposableHome.find((r) => disposableHomeRootMatches(r.root, name))?.owner;
+    if (!owner) continue;
     excludeRoot.add(name);
-    notCopied.push({ scope: "home", path: name, owner: row.owner });
+    notCopied.push({ scope: "home", path: name, owner });
   }
   return { excludeRoot, notCopied };
 }
+
+/** The `notCopied` owner of a verified extra tree: the retire's extra-tree
+ *  step handles it, not the home recovery. */
+const EXTRA_WORKTREE_OWNER = "kernel:extra-worktree";
+/** `git worktree list --porcelain -z` → [{ worktree, locked }]: `locked` is
+ *  the lock's reason ("" when it gives none), undefined when not locked. */
+function parseWorktreeList(out) {
+  const records = [];
+  for (const field of out.split("\0")) {
+    if (field.startsWith("worktree ")) records.push({ worktree: field.slice("worktree ".length) });
+    else if (records.length && (field === "locked" || field.startsWith("locked "))) records.at(-1).locked = field.slice("locked ".length);
+  }
+  return records;
+}
+/** The home's extra trees (awebai/oats#674), in every work mode: top-level
+ *  entries named `.work-*` that are real directories (not symlinks), whose
+ *  `.git` is a regular file, and that Git confirms are registered linked
+ *  worktrees of a repository outside the home: the git dir differs from the
+ *  common dir, the toplevel is the entry, and the repository's worktree list
+ *  names it. The repository is that list's first entry (its main worktree, or
+ *  the bare dir), as for the primary checkout (canonicalDeploymentPath).
+ *  Anything else named `.work-*` is ordinary home bytes. Read-only probes
+ *  (gitRead). → [{ name, path, repo, gitDir, commonDir, locked }] sorted by
+ *  name: `commonDir` is the repository's Git directory, which the step and
+ *  the reachability read name it by (bare or not). */
+function extraWorktreesOf(home) {
+  const trees = [];
+  let names;
+  try { names = readdirSync(home); } catch { return trees; }
+  const realHome = realPathOrNearest(home);
+  const inHome = (p) => { const rel = relative(realHome, realPathOrNearest(p)); return rel === "" || !(rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)); };
+  for (const name of names.sort(byCodeUnit)) {
+    if (!name.startsWith(".work-")) continue;
+    const path = join(home, name);
+    try {
+      if (!lstatSync(path).isDirectory() || !lstatSync(join(path, ".git")).isFile()) continue;
+    } catch { continue; }
+    const dirs = gitRead(path, ["rev-parse", "--path-format=absolute", "--git-dir", "--git-common-dir", "--show-toplevel"]);
+    if (!dirs.ok) continue;
+    const [gitDir, commonDir, toplevel] = dirs.out.split("\n");
+    if (!gitDir || !commonDir || !toplevel || realPathOrNearest(gitDir) === realPathOrNearest(commonDir)) continue;
+    const real = realPathOrNearest(path);
+    // A repository inside the home goes with the home: its trees are home bytes.
+    if (realPathOrNearest(toplevel) !== real || inHome(commonDir)) continue;
+    const list = gitRead(path, ["worktree", "list", "--porcelain", "-z"]);
+    if (!list.ok) continue;
+    const records = parseWorktreeList(list.out);
+    const self = records.find((r) => realPathOrNearest(r.worktree) === real);
+    if (!records.length || !self) continue;
+    trees.push({ name, path, repo: records[0].worktree, gitDir, commonDir: realPathOrNearest(commonDir), locked: self.locked });
+  }
+  return trees;
+}
+/** Where a retired worktree is re-homed: `<workspace>/.agents/worktrees/<repoName>/<leaf>`,
+ *  the leaf being the branch, else `detached-<commit>`; when that exists (or
+ *  `taken` holds it), `<leaf>-2`, `-3`, … The one naming rule of work/ and of
+ *  the extra trees. Creates nothing. */
+function retainedWorktreeDest(workspace, repo, branch, commit, taken = new Set()) {
+  const repoName = basename(realPathOrNearest(repo)).replace(/\.git$/, "") || "repo";
+  const leaf = (branch ?? `detached-${(commit || "unknown").slice(0, 12)}`).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
+  const retainedRoot = join(workspace, ".agents", "worktrees", repoName);
+  let dest = join(retainedRoot, leaf);
+  for (let n = 2; existsSync(dest) || taken.has(dest); n++) dest = join(retainedRoot, `${leaf}-${n}`);
+  taken.add(dest);
+  return dest;
+}
+/** What retirement does with each extra tree (`trees`: extraWorktreesOf) →
+ *  [{ path, repo, branch, detachedAt, disposition, movedTo, reason }], one row
+ *  per tree in order: the retire plan's `extraWorktrees` and the binding the
+ *  retire checks before it acts. `remove` when the tree is clean: an empty
+ *  status (ignored and untracked files count), no operation in progress, and
+ *  a HEAD commit some ref of the repository reaches: its shared refs, never
+ *  the tree's own HEAD, reflog or refs/worktree/, which go with its admin
+ *  entry when it is removed. `retain` (to `movedTo`) otherwise, with why
+ *  in `reason`; a HEAD that cannot be read is not clean. `refuse` for a locked
+ *  tree, which Git will neither move nor remove. Read-only. */
+function extraWorktreeRows(trees, root) {
+  const taken = new Set();
+  return trees.map((tree) => {
+    let name = null, commit = null;
+    try { name = headName(tree.path); } catch { /* not clean, below */ }
+    try { commit = worktreeHead(tree.path).commit; } catch { /* not clean, below */ }
+    const row = { path: tree.path, repo: tree.repo, branch: name?.branch ?? null, detachedAt: name?.detached ? commit : null, disposition: "remove", movedTo: null, reason: null };
+    if (tree.locked !== undefined) return { ...row, disposition: "refuse", reason: `it is locked${tree.locked ? ` (${tree.locked})` : ""}; unlock it with \`git worktree unlock\`, or move it out of the home, then retire again` };
+    const why = [];
+    if (!name || !commit) why.push("its HEAD could not be read");
+    const status = gitRead(tree.path, ["status", "--porcelain", "-z", "--ignored", "--untracked-files=all", "--ignore-submodules=none"]);
+    if (!status.ok) why.push(`its status could not be read (${status.err})`);
+    else if (status.out.length) why.push("it holds uncommitted, untracked or ignored files");
+    if (RECOVERABLE_GIT_ADMIN.some((n) => existsSync(join(tree.gitDir, n)))) why.push("an operation is in progress in it");
+    if (commit) {
+      const reach = gitRepoRead(tree.commonDir, ["for-each-ref", "--contains", commit, "--count=1", "--format=%(objectname)"]);
+      if (!reach.ok) why.push(`which refs reach its HEAD commit could not be read (${reach.err})`);
+      else if (!reach.out.length) why.push("its HEAD commit is reached by no ref");
+    }
+    if (!why.length) return row;
+    return { ...row, disposition: "retain", movedTo: retainedWorktreeDest(workspaceOf(root), tree.repo, row.branch, commit, taken), reason: why.join("; ") };
+  });
+}
+/** The retire plan's view of a home's extra trees: extraWorktreeRows of what
+ *  is there now. */
+export function extraWorktreePlan(home, root) {
+  return extraWorktreeRows(extraWorktreesOf(home), root);
+}
 function unionNotCopied(...lists) {
   const byPath = new Map();
   for (const row of lists.flatMap((list) => list || [])) if (!byPath.has(row.path)) byPath.set(row.path, row);
@@ -6414,9 +6519,11 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
   }
   const baselineValid = retirementBaselineValid(baseline, home);
   // This pass's one resolved exclusion set: provider-owned entries the spawn
-  // baseline declared. Every home fingerprint here and the copy made from this
-  // observation use it; without a valid baseline there is none.
-  const homeExclusions = resolveHomeExclusions(home, baselineValid ? baselineDisposableHome(baseline) : []);
+  // baseline declared, and the home's verified extra trees (whatever the
+  // baseline), which the retire's extra-tree step handles from this same set.
+  // Every home fingerprint here and the copy made from this observation use it.
+  const extraTrees = extraWorktreesOf(home);
+  const homeExclusions = resolveHomeExclusions(home, baselineValid ? baselineDisposableHome(baseline) : [], extraTrees);
   // One walk of the home, two digests: the stored one for the comparison with
   // the baseline, which must not see the kernel's own fields of instance.json,
   // and the exact one for the comparison after the hooks, which must see
@@ -6504,7 +6611,7 @@ function inspectRetirementWork(home, work, isWorktree, { recordedBranch, worktre
     .update("\0").update(unreached ? `${unreached.head.commit}\0${unreached.unreached ? "unreached" : "reached"}\0` : "")
     .update(unreached?.head.ref ?? "")
     .digest("hex");
-  return { classes: [...new Set(classes)], home, work, directory, orphanedWork, worktree, workProvable, directoryFingerprint, homeBytes: homeDigests.exact, workFingerprint, homeExclude: homeExclusions.excludeRoot, notCopied: homeExclusions.notCopied, branchExists, head: unreached?.head, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
+  return { classes: [...new Set(classes)], home, work, directory, orphanedWork, worktree, workProvable, directoryFingerprint, homeBytes: homeDigests.exact, workFingerprint, homeExclude: homeExclusions.excludeRoot, notCopied: homeExclusions.notCopied, extraTrees, branchExists, head: unreached?.head, runtimeAuthority: baselineValid ? runtimeAuthorityOf(baseline) : undefined };
 }
 
 function copyRecoveryTree(src, dest, { excludeRoot = new Set() } = {}) {
@@ -7020,7 +7127,8 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
   const intent = {
     instance: name, agent: found.agent.name, root: resolve(root),
     requestedAt: new Date().toISOString(), requestedByPid: process.pid, delaySec,
-    options: { home: found.home, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session }, resultPath,
+    // A confirmed plan's extra trees go with the intent, so the completion is bound by them as well.
+    options: { home: found.home, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session, ...(Array.isArray(o.plannedExtraWorktrees) ? { plannedExtraWorktrees: o.plannedExtraWorktrees } : {}) }, resultPath,
   };
   const env = { ...process.env, OATS_RETIRE_INTENT: JSON.stringify(intent) };
   for (const k of CORE_LAUNCH_ENV) delete env[k];
@@ -7098,6 +7206,7 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
   try {
     result = retireInstance(intent.root, intent.instance, {
       home: intent.options?.home, keepDir: !!intent.options?.keepDir, tmuxSession: intent.options?.tmuxSession,
+      ...(Array.isArray(intent.options?.plannedExtraWorktrees) ? { plannedExtraWorktrees: intent.options.plannedExtraWorktrees } : {}),
       ...(obsoleteDeleteBranch ? { [OBSOLETE_DELETE_BRANCH]: true } : {}),
     });
   } catch (e) {
@@ -7241,6 +7350,16 @@ export function retireInstance(root, name, o = {}) {
   // Whether this retire removes the worktree, when it gets to that step.
   const worktreeRemoval = { removes: !!(o.discardWorktree || owesWorktree), repo: meta.repo };
   const initialObservation = inspectRetirementWork(found.home, workPath, inspectableWorktree, { recordedBranch, worktreeRemoval, directory, orphanedWork });
+  // A locked extra tree is known from the home as it is now: Git will neither move nor remove it, so a retire that
+  // would remove the home refuses here, before the session is stopped and before any retire hook runs (the hooks
+  // revoke identities a kept home would still need). The extra-tree step keeps its own check, for a lock that appears
+  // during the hooks. --force does not bypass it: it covers hook debt, not local work.
+  if (!o.keepDir) {
+    const locked = initialObservation.extraTrees.filter((t) => t.locked !== undefined);
+    if (locked.length) {
+      throw oatsError("E_WORK_PRESERVATION_FAILED", `${name}: ${locked.map((t) => `the extra worktree ${t.path} is locked${t.locked ? ` (${t.locked})` : ""}`).join("; ")}; Git will neither move nor remove a locked worktree. Unlock it with \`git worktree unlock\`, or move it out of the home, then retire again; nothing was run or removed`);
+    }
+  }
   // Harness identity is destructive authority. The mutable child metadata may
   // describe it for humans, but only the independent baseline can authorize the
   // endpoint that proves quiescence.
@@ -7484,6 +7603,54 @@ export function retireInstance(root, name, o = {}) {
   // A failed spawn's quarantine that owes the worktree removes it; any other retire retains it unless
   // --discard-worktree. An orphaned work directory is never touched.
   const outstandingBeforeWorktree = quarantine ? retryFailures : ordinaryIncomplete;
+  // The home's extra trees (awebai/oats#674), in every work mode, before the
+  // work/ step so that a refusal here leaves work/ as it is. Only when the
+  // home is going to be removed: not under --keep-dir, and not when it is
+  // kept for a retry (the work/ step's condition). The trees are the final
+  // inspection's verified set, the one its recovery left out of the home's
+  // bytes. A clean tree is removed (its branch stays in its repository); any
+  // other is re-homed like work/; a locked one, or one Git will not move or
+  // remove, refuses and keeps the home, --force included: it covers hook
+  // debt, not local work. --discard-worktree does not apply. An applied plan
+  // (`plannedExtraWorktrees`) binds what is done: trees that no longer read
+  // as planned refuse as stale before any of them is touched.
+  let extraWorktrees;
+  if (!o.keepDir && !(outstandingBeforeWorktree.length > 0 && !o.force)) {
+    const rows = extraWorktreeRows(finalObservation.extraTrees, root);
+    if (o.plannedExtraWorktrees && JSON.stringify(rows) !== JSON.stringify(o.plannedExtraWorktrees)) {
+      throw oatsError("E_PLAN_STALE", `${name}: the home's extra worktrees changed since the retire plan was shown, so none of them was moved or removed. The retire hooks have run; the home and its work are kept. Review the fresh plan (\`oats retire ${name} --plan\`) and apply it again.`);
+    }
+    const refused = rows.filter((r) => r.disposition === "refuse");
+    if (refused.length) {
+      throw oatsError("E_WORK_PRESERVATION_FAILED", `${name}: ${refused.map((r) => `the extra worktree ${r.path}: ${r.reason}`).join("; ")}. No extra worktree was moved or removed and work/ is untouched; the retire hooks have run and the home is kept so nothing is lost.`);
+    }
+    extraWorktrees = [];
+    const done = () => extraWorktrees.length ? ` Already done in this retire: ${extraWorktrees.map((r) => r.outcome === "removed" ? `${r.path} removed` : `${r.path} re-homed to ${r.movedTo}`).join(", ")}.` : "";
+    // Each row's repository, by its Git directory: the commands run helper-free (gitRepoRun).
+    const gitDirOf = new Map(finalObservation.extraTrees.map((tree) => [tree.path, tree.commonDir]));
+    const git = (row, argv) => gitRepoRun(gitDirOf.get(row.path), argv);
+    const failed = (row, what, e) => oatsError("E_WORK_PRESERVATION_FAILED", `${name}: the extra worktree ${row.path} ${what} (${String(e?.stderr ?? e?.message ?? e ?? "").trim()}).${done()} work/ is untouched; the retire hooks have run and the home is kept so nothing is lost — resolve and retry.`);
+    for (const row of rows) {
+      if (row.disposition === "remove") {
+        try {
+          git(row, ["worktree", "remove", row.path]);
+          git(row, ["worktree", "prune"]);
+          const real = realPathOrNearest(row.path);
+          if (existsSync(row.path) || parseWorktreeList(git(row, ["worktree", "list", "--porcelain", "-z"])).some((r) => realPathOrNearest(r.worktree) === real)) throw new Error("it is still there after `git worktree remove`");
+        } catch (e) { throw failed(row, "could not be removed, or its removal could not be verified", e); }
+        extraWorktrees.push({ ...row, outcome: "removed" });
+        appendEvent(found.home, { kind: "worktree-removed", data: { branch: row.branch, extra: true, path: row.path } }, { workspaceOnly: true });
+      } else {
+        try {
+          mkdirSync(dirname(row.movedTo), { recursive: true });
+          git(row, ["worktree", "move", row.path, row.movedTo]);
+        } catch (e) { throw failed(row, `could not be re-homed to ${row.movedTo}`, e); }
+        extraWorktrees.push({ ...row, outcome: "retained" });
+        appendEvent(found.home, { kind: "worktree-retained", data: { movedTo: row.movedTo, branch: row.branch, recordedBranch: null, extra: true, path: row.path } }, { workspaceOnly: true });
+      }
+    }
+    if (!extraWorktrees.length) extraWorktrees = undefined;
+  }
   const worktreeStep = isWorktree && !!meta.repo && !orphanedWork;
   const worktreeDeferred = worktreeStep && existsSync(workPath) && outstandingBeforeWorktree.length > 0 && !o.force;
   const keptForRetry = worktreeDeferred ? `git worktree ${workPath}: kept for the retry; outstanding: ${outstandingBeforeWorktree.join("; ")}` : null;
@@ -7507,12 +7674,8 @@ export function retireInstance(root, name, o = {}) {
       shTry(`git -C ${shq(meta.repo)} worktree prune`);
       retention = { worktree: "removed", branch: verifiedBranch, recordedBranch: meta.branch ?? null };
     } else if (existsSync(workPath)) {
-      const repoName = basename(realPathOrNearest(meta.repo)).replace(/\.git$/, "") || "repo";
-      const leaf = (verifiedBranch ?? `detached-${(ref.commit || "unknown").slice(0, 12)}`).replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "work";
-      const retainedRoot = join(workspaceOf(root), ".agents", "worktrees", repoName);
-      mkdirSync(retainedRoot, { recursive: true });
-      let dest = join(retainedRoot, leaf);
-      for (let n = 2; existsSync(dest); n++) dest = join(retainedRoot, `${leaf}-${n}`);
+      const dest = retainedWorktreeDest(workspaceOf(root), meta.repo, verifiedBranch, ref.commit);
+      mkdirSync(dirname(dest), { recursive: true });
       try {
         execFileSync("git", ["-C", meta.repo, "worktree", "move", workPath, dest], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
       } catch (e) {
@@ -7623,7 +7786,7 @@ export function retireInstance(root, name, o = {}) {
     rmSync(deferredRetireResultPath(found.home).replace(/\.json$/, ".log"), { force: true });
   }
 
-  const result = { retired: name, agent: found.agent.name, workRecovery, retention, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: (() => {
+  const result = { retired: name, agent: found.agent.name, workRecovery, retention, extraWorktrees, worktreeRemoved: isWorktree && !!retention && retention.worktree !== "retained", branchDeleted: false, removedDir: !o.keepDir && (!stillIncomplete || forced), rollbackIncomplete: forced ? undefined : stillIncomplete, forcedIncomplete: forced ? stillIncomplete : undefined, retainedHome: stillIncomplete && !forced ? found.home : undefined, relinked: relinked.length ? relinked : undefined, capabilityMeta: hookResults?.meta, warnings: (() => {
     const w = [...(hookResults?.warnings || [])];
     if (o[OBSOLETE_DELETE_BRANCH]) w.push(OBSOLETE_DELETE_BRANCH_SENTENCE);
     if (isCapturedHome(meta) && !quarantine) {

package/lib/instance-git.mjs

@@ -43,6 +43,28 @@ function git(cwd, argv, { allowFail = false, input, diffExit = false } = {}) {
   }
 }
 const trim = (s) => (s === null ? null : s.trim());
+/** One helper-free Git probe run like the module's other reads
+ *  (READ_ONLY_GIT, gitEnv, argv, no shell) → { ok, out, err }. `out` is text.
+ *  Never throws: the caller decides what a failure means. `cwd`: the tree
+ *  `-C` names; gitRepoRead names the repository by its Git directory instead. */
+export function gitRead(cwd, argv) { return gitProbe(["-C", cwd], argv); }
+/** gitRead against the repository whose (common) Git directory is `gitDir`,
+ *  named explicitly (`--git-dir`), so that a bare repository is read too
+ *  (READ_ONLY_GIT sets safe.bareRepository=explicit). */
+export function gitRepoRead(gitDir, argv) { return gitProbe(["--git-dir", gitDir], argv); }
+/** A Git command that changes the repository whose Git directory is `gitDir`
+ *  (a worktree move, remove or prune), under the same discipline as the
+ *  reads: the repository's own configuration names no helper that runs
+ *  (fsmonitor, hooks, external diff; they reach the commands Git starts for
+ *  it through GIT_CONFIG_PARAMETERS), and nothing of the caller's Git
+ *  environment is passed. → stdout; throws the error execFileSync throws. */
+export function gitRepoRun(gitDir, argv) {
+  return execFileSync("git", ["--git-dir", gitDir, ...READ_ONLY_GIT, ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 120_000, env: gitEnv() });
+}
+function gitProbe(where, argv) {
+  const r = spawnSync("git", [...where, ...READ_ONLY_GIT, ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER, shell: false, timeout: 30_000, env: gitEnv() });
+  return !r.error && r.status === 0 ? { ok: true, out: r.stdout } : { ok: false, out: "", err: String(r.error?.message ?? r.stderr ?? "").trim() || `git ${argv[0]} exited with ${r.status}` };
+}
 
 const BRANCH_REFS = Buffer.from("refs/heads/");
 /** The two reads of HEAD, as bytes. They run like the module's other reads:

package/lib/instance-lifecycle.mjs

@@ -10,7 +10,7 @@
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
-import { findInstanceHomes, inspectInstanceSession, listAgents, listInstances, observeSessionWithoutReceipt, retirePendingMarkerPath, retirementRecoveryFacts, stopInstanceSession } from "./core.mjs";
+import { extraWorktreePlan, findInstanceHomes, inspectInstanceSession, listAgents, listInstances, observeSessionWithoutReceipt, retirePendingMarkerPath, retirementRecoveryFacts, stopInstanceSession } from "./core.mjs";
 import { groupedByOwner } from "./retire-output.mjs";
 import { observeInstanceGit } from "./instance-git.mjs";
 import { appendEvent } from "./instance-events.mjs";
@@ -165,6 +165,13 @@ function writeFileSyncAtomic(path, value) {
   writeFileSync(tmp, JSON.stringify(value, null, 2)); renameSync(tmp, path);
 }
 
+/** A retire plan's note for one extra tree (core extraWorktreePlan row). */
+function extraWorktreeNote(t) {
+  const at = t.branch ? `branch ${t.branch}` : t.detachedAt ? `detached at ${t.detachedAt.slice(0, 12)}` : "a HEAD that could not be read";
+  if (t.disposition === "remove") return `extra worktree ${t.path} (${at}) is clean and would be removed; its branch and commits stay in ${t.repo}`;
+  if (t.disposition === "retain") return `extra worktree ${t.path} (${at}) would be re-homed to ${t.movedTo}: ${t.reason}`;
+  return `extra worktree ${t.path} (${at}): retire refuses, ${t.reason}`;
+}
 /** How many declared roots a retire plan's recovery note lists before `, and N more`. */
 const PLAN_NOT_COPIED_CAP = 16;
 /** Facts for Remove (retire): what retirement would touch, with the design's
@@ -178,12 +185,19 @@ export function planRetire(ctx, root, name, { home } = {}) {
   const target = targetFacts({ ...me, instance: name, depth: 0 });
   target.session = retireSessionFacts(me.home, target.session);
   const meta = readJson(join(me.home, "instance.json")) || {};
+  // The home's extra trees and what retire does with each: listed, and bound
+  // into the revision (below), so that an apply refuses as stale when a tree
+  // was created, removed, dirtied or cleaned, or its target was taken.
+  const extraWorktrees = extraWorktreePlan(me.home, me.root);
   const facts = { session: target.session, work: target.work, workMode: meta.work ?? null, repo: meta.repo ?? null, recordedBranch: meta.branch ?? null,
+    extraWorktrees,
     children: kids.map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, session: sessionFacts(c.home) })),
     ambiguous: (kids.ambiguous || []).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: c.reason })),
     pullRequest: "unknown" /* forge facts are the ADE's (P1); the kernel never claims 'no PR' */ };
   const defaults = { retainWorktree: meta.work === "worktree", deleteBranch: false, stopChildren: true, retainChildren: true };
-  const safety = [me.home, target.session.state, target.launched, facts.work.observed ? [facts.work.revision, facts.work.branch, facts.work.changed, facts.work.untracked] : null, kids.map((c) => c.home)];
+  const safety = [me.home, target.session.state, target.launched, facts.work.observed ? [facts.work.revision, facts.work.branch, facts.work.changed, facts.work.untracked] : null, kids.map((c) => c.home),
+    // Only when there are any: a home without extra trees keeps the revision it had.
+    ...(extraWorktrees.length ? [extraWorktrees] : [])];
   // What retire would preserve and where, read from the spawn baseline and the
   // work mode: nothing is hashed, and the plan revision does not depend on it.
   // The declared roots are listed as written, capped so one note stays short.
@@ -195,6 +209,7 @@ export function planRetire(ctx, root, name, { home } = {}) {
     notes: [
       ...(facts.work.observed && facts.work.drift ? [`the worktree is on ${facts.work.branch ?? (facts.work.detached ? "a detached HEAD" : "a ref OATS carries no branch name for")}, not the recorded ${facts.recordedBranch}`] : []),
       ...(facts.work.observed && facts.work.changed + facts.work.untracked > 0 ? [`${facts.work.changed} changed and ${facts.work.untracked} untracked file(s) would be retained with the worktree`] : []),
+      ...extraWorktrees.map(extraWorktreeNote),
       ...(kids.length ? [`${kids.length} recorded child instance(s) are stopped first (bounded SIGTERM, never escalated) and retained (their homes are not removed); a child still running after the grace refuses the retirement`] : []),
       ...((kids.ambiguous || []).length ? [`${kids.ambiguous.length} instance(s) record this name as parent but the name is not unique under this root; they are listed under ambiguous and NOT acted on`] : []),
       ...(target.session.note ? [target.session.established ? `session absent: ${target.session.note}; nothing needs quiescing` : `session not observably absent: ${target.session.note}; retire refuses until it is stopped`] : []),

package/lib/retire-output.mjs

@@ -1,6 +1,7 @@
 /** What `oats retire` says about the work it preserved. One function renders
  *  the lines for the local and the remote path of bin/oats.mjs, from the
- *  receipt's `workRecovery` (lib/core.mjs, retireInstance). A receipt from an
+ *  receipt's `workRecovery` (lib/core.mjs, retireInstance); another renders
+ *  its `extraWorktrees`. A receipt from an
  *  older kernel, or a stored one, may carry `workRecoveries[]` instead: one
  *  block is printed per entry. Dependency-free. */
 
@@ -48,3 +49,15 @@ export function workRecoveryLines(receipt, { host } = {}) {
   }
   return lines;
 }
+
+/** The lines `oats retire` prints for the home's extra trees it handled
+ *  (the receipt's `extraWorktrees`): one per tree, removed or re-homed. */
+export function extraWorktreeLines(receipt, { host } = {}) {
+  const rows = Array.isArray(receipt?.extraWorktrees) ? receipt.extraWorktrees : [];
+  return rows.map((t) => {
+    const at = t.branch ? `branch ${t.branch}` : t.detachedAt ? `detached at ${t.detachedAt}` : "a HEAD that could not be read";
+    return t.outcome === "removed"
+      ? `Extra worktree ${t.path} removed (${at}); its branch and commits stay in ${t.repo}${host ? ` on ${host}` : ""}`
+      : `Extra worktree ${t.path} re-homed${host ? ` on ${host}` : ""} to ${t.movedTo} (${at}): ${t.reason}`;
+  });
+}

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

@@ -783,8 +783,11 @@ function listSnapshotServers() {
  *  action authority. */
 /** The facts a remote row relays from the host's `status --json` row, as the
  *  host reported them; a fact the host does not supply is null, never
- *  derived here. */
-export const REMOTE_ROW_FACTS = ["identity", "identityAddress", "teams", "startedAt", "createdAt", "model", "runtimeState", "parentInstance", "siblingInstance", "relation", "relativeTo", "spawnOrigin"];
+ *  derived here. `work`, `repo`, `branch` and `modelFrom` are the host's own
+ *  record (`repo` is a path on the host, never read here); `soul` and `modules`
+ *  carry the host's drift observation against its own members and lock, not
+ *  recomputed here (#675). */
+export const REMOTE_ROW_FACTS = ["identity", "identityAddress", "teams", "startedAt", "createdAt", "model", "runtimeState", "parentInstance", "siblingInstance", "relation", "relativeTo", "spawnOrigin", "work", "repo", "branch", "modelFrom", "soul", "modules"];
 const rowFacts = (i = {}) => Object.fromEntries(REMOTE_ROW_FACTS.map((k) => [k, i[k] ?? null]));
 /** `waitingOnYou` (feature waiting-on-you) is relayed ONLY when the host's row has the
  *  key, so it is not one of REMOTE_ROW_FACTS: a host whose kernel predates the feature
@@ -1100,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");