@awebai/oats 0.27.1 → 0.28.0

package/docs/schedules.md

@@ -10,7 +10,7 @@ is `E_LOCAL_MISSING`. Scheduled spawns materialize exactly like `oats spawn`.
 Execution belongs to the host that holds the scope, so a schedule on a
 registered server keeps running while your laptop sleeps.
 
-There is no daemon. One host timer (a launchd user agent on macOS, a systemd
+[Triggers](#triggers) are evaluated by the same tick. There is no daemon. One host timer (a launchd user agent on macOS, a systemd
 user timer on Linux) runs `oats schedule tick --host` once a minute; the tick
 is a short-lived process that evaluates only the current minute, launches
 what is due through the same `spawn`, `session start` and `session input`
@@ -89,6 +89,104 @@ required IANA zone; both are evaluated by the croner library. `--wake-every
 N` at spawn time means `*/N * * * *`: every 7 fires at :00, :07, ... :56 and
 then :00 again, so 1, 5, 10, 15 and 30 give an even cadence.
 
+## Triggers
+
+A **trigger** (OATS 0.28.0, feature `triggers`) is an event-driven schedule:
+"when EVENT matches, spawn a NEW instance of SOUL with TASK, in TEAMS". It is
+stored in the same `oats-schedules.json` as a job of `kind: "trigger"`,
+managed with `oats trigger …` (never `oats schedule …`, which neither lists nor
+edits one), and evaluated by the same host tick (`oats schedule tick --host`,
+and `oats schedule tick` for one scope). There is no daemon and no webhook: it
+runs only on the host that holds the scope, with **that host's own
+credentials**; a definition carries none.
+
+**Credentials reach the tick through the host timer, not your shell.** The
+timer (a user LaunchAgent on macOS, a `systemd --user` unit on Linux) runs the
+tick with its own environment, which sets only `PATH` and `OATS_HOME_DIR`. `gh`
+logged in with the keyring or its config file under your HOME works there. A
+`GH_TOKEN` or `GITHUB_TOKEN` exported in your shell does not reach it.
+`oats trigger test` reports where `gh`'s credential comes from (`gh.credentialSource`:
+`keyring`, `config`, `env:<VAR>`) and warns when the timer cannot reach it.
+
+```json
+{ "id": "okf-harvest-review", "enabled": true, "kind": "trigger",
+  "on": { "source": "github.pull_request", "repo": "github.com/acme/knowledge",
+          "events": ["opened", "reopened", "ready_for_review"],
+          "labels": ["okf-harvest"], "base": "main", "poll": "2m" },
+  "spawn": { "soul": "oats.okf/knowledge-maintainer", "purpose": "review-pr-{number}",
+             "task": "Review knowledge-base PR {repo}#{number}. Load knowledge-review first.",
+             "teams": ["okf"], "harness": "claude", "model": "opus" },
+  "concurrency": { "max": 2, "perKey": 1 } }
+```
+
+- **Source** `github.pull_request` (the only one in v1): the tick polls the
+  repository's open pull requests with the host's `gh` (`gh api repos/<owner>/<repo>/pulls`,
+  `state=open`, most recently updated first) every `poll` (default `2m`, at
+  least `1m`). `labels` (all must be present) and `base` filter them. A repo is
+  `github.com/<owner>/<repo>`; another host is passed to `gh` as `--hostname`.
+- **Events** are inferred poll over poll: `opened` (a PR first seen, not a
+  draft; the first poll sees every open PR), `reopened` (seen closed, open
+  again), `ready_for_review` (was a draft), `labeled` (now carries the filter
+  labels it lacked; without a filter, any new label), `synchronize` (a new
+  head commit).
+- **Dedup and retry.** Each event has a key
+  `<trigger>:<repo>#<number>:<event>:<stamp>` (`created_at` for `opened`, the
+  head SHA for `synchronize`, `updated_at` otherwise). A key is recorded as
+  fired **only after a successful spawn**; until then the event stays pending
+  and is retried at every poll, and dropped when its PR closes.
+- **At least once, not exactly once.** The fired key is written after the
+  spawn returns. If the tick dies in between (a crash, a kill, the host going
+  down), the spawned instance exists but the key does not, and the next poll
+  spawns the event again. Concurrency still applies to that retry: with the
+  default `perKey: 1` the first instance is live, so the event is `held` rather
+  than spawned twice, and it fires once that instance retires. A trigger's soul
+  should therefore tolerate a second run on the same PR event (a review that
+  finds its own earlier review, for example).
+- **Concurrency.** `max` (default 1) bounds the live instances of the trigger,
+  `perKey` (default 1) those of one PR; both are counted from the homes'
+  `instance.json.trigger` records, so a retired instance frees its slot. An
+  event over the bound stays pending (`held`).
+- **The spawn** is `oats spawn` (the same path as a scheduled spawn). `soul` is
+  bare or qualified (`<package>/<soul>`). `purpose` (default
+  `{trigger}-{number}`, must render to a slug) and `task` are templated from
+  **only** `{repo} {number} {url} {event} {headSha} {trigger}`: a pull
+  request's title and body are untrusted and never reach the task (a template
+  naming any other field is refused). `teams` becomes the messaging
+  capability's `join=` setting (as `--provider <messaging cap> join=<labels>`).
+  `harness`, `model`, `yolo`, `backend` are as for schedules.
+- **The event reaches the instance** as `OATS_TRIGGER_EVENT_FILE`
+  (`<home>/.oats/trigger-event.json`: `{ trigger, source, repo, number, url,
+  event, headSha, labels, observedAt, key }`), given to the spawn hooks and the
+  harness; `instance.json.trigger` records `{ id, key, source, repo, number,
+  url, event, headSha, observedAt, eventFile }`. The task ends with a short
+  block naming the event file.
+- **State** lives in `<scope>/.agents/schedules/triggers.json` (last poll, the
+  PRs seen, pending events, fired keys, the last error).
+
+```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 list | show <id> | enable <id> | disable <id> | remove <id>
+oats trigger test <id>      # dry run: gh auth + credential source, repo + permissions (push/maintain/admin), the soul resolves,
+                            # its messaging capability, the teams declared, what WOULD fire now; spawns nothing
+oats trigger status [<id>]  # last poll, pending, fired keys, live instances, last error
+```
+
+All take `--dir` and `--json` (`triggerApi: 1`). `remove` leaves the instances
+it spawned running. `oats schedule list` does not list triggers, but it 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_BAD_ARGS`.
+
+**Package trigger templates.** A package may declare `triggers: [{ id, file }]`
+in `oats-package.json`. Each file is `{ parameters: { <name>: { path,
+required?, default?, description? } }, definition: { …a trigger… } }`.
+`oats trigger add --from <package>:<id>` reads it at the locked commit;
+`--set <name>=<value>` fills a parameter at its dotted `path` (a list value is
+comma-separated); a required parameter without a value is `E_BAD_ARGS
+{ missing }` naming it. The trigger records `template: { package, version,
+commit, template }`.
+
 ## Captured definitions (removed in 0.26)
 
 0.24–0.25 could save captured command definitions: `definitionVersion`,

package/docs/souls-and-instances.md

@@ -196,9 +196,13 @@ refused (`E_INSTANCE_NAME_TAKEN`).
 
 From a deployment (where `oats-local.yaml` is), a spawn: reads the local file →
 discovers the workspace over its remotes and confirms membership → finds the
-soul among the confirmed members (or `external:`; an ambiguous bare name is
-`E_SOUL_AMBIGUOUS` — say `<repo>/<soul>`) → fetches the soul's source into
-`<agents-root>/<soul>/souls/<commit12>/` at its commit (the home links that
+soul among the confirmed members, `external:` souls and the locked packages'
+souls (an ambiguous bare name is `E_SOUL_AMBIGUOUS`, naming each qualified
+form: `<member>/<soul>` or `<package>/<soul>`; a soul listed in
+`oats-local.yaml` `souls.disabled` is `E_SOUL_DISABLED`) → fetches the soul's
+source into `<agents-root>/<soul>/souls/<commit12>/` at its commit (a package
+soul at the locked commit, verified against the lock's digest — see
+[package souls](packages.md#package-souls); the home links that
 directory; `<agents-root>/<soul>/soul` points at the current one) → resolves
 every capability by
 `from:` (member = latest, package = locked) → creates the home →
@@ -302,6 +306,18 @@ uncertified capture retains the home for retry. Successful retirement enqueues
 evidence but never waits for a model or GitHub: independent processing and
 source-targeted inspection continue after the home disappears.
 
+Before any retire hook runs, retire preserves the instance's uncommitted and
+unmerged work: a verified recovery under `.oats-retirement/recovery/`, named in
+the summary. A worktree recovery is a standalone clone that carries the
+repository's local exclude rules (`info/exclude`, a configured
+`core.excludesFile`), its `info/attributes` and the settings that change what
+status reports (`core.fileMode`, `core.ignoreCase`, …), so its Git status
+matches the source's. A recovery that
+cannot be verified refuses with `E_WORK_PRESERVATION_FAILED` and keeps the
+home. **`--force` does not skip work preservation.** It forces only past a
+missing or unusable cleanup marker and past incomplete hook cleanup
+([capabilities.md](capabilities.md)).
+
 `oats retire <instance> --self` lets an instance retire itself when the human
 or briefing says it is done. A live harness cannot give a stable final
 inspection of its own work, so the calling process inspects, runs, and removes

package/docs/workspaces.md

@@ -60,7 +60,7 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
 
 packages:                                  # the ONLY versioned things
   oats.framework: v1.1.3                   # bare version → resolves through the official catalog
-  oats.okf: v2.1.5
+  oats.okf: v3.0.0
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
 teams:                                     # labels, declared once so they cannot drift
@@ -168,7 +168,7 @@ settings:                                  # host-owned values the manifests ask
     bindings-file: /Users/ana/.oats/okf-bindings.json
     state-dir: /Users/ana/.oats/okf
 souls:
-  disabled: [data-analyst]                 # not run on this machine
+  disabled: [data-analyst]                 # not run on this machine (E_SOUL_DISABLED); oats.okf/knowledge-harvester names a package soul
 ```
 
 See [configuration.md](configuration.md). `oats-config.yaml` no longer exists.
