@awebai/oats 0.27.0 → 0.27.2

package/docs/desktop-cli-api.md

@@ -953,6 +953,12 @@ location. The receipt says so:
   discarding the worktree (a checked-out branch cannot be deleted).
 - A failed move keeps the home and refuses `E_WORK_PRESERVATION_FAILED` —
   nothing is lost; retry or pass `--discard-worktree`.
+- When a recovery's Git status disagrees with the source's (0.27.2),
+  `E_WORK_PRESERVATION_FAILED` carries `details: {home, statusDisagreement:
+  {repo, rows: [{path, source, recovery}], total}}`. `repo` is `.` or a nested
+  repository's path. `source`/`recovery` are the porcelain `XY` codes, or
+  `null` where that side has no row. `rows` holds the first 10 paths, sorted,
+  and `total` counts all of them. The message names the same rows.
 - Non-worktree modes report `retention: null`. Quarantine/rollback paths keep
   their removal semantics.
 - A recovery (`workRecovery`, `workRecoveries[]`) is `{path, classes, bytes,

package/docs/packages.md

@@ -74,7 +74,7 @@ members:
 packages:
   oats.framework: v1.1.3
   oats.okf: v2.1.5
-  oats.aweb: v1.13.1
+  oats.aweb: v1.14.2
 teams:
   global: { description: Org-wide }
   engineering: { description: Platform }

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

@@ -0,0 +1,29 @@
+# OATS 0.27.1
+
+## Changed
+
+- **oats.aweb 1.14.2 is bundled and pinned** (was 1.13.1): **joining teams
+  beyond the personal one now works.** An instance joins the eligible teams it
+  is given at spawn (`--provider oats.aweb join=<labels>`) or later with
+  `oats aweb join <labels>` / the Desktop's Teams controls, and leaves with
+  `oats aweb leave <labels>`. Each joined team gets its own identity under the
+  instance home. Joined teams **poll** (their mail is read between tasks); live
+  receive for joined teams is planned for oats.aweb 1.15. Joining needs
+  **aw 1.36.12 or later** (older aw answers `E_TEAM_AW_FLOOR`; the primary
+  identity still mints). A leave removes the local identity only after aweb
+  confirms the membership is released, so a failed leave can be retried.
+  Retire leaves every joined team before releasing the primary identity.
+- The framework workspace (`oats-workspace.yaml`) pins oats.aweb v1.14.2.
+- Skip oats.aweb 1.14.0 and 1.14.1 (tagged, never pinned by an OATS release): their binding check answered a `teams` key that OATS rejects, so `oats readiness` showed messaging unknown; 1.14.2 fixes it, and 1.14.0's joins were refused by aw.
+
+## Known limitations
+
+- The bundled oats.okf is still 2.1.5: its harvest worker spawns with `--runtime`, so each harvest answers one `deprecated-runtime-name` warning on 0.27.x. It's harmless; oats.okf 2.1.6 passes `--harness`.
+
+- A per-workspace personal team still needs oats.aweb 1.15 (the aweb service
+  and CLI already carry personal enrollment); until then "personal" is the
+  person's active aweb team.
+
+## Upgrading from 0.27.0
+
+- To join teams: upgrade aw to 1.36.12 or later (and restart the host's wake daemon), then `oats sync` so the deployment's lock takes oats.aweb 1.14.2. Existing instances keep their primary identity; they join teams with `oats aweb join <labels>`.

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

@@ -0,0 +1,51 @@
+# OATS 0.27.2
+
+## Fixed
+
+- **Retiring a worktree instance whose repository excludes paths locally.**
+  Retire refused with `E_WORK_PRESERVATION_FAILED` ("recovered Git
+  index/status disagreed with the source") when the repository ignored a path
+  only through its local rules: the common Git directory's `info/exclude`, or
+  a `core.excludesFile` set in the repository's config. The recovery clone had
+  neither, so such a path was ignored (`!!`) in the source but untracked, or
+  absent for an empty directory, in the clone. Preservation runs before the
+  retire hooks and `--force` does not bypass it, so the instance could not be
+  retired and its identities were never revoked. The recovery now carries
+  those patterns into its own `.git/info/exclude` (nested repositories too),
+  and `recovery.json` lists them under `excludes`
+  (`[{ repo, kind, path }]`).
+  When a recovery's status still disagrees, the refusal now **names the
+  differing rows** from both sides, for example
+  `.scratch/ (source !!, recovery absent)`: the first 10, then
+  `; and N more`. Under `--json` they are in
+  `details.statusDisagreement` (`{repo, rows: [{path, source, recovery}],
+  total}`; see [desktop-cli-api.md](../desktop-cli-api.md)).
+  **On an older kernel:** remove the disposable paths that
+  `git -C <home>/work status --porcelain --ignored=matching` lists as `!!`
+  before retiring.
+
+- **Retiring a worktree instance whose repository changes how status reads
+  its files.** The recovery clone probed its own settings and lacked the
+  common Git directory's `info/attributes`. A repository with, for example,
+  `core.fileMode=false` and a mode-only change was clean in the source but
+  ` M` in the clone, so retire refused. The recovery now takes the source's
+  `core.fileMode`, `core.ignoreCase`, `core.precomposeUnicode`,
+  `core.symlinks`, `core.autocrlf` and `core.eol` (set, or unset where the
+  source leaves them unset) and its `info/attributes`, nested repositories
+  included. `recovery.json` lists them under `statusConfig`
+  (`[{ repo, kind: "config", key, value } | { repo, kind: "info/attributes", path }]`).
+
+## Known limitations
+
+- The bundled oats.okf is still 2.1.5 (its harvest answers one `deprecated-runtime-name` warning per spawn; harmless). oats.okf 2.1.6 follows in a later patch.
+
+- **A `core.attributesFile` or filter driver set in the repository's own
+  config is not carried** into a recovery. Merging its patterns would change
+  their precedence, and a pointer would tie the recovery to a host file. Such
+  a repository can still make retire refuse, and the refusal names the rows.
+  Workaround: commit or restore the files it re-reads before retiring.
+
+## Documentation
+
+- `oats retire --force` does **not** skip work preservation
+  ([souls-and-instances.md](../souls-and-instances.md#retire)).

package/docs/souls-and-instances.md

@@ -302,6 +302,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/lib/core.mjs

@@ -4092,6 +4092,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 +5001,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 +5077,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 +5087,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 +5096,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 +5153,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 +5172,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 +5204,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/package-catalog.json

@@ -8,7 +8,7 @@
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.13.1",
+      "ref": "v1.14.2",
       "path": "oats-package"
     },
     "oats.jira": {

package/package.json

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