@@ -230,6 +230,12 @@ read; the soul gets no member-tier capabilities of its own repo; it is
 "source-complete" (its skills travel with it) and the workspace's defaults fill
 its slots. An `external[].team` overrides the soul's own `team`.
 
+**Package souls.** A package may ship souls (`souls:` in `oats-package.json`,
+0.28.0): they are listed from the lock for each package the workspace declares,
+named `<package>/<soul>` (a bare name when unique), resolved like any soul
+(`from: here` = their own package at the locked commit) and trusted as the
+package is. See [packages](packages.md#package-souls).
+
 ## Member tier vs package tier — the non-collapse rule
 
 A repository may be a **member** (it completed the handshake; its `souls/*` and

package/lib/core.mjs

@@ -1501,6 +1501,11 @@ export function stableSoulId({ soulId, home, soulDir, agentName } = {}) {
   return "";
 }
 export const workspaceSoulId = (repoKey, name) => `${repoKey}#${name}`;
+/** A triggered instance's event, inside its home's .oats/ (lib/triggers.mjs). */
+export const TRIGGER_EVENT_FILE = "trigger-event.json";
+/** A prepared soul entry's id: `<repoKey>#<name>` for a member or external soul, `package:<id>#<name>`
+ *  for a package soul (stable across the package's versions and independent of its repo). */
+const preparedSoulIdOf = (entry) => workspaceSoulId(typeof entry.package === "string" ? `package:${entry.package}` : entry.repoKey, entry.name);
 /** The soul directory an instance incarnates, as spawn recorded it (instance.json
  *  `soulDir`): a workspace soul's per-commit copy (agents/<soul>/souls/<commit12>) or
  *  the read-only soul inside a capability package. It is what every classic
@@ -1672,7 +1677,10 @@ function readSoul(agentDir, soulDir = soulOf(agentDir)) {
   }
   const soul = soulHarnessField(stripInternalAnnotations(parsed), p);
   soul._dir = agentDir;
-  soul.name = soul.name || basename(agentDir);
+  // A package soul homes at <package>--<soul> (lib/workspace.mjs packageSoulAgentName): that
+  // directory, not the soul.yaml name, is its agent name, so its instances never share a
+  // member soul's name or roster row.
+  soul.name = basename(agentDir).includes("--") ? basename(agentDir) : (soul.name || basename(agentDir));
   return soul;
 }
 export function findAgent(root, name) {
@@ -3270,14 +3278,22 @@ function* spawnBody(root, agent, o = {}) {
   // Capability lifecycle hooks (spawn) — the knowledge integration scaffolds instance
   // memory (STATE.md/log.md/notes/ are OKF conventions, not kernel ones); the
   // messaging integration mints the comms identity. Kernel stays memory-agnostic.
-  const preparedSoulId = o.prepared ? workspaceSoulId(o.prepared.soulEntry.repoKey, o.prepared.soulEntry.name) : undefined;
+  const preparedSoulId = o.prepared ? preparedSoulIdOf(o.prepared.soulEntry) : undefined;
+  // A trigger's event (lib/triggers.mjs): a private copy in the home, named to hooks and the harness
+  // as OATS_TRIGGER_EVENT_FILE. Its PR title/body are never in the task: the soul reads them from here.
+  let triggerEventFile = null;
+  if (o.triggerEvent && typeof o.triggerEvent === "object") {
+    triggerEventFile = join(home, ".oats", TRIGGER_EVENT_FILE);
+    mkdirSync(dirname(triggerEventFile), { recursive: true });
+    writeFileSync(triggerEventFile, JSON.stringify(o.triggerEvent, null, 2) + "\n", { mode: 0o600 });
+  }
   // Hooks read the soul the HOME links (the per-commit directory for a workspace
   // soul), never the swappable agents/<name>/soul pointer: a provider that pins a
   // path must pin this instance's content, and OATS_SOUL_ID is what it keys on.
   const hookRes = runLifecycleHooks("spawn", {
     home, instance, agentName: agent.name, soulDir: homeSoulTarget, soulId: preparedSoulId, contextDir: repoAbs,
     workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg,
-    extraEnv: { OATS_TASK: task, OATS_REPO: repoAbs, OATS_BRANCH: branch || "", OATS_WORK: work, OATS_HARNESS: harness, OATS_RUNTIME: harness, OATS_KIND: agent.kind || "persistent" },
+    extraEnv: { OATS_TASK: task, OATS_REPO: repoAbs, OATS_BRANCH: branch || "", OATS_WORK: work, OATS_HARNESS: harness, OATS_RUNTIME: harness, OATS_KIND: agent.kind || "persistent", ...(triggerEventFile ? { OATS_TRIGGER_EVENT_FILE: triggerEventFile } : {}) },
   });
   warnings.push(...hookRes.warnings);
   // Which capability hooks RAN (in order) and how each ended — recorded on the
@@ -3498,6 +3514,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       hooks: { launch: { ...hookRes.launch }, env: { ...hookRes.env }, contributions: hookRes.contributions || [] },
       prompt: LAUNCH_PROMPT,
     };
+    if (triggerEventFile) recipe.env.OATS_TRIGGER_EVENT_FILE = triggerEventFile;
     const cmdline = renderLaunchRecipe(recipe, { home, instance });
 
     // Module skills as materialize landed them (.agents/skills/<module>/<skill>/),
@@ -3514,6 +3531,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       relativeTo: relation ? relativeTo : undefined,
       spawnOrigin: relation || (parentInstance && parentInstance !== instance) ? "instance" : "operator",
       policy: { childSpawns: ownChildPolicy },
+      ...(triggerEventFile ? { trigger: { id: o.triggerEvent.trigger, key: o.triggerEvent.key ?? null, source: o.triggerEvent.source, repo: o.triggerEvent.repo, number: o.triggerEvent.number, url: o.triggerEvent.url ?? null, event: o.triggerEvent.event, headSha: o.triggerEvent.headSha ?? null, observedAt: o.triggerEvent.observedAt ?? null, eventFile: triggerEventFile } } : {}),
       // K6c: a decision-bound spawn records what bound it, so a retry with the
       // same key replays this receipt instead of spawning again.
       // The FULL bound decision (placement + effective), exactly as the fence
@@ -3582,7 +3600,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       try { const prior = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); if (prior.modules) meta.modules = prior.modules; if (prior.providers) meta.providers = prior.providers; } catch { /* materialize wrote it; absent means nothing to carry */ }
       // M5/3a: the workspace's name and the deployment directory are recorded, so a home
       // answers them (inspect/operation run --home, OATS_WORKSPACE_NAME) without discovery.
-      meta.workspace = { key: o.prepared.discovery?.key ?? null, name: o.prepared.discovery?.workspace?.name ?? null, deployment: o.prepared.deployment ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: workspaceSoulId(o.prepared.soulEntry.repoKey, o.prepared.soulEntry.name), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, team: o.prepared.soulEntry.team ?? null, labels: [...(o.prepared.soulEntry.labels ?? (o.prepared.soulEntry.team ? [o.prepared.soulEntry.team] : []))] }, layers: layerRows(o.prepared.resolution) };
+      meta.workspace = { key: o.prepared.discovery?.key ?? null, name: o.prepared.discovery?.workspace?.name ?? null, deployment: o.prepared.deployment ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: preparedSoulIdOf(o.prepared.soulEntry), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, team: o.prepared.soulEntry.team ?? null, labels: [...(o.prepared.soulEntry.labels ?? (o.prepared.soulEntry.team ? [o.prepared.soulEntry.team] : []))], ...(typeof o.prepared.soulEntry.package === "string" ? { name: o.prepared.soulEntry.name, qualifiedName: o.prepared.soulEntry.qualifiedName, package: { id: o.prepared.soulEntry.package, version: o.prepared.soulEntry.version, commit: o.prepared.soulEntry.commit, digest: o.prepared.soulEntry.digest, path: o.prepared.soulEntry.path } } : {}) }, layers: layerRows(o.prepared.resolution) };
       // Teams contract (decision 6): the eligible teams at spawn, recorded as EVIDENCE beside
       // `providers` (never inside that capability-keyed map). A home's hooks and operations get
       // the LIVE set (liveTeams); this is what they fall back to when discovery cannot answer.
@@ -4092,6 +4110,36 @@ function worktreeStatus(repo) {
   }
 }
 
+/** `git status --porcelain=v1 -z` as Map<path, XY>; a rename/copy row names its source (`R  ← old`). */
+function statusRows(z) {
+  const rows = new Map(), parts = z.split("\0");
+  for (let i = 0; i < parts.length; i++) {
+    const row = parts[i];
+    if (!row) continue;
+    const xy = row.slice(0, 2), path = row.slice(3);
+    rows.set(path, xy[0] === "R" || xy[0] === "C" ? `${xy} ← ${parts[++i]}` : xy);
+  }
+  return rows;
+}
+const STATUS_DISAGREEMENT_CAP = 10;
+/** Where two statuses disagree, by path: { rows: [{ path, source, recovery }] (null = absent; sorted, the
+ *  first `cap`), total }. What E_WORK_PRESERVATION_FAILED shows, so an operator sees `!! .scratch/` against
+ *  an absent row directly. */
+export function statusDisagreement(sourceStatus, recoveredStatus, cap = STATUS_DISAGREEMENT_CAP) {
+  const a = statusRows(sourceStatus), b = statusRows(recoveredStatus);
+  const paths = [...new Set([...a.keys(), ...b.keys()])].filter((p) => a.get(p) !== b.get(p)).sort();
+  return { rows: paths.slice(0, cap).map((path) => ({ path, source: a.get(path) ?? null, recovery: b.get(path) ?? null })), total: paths.length };
+}
+/** Refuse a recovery whose Git status is not the source's, naming the differing rows (capped). */
+function assertStatusAgrees(source, recovered, what, repo) {
+  const sourceStatus = worktreeStatus(source), recoveredStatus = worktreeStatus(recovered);
+  if (sourceStatus === recoveredStatus) return;
+  const diff = statusDisagreement(sourceStatus, recoveredStatus);
+  const shown = diff.rows.map((r) => `${r.path} (source ${r.source ?? "absent"}, recovery ${r.recovery ?? "absent"})`).join("; ");
+  const more = diff.total > diff.rows.length ? `; and ${diff.total - diff.rows.length} more` : "";
+  throw Object.assign(new Error(`${what}${shown ? `: ${shown}${more}` : ""}`), { statusDisagreement: { repo, ...diff } });
+}
+
 function generatedWorkFingerprint(work, status, disposableRoots = []) {
   const owned = (path) => disposableRoots.some((root) => path === root || path.startsWith(`${root}${sep}`));
   const paths = status.split("\0").filter(Boolean)
@@ -4971,6 +5019,64 @@ function restoreStandaloneGitState(sourceWork, recoveredRepo) {
   }
 }
 
+/** Give a recovery clone the source's effective exclude rules, so the status comparison sees the same
+ *  ignored paths. A fresh clone has neither the common dir's info/exclude nor a repository-configured
+ *  core.excludesFile, so a path excluded only there is `!!` in the source and `??` in the clone. Both are
+ *  written into the clone's own info/exclude (self-contained): core.excludesFile first, then
+ *  info/exclude, which keeps Git's precedence (a later pattern wins, and info/exclude outranks
+ *  core.excludesFile). → the sources carried, [{ kind, path }]. */
+function carryExcludes(sourceWork, recoveredRepo) {
+  const git = (...args) => execFileSync("git", ["-C", sourceWork, ...args], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim();
+  const carried = [], parts = [];
+  // A file with no pattern line (Git's template info/exclude is comments only) changes nothing: not carried.
+  const carry = (kind, file) => {
+    if (!existsSync(file)) return;
+    const text = readFileSync(file, "utf8");
+    if (!text.split("\n").some((line) => line.trim() && !line.startsWith("#"))) return;
+    parts.push(text); carried.push({ kind, path: file });
+  };
+  let excludesFile = "";
+  try { excludesFile = git("config", "--path", "--get", "core.excludesFile"); } catch { /* unset: Git's default applies to both repositories alike */ }
+  if (excludesFile) {
+    carry("core.excludesFile", resolve(git("rev-parse", "--show-toplevel"), excludesFile));
+  }
+  carry("info/exclude", join(git("rev-parse", "--path-format=absolute", "--git-common-dir"), "info", "exclude"));
+  if (!carried.length) return carried;
+  mkdirSync(join(recoveredRepo, ".git", "info"), { recursive: true });
+  writeFileSync(join(recoveredRepo, ".git", "info", "exclude"), parts.map((t) => (t.endsWith("\n") ? t : `${t}\n`)).join(""));
+  return carried;
+}
+
+/** Repository settings that change what `git status` reports for the same bytes and index. */
+const STATUS_CONFIG = ["core.fileMode", "core.ignoreCase", "core.precomposeUnicode", "core.symlinks", "core.autocrlf", "core.eol"];
+/** Give a recovery clone the source's status-affecting settings, so the status comparison judges the same
+ *  bytes the same way. A fresh clone probes its own core.fileMode/ignoreCase/… and lacks the common dir's
+ *  info/attributes, so e.g. core.fileMode=false with a mode-only change is clean in the source and ` M` in
+ *  the clone. Each key whose effective value differs is set (or, unset in the source, unset) in the
+ *  clone's local config; info/attributes is copied to the clone's (the same precedence). → what was
+ *  carried: [{ kind: "config", key, value } | { kind: "info/attributes", path }]. */
+function carryStatusConfig(sourceWork, recoveredRepo) {
+  const get = (repo, key) => {
+    try { return execFileSync("git", ["-C", repo, "config", "--get", key], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).replace(/\n$/, ""); }
+    catch (e) { if (e.status === 1) return null; throw e; }
+  };
+  const carried = [];
+  for (const key of STATUS_CONFIG) {
+    const value = get(sourceWork, key);
+    if (value === get(recoveredRepo, key)) continue;
+    execFileSync("git", ["-C", recoveredRepo, "config", "--local", ...(value === null ? ["--unset-all", key] : [key, value])], { stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER });
+    carried.push({ kind: "config", key, value });
+  }
+  const common = execFileSync("git", ["-C", sourceWork, "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: GIT_MAX_BUFFER }).trim();
+  const attributes = join(common, "info", "attributes");
+  if (existsSync(attributes)) {
+    mkdirSync(join(recoveredRepo, ".git", "info"), { recursive: true });
+    copyFileSync(attributes, join(recoveredRepo, ".git", "info", "attributes"));
+    carried.push({ kind: "info/attributes", path: attributes });
+  }
+  return carried;
+}
+
 function detachRecoveryClone(source, recovered) {
   let stash;
   try { stash = execFileSync("git", ["-C", source, "rev-parse", "--verify", "--quiet", "refs/stash"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER }).trim(); }
@@ -4989,6 +5095,7 @@ function detachRecoveryClone(source, recovered) {
 }
 
 function materializeNestedRepositories(sourceWork, recoveredRepo) {
+  const excludes = [], statusConfig = [];
   for (const source of nestedGitRoots(sourceWork)) {
     const rel = relative(sourceWork, source);
     const dest = join(recoveredRepo, rel);
@@ -4998,6 +5105,8 @@ function materializeNestedRepositories(sourceWork, recoveredRepo) {
     execFileSync("git", ["-C", dest, "checkout", "--quiet", head], { maxBuffer: GIT_MAX_BUFFER });
     detachRecoveryClone(source, dest);
     restoreStandaloneGitState(source, dest);
+    for (const c of carryExcludes(source, dest)) excludes.push({ repo: rel, ...c });
+    for (const c of carryStatusConfig(source, dest)) statusConfig.push({ repo: rel, ...c });
     for (const e of readdirSync(source, { withFileTypes: true })) {
       if (e.name === ".git") continue;
       const target = join(dest, e.name);
@@ -5005,8 +5114,9 @@ function materializeNestedRepositories(sourceWork, recoveredRepo) {
       copyTreeSafe(join(source, e.name), target);
     }
     if (existsSync(join(dest, ".git", "objects", "info", "alternates"))) throw new Error(`nested recovery ${rel} depends on object alternates`);
-    if (worktreeStatus(source) !== worktreeStatus(dest)) throw new Error(`nested recovery ${rel} Git state disagreed with source`);
+    assertStatusAgrees(source, dest, `nested recovery ${rel} Git state disagreed with source`, rel);
   }
+  return { excludes, statusConfig };
 }
 
 /** Bytes a path holds, never following a symlink (a link counts as its own entry). */
@@ -5061,7 +5171,7 @@ function preserveRetirementWork(observation, meta, instance) {
     if (fingerprintTree(observation.home, { excludeRoot: new Set(["work"]), instanceHome: true }) !== fingerprintTree(recoveredHome, { instanceHome: true })) {
       throw new Error("home recovery verification disagreed with the source");
     }
-    let branchDrift;
+    let branchDrift, excludes, statusConfig;
     if (!homeOnly && meta.work === "worktree" && meta.repo && meta.branch && (existsSync(observation.work) || observation.branchExists)) {
       const recoveredRepo = join(staging, "repo");
       // The branch is derived from the worktree while it exists: an instance
@@ -5080,18 +5190,21 @@ function preserveRetirementWork(observation, meta, instance) {
       detachRecoveryClone(sourceGitContext, recoveredRepo);
       if (existsSync(observation.work)) {
         restoreStandaloneGitState(observation.work, recoveredRepo);
+        excludes = carryExcludes(observation.work, recoveredRepo).map((c) => ({ repo: ".", ...c }));
+        statusConfig = carryStatusConfig(observation.work, recoveredRepo).map((c) => ({ repo: ".", ...c }));
         for (const e of readdirSync(observation.work, { withFileTypes: true })) {
           if (e.name === ".git") continue;
           const dest = join(recoveredRepo, e.name);
           rmSync(dest, { recursive: true, force: true });
           copyTreeSafe(join(observation.work, e.name), dest);
         }
-        materializeNestedRepositories(observation.work, recoveredRepo);
+        const nested = materializeNestedRepositories(observation.work, recoveredRepo);
+        excludes.push(...nested.excludes); statusConfig.push(...nested.statusConfig);
       }
       if (existsSync(join(recoveredRepo, ".git", "objects", "info", "alternates"))) throw new Error("recovery clone depends on object alternates");
       if (existsSync(observation.work)) {
         if (fingerprintTree(observation.work, { excludeRoot: new Set([".git"]), excludeGitMetadata: true }) !== fingerprintTree(recoveredRepo, { excludeRoot: new Set([".git"]), excludeGitMetadata: true })) throw new Error("worktree recovery verification disagreed with the source");
-        if (worktreeStatus(observation.work) !== worktreeStatus(recoveredRepo)) throw new Error("recovered Git index/status disagreed with the source");
+        assertStatusAgrees(observation.work, recoveredRepo, "recovered Git index/status disagreed with the source", ".");
       }
       const recoveredHead = execFileSync("git", ["-C", recoveredRepo, "rev-parse", "HEAD"], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
       const sourceHead = ref.branch === null ? ref.oid
@@ -5109,14 +5222,15 @@ function preserveRetirementWork(observation, meta, instance) {
     // What the copy cost: the untracked/ignored (or directory) outputs it carries, named.
     const workCopied = observation.directory ? !!observation.directoryFingerprint : !homeOnly && meta.work === "worktree" && existsSync(observation.work);
     const outputs = workCopied ? preservedOutputs(observation.work, observation.directory) : undefined;
-    writeFileSync(join(staging, "recovery.json"), JSON.stringify({ version: 1, instance, classes: observation.classes, sourceHome: observation.home, createdAt: new Date().toISOString(), ...(repoCopy ? { repoCopy } : {}), ...(branchDrift ? { branchDrift } : {}), ...(outputs ? { outputs } : {}) }, null, 2) + "\n", { mode: 0o600 });
+    writeFileSync(join(staging, "recovery.json"), JSON.stringify({ version: 1, instance, classes: observation.classes, sourceHome: observation.home, createdAt: new Date().toISOString(), ...(repoCopy ? { repoCopy } : {}), ...(branchDrift ? { branchDrift } : {}), ...(excludes?.length ? { excludes } : {}), ...(statusConfig?.length ? { statusConfig } : {}), ...(outputs ? { outputs } : {}) }, null, 2) + "\n", { mode: 0o600 });
     const bytes = treeBytes(staging);
     mkdirSync(dirname(recovery), { recursive: true });
     renameSync(staging, recovery);
     return { path: recovery, classes: observation.classes, bytes, ...(outputs ? { outputs } : {}), ...(repoCopy ? { repoCopy } : {}) };
   } catch (e) {
     rmSync(staging, { recursive: true, force: true });
-    throw oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${observation.home}; recovery could not be verified: ${e.message}`);
+    const details = e.statusDisagreement ? { home: observation.home, statusDisagreement: e.statusDisagreement } : undefined;
+    throw Object.assign(oatsError("E_WORK_PRESERVATION_FAILED", `retirement work remains at ${observation.home}; recovery could not be verified: ${e.message}`, details), details ? { details } : {});
   }
 }
 

package/lib/instance-inspect.mjs

@@ -15,7 +15,7 @@ import { accessSync, constants as fsConstants, existsSync, readFileSync, realpat
 import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { capabilityManifests, instanceSoulDir, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
-import { discoverOrStandalone, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
+import { agentDirOf, discoverOrStandalone, findSoulEntry, liveTeams, prepareInstance } from "./instance-resolution.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
 import { kernelCompatibility, teamLabelsOf, teamsOf } from "./resolve.mjs";
 import { loadLocal } from "./workspace.mjs";
@@ -94,7 +94,7 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
       // The derived deployment exactly — never an oats-local.yaml found further up.
       const found = loadLocal(deployment);
       if (real(dirname(found.path)) !== real(deployment)) throw Object.assign(new Error(`${deployment} has no oats-local.yaml`), { code: "E_HOME_MISMATCH" });
-      discovery = await discoverOrStandalone(found.local, { remoteOptions });
+      discovery = await discoverOrStandalone(found.local, { deployment, remoteOptions });
     }
     catch (e) { discoveryError = { code: e.code || "E_REMOTE_UNREADABLE", message: e.message }; }
   }
@@ -140,13 +140,13 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
   let discovery = prepared?.discovery ?? null, soulEntry = prepared?.soulEntry ?? null;
   if (!prepared) {
     // Still name the soul (and its member) when its resolution is refused.
-    discovery = await discoverOrStandalone(found.local, { remoteOptions });
+    discovery = await discoverOrStandalone(found.local, { deployment, remoteOptions });
     soulEntry = findSoulEntry(discovery, soul);
   }
   const res = prepared?.resolution;
   // A refused resolution still names its eligible teams: the labels and the workspace are known.
   const teams = res?.teams ?? teamsOf(discovery?.standalone === true ? null : discovery?.workspace ?? null, teamLabelsOf(soulEntry));
-  const cached = soulEntry?.commit ? join(deployment, "agents", soulEntry.name, "souls", String(soulEntry.commit).slice(0, 12)) : null;
+  const cached = soulEntry?.commit ? join(deployment, "agents", agentDirOf(soulEntry), "souls", String(soulEntry.commit).slice(0, 12)) : null;
   return {
     kind: "soul", home: null, meta: null, deployment, agentsRoot: join(deployment, "agents"), teams, teamsSource: "live",
     subject: { kind: "soul", soul: soulEntry.name, repoKey: soulEntry.repoKey ?? null, commit: soulEntry.commit ?? null, team: soulEntry.team ?? null },