@awebai/oats 0.25.3 → 0.25.5

package/capabilities/oats-aweb/bin/oats-aweb.mjs

@@ -39,7 +39,7 @@
 import { execFileSync } from "node:child_process";
 import { chmodSync, cpSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
-import { join, dirname, resolve, delimiter } from "node:path";
+import { join, dirname, resolve, delimiter, isAbsolute } from "node:path";
 import { loadCapturedAwebExecution, requireCapturedAwebAction } from "../lib/captured-execution.mjs";
 import { assessCapturedSessionReadiness, querySelectedKernel } from "../lib/session-readiness.mjs";
 import { runCapturedNative } from "../lib/captured-native.mjs";
@@ -50,9 +50,11 @@ import { parseBindingJson } from "../lib/binding-wire.mjs";
  * property of one helper staying correct forever, while argv removes the class.
  * This hook is a REQUIRED spawn hook, so it gates every spawn, which is reason
  * enough not to rely on quoting. */
-const run = (argv, cwd, timeout = 45000, { secrets = [], secretSafe = false } = {}) => {
+const run = (argv, cwd, timeout = 45000, { secrets = [], secretSafe = false, env: extraEnv, unsetEnv = [] } = {}) => {
   try {
-    return execFileSync(argv[0], argv.slice(1), { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout }).trim();
+    const childEnv = extraEnv || unsetEnv.length ? { ...process.env, ...(extraEnv || {}) } : undefined;
+    for (const name of unsetEnv) if (childEnv) delete childEnv[name];
+    return execFileSync(argv[0], argv.slice(1), { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout, ...(childEnv ? { env: childEnv } : {}) }).trim();
   } catch (e) {
     // execFileSync puts the WHOLE ARGV in e.message ("Command failed: aw team
     // join <token> …"). This hook's failures are reported by the kernel and land
@@ -113,6 +115,17 @@ const warn = (m) => out({ warning: `oats-aweb: ${String(m).slice(0, 300)}` });
  * nonzero so the kernel rolls the spawn back. `meta` carries whatever external
  * state already exists (e.g. a joined identity) so retire can undo it. */
 const fatal = (m, meta) => out({ ...(meta ? { meta } : {}), warning: `oats-aweb: ${String(m).slice(0, 300)}` }, 1);
+const parseAwJson = (text, what) => {
+  const trimmed = String(text ?? "").trim();
+  if (!trimmed) throw new Error(`${what} returned no JSON result`);
+  try { return JSON.parse(trimmed); } catch { /* may have progress before JSON */ }
+  const lines = trimmed.split(/\r?\n/);
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].trimStart().startsWith("{")) continue;
+    try { return JSON.parse(lines.slice(i).join("\n")); } catch { /* keep looking */ }
+  }
+  throw new Error(`${what} returned no JSON result`);
+};
 
 // Any selected snapshot enters the captured consumer BEFORE legacy settings,
 // root discovery or identity handling. Invalid-present never falls back.
@@ -150,6 +163,15 @@ const deliveryMode = (() => {
   const v = settings.delivery === undefined || settings.delivery === null || settings.delivery === "" ? "channel" : String(settings.delivery);
   return v === "session" ? "session" : "channel";
 })();
+const identitySettings = settings.identity && typeof settings.identity === "object" && !Array.isArray(settings.identity) ? settings.identity : {};
+const identityMode = identitySettings.mode === undefined || identitySettings.mode === null || identitySettings.mode === "" ? "local" : String(identitySettings.mode);
+if (!["local", "global"].includes(identityMode) && ["spawn", "retire"].includes(event)) fatal(`identity.mode must be either "local" or "global" (got ${JSON.stringify(identitySettings.mode)})`);
+const payloadTeam = () => {
+  const fromSettings = typeof settings.team === "string" && settings.team.trim() ? settings.team.trim() : undefined;
+  const fromEnv = process.env.OATS_TEAM_ID || process.env.OATS_TEAM_NAME || undefined;
+  return { team: fromSettings || fromEnv, payload: fromSettings, env: fromEnv };
+};
+const identityMeta = ({ mode = "local", alias, team, address = null, resident = null, grant }) => ({ mode, alias, team, address: address || null, resident: resident || null, ...(grant ? { grant } : {}) });
 
 /**
  * The aweb root (minting authority). BOUNDED candidates — the deployment's team
@@ -231,6 +253,126 @@ function wakeRegister(instanceHome, identityHome) {
 function wakeDeregister(instanceHome) {
   try { run(["aw", "wake", "deregister", "--home", instanceHome], instanceHome, 60000); return true; } catch { return false; }
 }
+const DEFAULT_GRANT_SCOPES = ["mail.read", "mail.send", "chat.read", "chat.send"];
+const residentKeyHint = (name) => `oats-local.yaml settings.oats.aweb.residents.${name || "<name>"}`;
+function resolveResidentCustody(name) {
+  if (!name) fatal(`identity.mode "global" requires identity.resident; set ${residentKeyHint("<name>")} to the absolute custody directory for that resident identity`);
+  const residents = settings.residents && typeof settings.residents === "object" && !Array.isArray(settings.residents) ? settings.residents : {};
+  const custody = residents[name];
+  if (typeof custody !== "string" || !isAbsolute(custody) || !existsSync(join(custody, ".aw", "identity.yaml"))) {
+    fatal(`identity.mode "global" resident ${JSON.stringify(name)} is not resolvable; set ${residentKeyHint(name)} to an absolute custody directory whose .aw/identity.yaml exists`);
+  }
+  return custody;
+}
+function grantShow(custody, grantId) {
+  const raw = run(["aw", "id", "grant", "show", grantId, "--json"], custody, 60000, { unsetEnv: ["AWEB_IDENTITY_HOME"] });
+  return parseAwJson(raw, "aw id grant show");
+}
+const revokeMaybeApplied = (error) => /may have applied|context deadline exceeded|timed out|timeout/i.test(String(error?.message || error));
+function revokeGrant(custody, grantId) {
+  try {
+    const raw = run(["aw", "id", "grant", "revoke", grantId, "--json"], custody, 60000, { unsetEnv: ["AWEB_IDENTITY_HOME"] });
+    return parseAwJson(raw, "aw id grant revoke");
+  } catch (e) {
+    if (revokeMaybeApplied(e)) {
+      try {
+        const shown = grantShow(custody, grantId);
+        const status = String(shown.status || shown.grant?.status || "").toLowerCase();
+        if (status === "revoked" || shown.revoked === true) return { grant_id: grantId, status: "revoked", verifiedByShow: true };
+      } catch { /* fall through to original revoke error */ }
+    }
+    throw e;
+  }
+}
+function recoverGrantHome(grantHome) {
+  try {
+    const text = readFileSync(join(grantHome, "grant.yaml"), "utf8");
+    const scalar = (key) => {
+      const m = text.match(new RegExp(`^\\s*${key}:\\s*["']?([^"'\\n#]+)["']?\\s*$`, "m"));
+      return m ? m[1].trim() : undefined;
+    };
+    return { grantId: scalar("grant_id"), team: scalar("team_id"), expiresAt: scalar("expires_at") };
+  } catch { return {}; }
+}
+function globalGrantSpawn() {
+  const { team, payload, env: envTeam } = payloadTeam();
+  if (!team) fatal("identity.mode \"global\" requires settings.oats.aweb.team (or OATS_TEAM_ID/OATS_TEAM_NAME) before minting a grant");
+  const resident = String(identitySettings.resident || "");
+  const custody = resolveResidentCustody(resident);
+  const grantHome = join(home, ".aweb-identity");
+  if (existsSync(grantHome)) fatal(`${grantHome} already exists; refusing to overwrite an existing aweb session grant home`);
+  const scopes = Array.isArray(identitySettings.scopes) && identitySettings.scopes.length ? identitySettings.scopes.map(String) : DEFAULT_GRANT_SCOPES;
+  const ttl = identitySettings.ttl === undefined || identitySettings.ttl === null || identitySettings.ttl === "" ? "8h" : String(identitySettings.ttl);
+  let meta;
+  const cleanup = () => { try { rmSync(grantHome, { recursive: true, force: true }); } catch { /* best effort */ } };
+  const failAfterMint = (message, code = 1) => { cleanup(); out({ ...(meta ? { meta } : {}), warning: `oats-aweb: ${String(message).slice(0, 300)}` }, code); };
+  try {
+    const raw = run(["aw", "id", "grant", "mint", "--scope", scopes.join(","), "--ttl", ttl, "--label", `oats:${instance}`, "--out", grantHome, "--json"], custody, 60000, { unsetEnv: ["AWEB_IDENTITY_HOME"] });
+    let minted;
+    try { minted = parseAwJson(raw, "aw id grant mint"); }
+    catch (parseError) {
+      const recovered = recoverGrantHome(grantHome);
+      if (recovered.grantId) {
+        meta = { delivery: deliveryMode, identity: identityMeta({ mode: "global", alias: resident, team: recovered.team || team, resident, grant: { id: recovered.grantId, expiresAt: recovered.expiresAt || "unknown", scopes } }) };
+        try { revokeGrant(custody, recovered.grantId); failAfterMint(`${parseError.message}; recovered grant ${recovered.grantId} from grant.yaml, revoked it, and removed the grant home`); }
+        catch (revokeError) { failAfterMint(`${parseError.message}; recovered grant ${recovered.grantId} from grant.yaml, but revoke failed: ${revokeError.message || revokeError}`); }
+      }
+      throw parseError;
+    }
+    const grantId = typeof minted.grant_id === "string" ? minted.grant_id : undefined;
+    const expiresAt = typeof minted.expires_at === "string" ? minted.expires_at : undefined;
+    const mintedTeam = typeof minted.team_id === "string" ? minted.team_id : undefined;
+    const mintedOut = typeof minted.out === "string" ? minted.out : undefined;
+    if (!grantId || !expiresAt || !mintedTeam || !mintedOut) throw new Error("aw id grant mint JSON lacked grant_id, expires_at, team_id, or out");
+    if (resolve(mintedOut) !== resolve(grantHome)) throw new Error(`aw id grant mint wrote ${mintedOut}, not ${grantHome}`);
+    const alias = typeof minted.alias === "string" && minted.alias ? minted.alias : resident;
+    const address = typeof minted.address === "string" && minted.address ? minted.address : null;
+    meta = { delivery: deliveryMode, identity: identityMeta({ mode: "global", alias, team: mintedTeam, address, resident, grant: { id: grantId, expiresAt, scopes } }) };
+    if (mintedTeam !== team) {
+      try { revokeGrant(custody, grantId); failAfterMint(`minted grant team ${mintedTeam} differs from ${team}; the grant was revoked and nothing was kept`); }
+      catch (e) { failAfterMint(`minted grant team ${mintedTeam} differs from ${team}; revoke failed: ${e.message || e}`); }
+    }
+    const launch = (process.env.OATS_RUNTIME || "") === "claude" && deliveryMode === "channel"
+      ? { claude: "--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace" }
+      : undefined;
+    const env = { ...(deliveryMode === "session" ? { AWEB_DELIVERY: "session" } : {}), AWEB_IDENTITY_HOME: grantHome };
+    if (deliveryMode === "session") {
+      try { wakeRegister(home, grantHome); }
+      catch (e) {
+        try { revokeGrant(custody, grantId); failAfterMint(`session delivery registration failed for minted grant ${grantId}: ${e.message || e}; grant revoked and grant home removed`); }
+        catch (revokeError) { failAfterMint(`session delivery registration failed for minted grant ${grantId}: ${e.message || e}; revoke failed: ${revokeError.message || revokeError}`); }
+      }
+    }
+    const warnings = [];
+    if (payload && envTeam && payload !== envTeam) warnings.push(`oats-aweb: settings.oats.aweb.team ${payload} differs from OATS team ${envTeam}; using payload team`);
+    const deliveryBrief = deliveryMode === "session"
+      ? ` Notification delivery: external (AWEB_DELIVERY=session): the host wake broker (aw wake) is registered for this home and nudges you when mail or chat arrives; the native aweb channel is not running. If you have waited long with nothing arriving, check \`aw mail inbox\` and \`aw chat pending\` yourself at task boundaries.`
+      : "";
+    out({
+      meta,
+      env,
+      brief: `Comms: you act as resident aweb identity "${alias}" on team ${mintedTeam} through a session grant for ${resident}; scopes: ${scopes.join(", ")}; expires: ${expiresAt}. Root keys are not in this home, and identity lifecycle commands are not yours to run.${deliveryBrief} Use \`aw mail\`/\`aw chat\` for messaging (see the aweb-messaging skill); coordination stays in your deployment's task layer.`,
+      ...(launch ? { launch } : {}),
+      ...(warnings.length ? { warning: warnings.join(" | ") } : {}),
+    });
+  } catch (e) {
+    if (meta?.identity?.grant?.id) { try { revokeGrant(custody, meta.identity.grant.id); } catch { /* retire compensation gets meta */ } cleanup(); }
+    fatal(`identity grant minting failed: ${e.message || e}`, meta);
+  }
+}
+function globalGrantRetire(meta) {
+  if (meta.delivery === "session") { if (!wakeDeregister(home)) process.stderr.write("oats-aweb: aw wake deregister failed; the broker treats a retired home as inactive on its own\n"); }
+  const id = meta.identity?.grant?.id;
+  if (!id) out({ meta: { retired: false, reason: "nothing-to-revoke" } });
+  const resident = meta.identity?.resident;
+  const custody = resolveResidentCustody(resident);
+  try {
+    revokeGrant(custody, id);
+    out({ meta: { retired: true, identityRevoked: true, grant: id } });
+  } catch (e) {
+    out({ meta: { retired: false, reason: "grant-revoke-failed", grant: id }, warning: `oats-aweb: grant ${id} was not revoked (${e.message || e}); it still expires at ${meta.identity?.grant?.expiresAt || "its TTL"}` }, 1);
+  }
+}
 const seatLockPath = (source) => join(dirname(source), ".aw-retained-seat.json");
 /** The alias a home's .aw/workspace.yaml records under memberships (indented),
  *  or undefined. Read only when the hook has no alias of its own. */
@@ -357,7 +499,7 @@ function retainedSeatSpawn(source, takeOver) {
     if (takenOver) warnings.push(`oats-aweb: took over the retained identity from ${takenOver} on identity.takeOver: true; if that runtime was still alive there are now two seats with one key — stop the old one`);
     if (hostNote) warnings.push(`oats-aweb: seated${hostNote}`);
     out({
-      meta: { team, alias, retained: true, source, lock: lockPath, delivery: deliveryMode, ...(takenOver ? { tookOverFrom: takenOver } : {}) },
+      meta: { team, alias, retained: true, source, lock: lockPath, delivery: deliveryMode, identity: identityMeta({ mode: "global", alias, team, address: shownAddress || expectedAddress || null }), ...(takenOver ? { tookOverFrom: takenOver } : {}) },
       ...(env ? { env } : {}),
       brief: `Comms: you are the retained seat of the existing aweb identity "${alias}" on team ${team} (same did and address as the seat you replace; its contacts, routes and conversations are yours).${deliveryBrief} Use \`aw mail\`/\`aw chat\` for messaging (see the aweb-messaging skill).`,
       ...(launch ? { launch } : {}),
@@ -370,7 +512,9 @@ function retainedSeatSpawn(source, takeOver) {
 }
 
 if (event === "spawn") {
-  if (settings.identity && typeof settings.identity === "object" && settings.identity.source) retainedSeatSpawn(String(settings.identity.source), settings.identity.takeOver === true);
+  if (identityMode === "global" && identitySettings.source) fatal('identity.mode "global" cannot be combined with identity.source; use identity.mode "local" with identity.source for a retained seat, or identity.mode "global" with identity.resident for a resident grant');
+  if (identityMode === "global") globalGrantSpawn();
+  if (identityMode === "local" && settings.identity && typeof settings.identity === "object" && settings.identity.source) retainedSeatSpawn(String(settings.identity.source), settings.identity.takeOver === true);
   let minted;                 // external identity, once `aw team join` succeeds
   const root = awebRoot();
   if (!root) fatal(`no initialized aweb root (.aw) among the bounded candidates (home, its git repo, context repo, workspace ${process.env.OATS_WORKSPACE || "?"}), so no identity could be minted and this instance would have no messaging — run \`oats aweb setup\` for guided onboarding`);
@@ -380,7 +524,9 @@ if (event === "spawn") {
     // team happens to be active at mint time — and verify the joined cert matches.
     // The instance name IS the discoverable alias (the team roster doubles as the
     // cross-machine instance directory).
-    let team = process.env.OATS_TEAM_ID || process.env.OATS_TEAM_NAME;
+    const resolvedTeam = payloadTeam();
+    let team = resolvedTeam.team;
+    const teamPayloadMismatch = resolvedTeam.payload && resolvedTeam.env && resolvedTeam.payload !== resolvedTeam.env;
     if (!team) team = JSON.parse(run(["aw", "team", "list", "--json"], root)).active_team;
     if (!team) fatal("cannot determine target team (no config team block, no active team at root), so no identity could be minted — set a team: block in oats-config.yaml, or activate a team at the aweb root");
     // A bare team name (no namespace) resolves against the root's memberships.
@@ -437,7 +583,7 @@ if (event === "spawn") {
     run(["aw", "init", "--do-not-touch-agents-md"], home);
     const alias = joined.alias;
     const mismatch = joined.team_id !== team
-      ? ` [WARNING: joined ${joined.team_id}, expected ${team}]` : "";
+      ? ` [WARNING: joined ${joined.team_id}, expected ${team}]` : teamPayloadMismatch ? ` [WARNING: settings team ${resolvedTeam.payload} differs from OATS team ${resolvedTeam.env}; using payload team]` : "";
     // Runtime integration: for Claude Code sessions the aweb-channel plugin
     // carries real-time push events. This hook does NOT install it. The plugin
     // is a DECLARED runtime requirement (oats.json), consented once at
@@ -458,11 +604,11 @@ if (event === "spawn") {
       ? ` Notification delivery: external (AWEB_DELIVERY=session): the host wake broker (aw wake) is registered for this home and nudges you when mail or chat arrives; the native aweb channel is not running. If you have waited long with nothing arriving, check \`aw mail inbox\` and \`aw chat pending\` yourself at task boundaries.`
       : "";
     out({
-      meta: { team: joined.team_id, alias, delivery: deliveryMode },
+      meta: { team: joined.team_id, alias, delivery: deliveryMode, identity: identityMeta({ mode: "local", alias, team: joined.team_id }) },
       ...(env ? { env } : {}),
       brief: `Comms: you have an aweb identity — alias "${alias}" on team ${joined.team_id}.${mismatch}${deliveryBrief} Use \`aw mail\`/\`aw chat\` for messaging (see the aweb-messaging skill); coordination stays in your deployment's task layer.`,
       ...(launch ? { launch } : {}),
-      ...(mismatch ? { warning: `oats-aweb: team mismatch — joined ${joined.team_id}, expected ${team}` } : channelWarning ? { warning: channelWarning } : {}),
+      ...(joined.team_id !== team ? { warning: `oats-aweb: team mismatch — joined ${joined.team_id}, expected ${team}` } : teamPayloadMismatch ? { warning: `oats-aweb: settings.oats.aweb.team ${resolvedTeam.payload} differs from OATS team ${resolvedTeam.env}; using payload team` } : channelWarning ? { warning: channelWarning } : {}),
     });
   } catch (e) {
     // A join may already have created a REMOTE identity before the failure.
@@ -480,6 +626,7 @@ if (event === "spawn") {
     if (meta.lock) { try { rmSync(meta.lock, { force: true }); } catch { /* the lock may already be gone */ } }
     out({ meta: { retired: true, retained: true, identityReleased: true, ...(meta.tookOverFrom ? { tookOverFrom: meta.tookOverFrom } : {}) }, warning: `oats-aweb: released the retained identity "${meta.alias}" (lock ${meta.lock || "?"} removed); the identity itself and ${meta.source || "its source"} are untouched${meta.tookOverFrom ? `; this seat had taken over from ${meta.tookOverFrom}` : ""}` });
   }
+  if (meta.identity?.mode === "global") globalGrantRetire(meta);
   // No alias means the spawn hook never reported an identity: nothing exists to
   // undo, which is completion. An alias WITH no local `.aw` is the opposite —
   // the remote record exists and its key is gone, so the self-delete cannot be

package/capabilities/oats-aweb/injects/aweb.md

@@ -4,6 +4,13 @@ Your messaging layer is **aweb**. You have (or will be minted) a team-scoped
 aweb identity — alias = your instance name — on your deployment's team (see
 `instance.json` / your TASK.md briefing for the team).
 
+Some instances serve a resident global identity through an expiring session
+grant instead of holding their own root keys. In that mode, your TASK.md and
+`instance.json` identify the resident alias, scopes, and expiry; root keys are
+not in your home, and mint/revoke/join/identity-lifecycle commands are not yours
+to run. If `aw mail` or `aw chat` says the grant expired or was revoked, stop
+messaging and report the condition to your coordinator/human.
+
 **Load the skills at the right moments — do not work from memory:**
 
 - **Before your first `aw mail`/`aw chat` of a session**, load the

package/capabilities/oats-aweb/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.aweb",
   "command": "aweb",
-  "version": "1.11.2",
+  "version": "1.12.0",
   "compatibility": {
     "oats": ">=0.24.4"
   },
@@ -124,7 +124,8 @@
     "retire": "bin/oats-aweb.mjs retire"
   },
   "environment": [
-    "AWEB_DELIVERY"
+    "AWEB_DELIVERY",
+    "AWEB_IDENTITY_HOME"
   ],
   "settings": {
     "delivery": {
@@ -134,6 +135,18 @@
         "session"
       ],
       "description": "channel: the native aweb channel packages wake the instance (default). session: delivery is external (AWEB_DELIVERY=session), no channel flag; the host wake broker registers the instance once it exists."
+    },
+    "team": {
+      "description": "Target aweb team id for identity lifecycle. In workspace v2 spawns this payload value wins over OATS_TEAM_ID/OATS_TEAM_NAME; if both are set and differ the hook warns and uses this setting."
+    },
+    "identity": {
+      "default": {
+        "mode": "local"
+      },
+      "description": "Identity selection. mode=local (default) mints an instance-local team identity or uses the existing identity.source retained-seat flow. mode=global acts as a named resident identity through a session grant; requires identity.resident and optional scopes/ttl."
+    },
+    "residents": {
+      "description": "Host-owned map for global mode: resident name to absolute custody directory whose .aw holds the resident root keys and team certificate. Put this only in oats-local.yaml settings.oats.aweb.residents; committed workspace or soul files must never carry custody paths."
     }
   },
   "environmentNamespaces": [

package/capabilities/oats-okf/bin/oats-okf.mjs

@@ -4,7 +4,7 @@ import { fs, join, dirname, resolve, readJSON, save, safePath, cliPath, oats, fa
 import { loadBindings, declaration, splitRef } from '../lib/config.mjs';
 import { register, registerCaptured, loadInvocationSourceReceipt, homeSource, loadSource, loadStatus, saveStatus, updateStatus, capture, scheduleSource, settleRetiredSchedule, service, markerPath, views } from '../lib/sources.mjs';
 import { runSource, complete, retry, readRun, requireQualifiedHelper } from '../lib/worker.mjs';
-import { initBase, migrate, deliverMigration, cutoverMigration, migrateSource } from '../lib/migration.mjs';
+import { initBase, migrate, deliverMigration, cutoverMigration, migrateSource, forgetMigration } from '../lib/migration.mjs';
 import { inspect } from '../lib/inspection.mjs';
 import { loadInvocationKnowledgeBinding } from '../lib/binding-wire.mjs';
 import { loadCapturedOkfInvocation, loadOkfSourceReceiptInput, assertOkfInvocationAction, requireOkfAdmittedAction, assertOkfSourceContext, assertOkfRegisteredSourceReplay } from '../lib/invocation-context.mjs';
@@ -20,6 +20,7 @@ oats okf init --base ALIAS --nodes FILE [--output PATH | --confirm] [--json]
 oats okf migrate --legacy PATH --base ALIAS --node NODE --output PATH [--json]
 oats okf migrate --deliver FILE | --cutover FILE --soul-dir PATH [--json]
 oats okf migrate --source-home PATH [--json]
+oats okf migrate --forget ID [--json]
 oats okf unlock --lock PATH --token TOKEN [--json]
 Captured workers use oats operation run knowledge:harvest with SOURCE --deployment/--resolution/--home,
 --arg native-request=ABS_BACKEND_ONLY_JSON and optional --arg worker-mode=prepare|launch.
@@ -167,6 +168,7 @@ else {
     } else if(event==='init') result=initBase(loadBindings(),flags.base,flags.nodes,flags.output,{confirm:!!flags.confirm});
     else if(event==='migrate') {
       if(flags['source-home']) result=migrateSource(loadBindings(),flags['source-home']);
+      else if(flags.forget) result=forgetMigration(loadBindings(),flags.forget);
       else if(flags.deliver) result=deliverMigration(resolve(flags.deliver));
       else if(flags.cutover) result=cutoverMigration(resolve(flags.cutover),flags['soul-dir']);
       else result=migrate(loadBindings(),{legacy:flags.legacy,alias:flags.base,node:flags.node,output:flags.output});

package/capabilities/oats-okf/lib/config.mjs

@@ -7,12 +7,16 @@ function keys(value, allowed, label, code='E_CONFIG') {
 }
 export function settings() {
   const s = JSON.parse(process.env.OATS_SETTINGS || '{}');
-  keys(s,['bindings-file','state-dir','harvest-runtime','harvest-model'],'OATS_SETTINGS');
+  keys(s,['bindings-file','state-dir','harvest-runtime','harvest-model','git-timeout'],'OATS_SETTINGS');
+  if(s['git-timeout']!==undefined && (!Number.isInteger(s['git-timeout']) || s['git-timeout']<1)) fail('E_CONFIG','git-timeout must be a positive integer number of seconds');
   if(s['state-dir']!==undefined && (typeof s['state-dir']!=='string' || !isAbsolute(s['state-dir']) || resolve(s['state-dir'])!==s['state-dir'])) fail('E_CONFIG','state-dir must be a normalized absolute path');
   if(s['harvest-runtime']!==undefined && !['pi','claude','codex'].includes(s['harvest-runtime'])) fail('E_CONFIG','invalid harvest-runtime');
   if(s['harvest-model']!==undefined && (typeof s['harvest-model']!=='string' || !s['harvest-model'].trim())) fail('E_CONFIG','harvest-model must be a nonempty string');
   return s;
 }
+/** Time budget for Git operations that talk to a remote (clone, fetch, push,
+ *  ls-remote). Local object reads keep the short exec default. */
+export function gitTimeoutMs() { return (settings()['git-timeout'] ?? 600)*1000; }
 export function noGit(path) {
   for (let p = safePath(path); ; p = dirname(p)) {
     if (fs.existsSync(join(p, '.git')) || (fs.existsSync(join(p, 'HEAD')) && fs.existsSync(join(p, 'objects')) && fs.existsSync(join(p, 'refs')))) fail('E_DIRECTORY_GIT', `directory store is in Git custody: ${p}; use kind git`);

package/capabilities/oats-okf/lib/io.mjs

@@ -70,7 +70,7 @@ export function unlock(path, token) {
   try { process.kill(o.pid, 0); fail('E_LOCKED', 'lock owner is still alive'); } catch (e) { if(e.code !== 'ESRCH') throw e; }
   fs.rmSync(path, { recursive: true }); syncDir(dirname(path)); return { unlocked: path };
 }
-export const identityKeys = ['OATS_INSTANCE','OATS_INSTANCE_HOME','OATS_HOME','PI_AGENT_HOME','PI_AGENT_NAME','PI_AGENT_INSTANCE','PI_AGENTS_ROOT','OATS_ROOT','OATS_SOUL','OATS_AGENT','OATS_KIND','OATS_EVENT','OATS_CONTEXT','OATS_REPO','OATS_WORK','OATS_BRANCH','OATS_META','OATS_SETTINGS','OATS_BINDING_FILE','OATS_SOURCE_RECEIPT_FILE','OATS_INVOCATION_CONTEXT_FILE','OATS_DEPLOYMENT','OATS_RESOLUTION'];
+export const identityKeys = ['OATS_INSTANCE','OATS_INSTANCE_HOME','OATS_HOME','PI_AGENT_HOME','PI_AGENT_NAME','PI_AGENT_INSTANCE','PI_AGENTS_ROOT','OATS_ROOT','OATS_SOUL','OATS_SOUL_ID','OATS_AGENT','OATS_KIND','OATS_EVENT','OATS_CONTEXT','OATS_REPO','OATS_WORK','OATS_BRANCH','OATS_META','OATS_SETTINGS','OATS_BINDING_FILE','OATS_SOURCE_RECEIPT_FILE','OATS_INVOCATION_CONTEXT_FILE','OATS_DEPLOYMENT','OATS_RESOLUTION'];
 export function cleanEnv(env = process.env) {
   return Object.fromEntries(Object.entries(env).filter(([k]) => !/^(OATS_(?!HOME_DIR$|PACKAGE_CATALOG$)|PI_AGENT|GIT_)/.test(k)));
 }

package/capabilities/oats-okf/lib/migration.mjs

@@ -30,10 +30,16 @@ export function migrate(bindings,{legacy,alias,node,output}) {
     if(paths.some(path=>overlaps(path,output))) fail('E_PATH','migration stage overlaps configured accepted base or coordination artifacts');
   }
   const original=tree(legacy);
+  // Stage the accepted base before any record exists: a base that cannot be
+  // read leaves nothing behind. From the record on, a failure is recorded in
+  // it rather than left as an unexplained directory.
+  const stage=stageBase(base,output);
   fs.mkdirSync(bindings.stateDir,{recursive:true,mode:0o700});
   const id=randomUUID();const dir=join(bindings.stateDir,'migrations',id);fs.mkdirSync(dir,{recursive:true,mode:0o700});
   save(join(dir,'legacy.json'),original); // byte-preserving backup BEFORE any delivery
-  const stage=stageBase(base,output); const spec=stage.meta.nodes[node];if(!spec) fail('E_OWNER','migration node must be explicitly provisioned first');
+  const recordFile=join(dir,'migration.json');
+  try {
+  const spec=stage.meta.nodes[node];if(!spec) fail('E_OWNER','migration node must be explicitly provisioned first');
   const prefix=spec.path+'/';
   if(Object.keys(stage.files).some(p=>p.startsWith(prefix) && ![prefix+'index.md',prefix+'log.md'].includes(p))) fail('E_MIGRATION','target node is not empty; merge migration requires human judgment');
   const after={...stage.files};for(const p of Object.keys(after)) if(p.startsWith(prefix)) delete after[p];
@@ -48,8 +54,23 @@ export function migrate(bindings,{legacy,alias,node,output}) {
   // Replace only the empty pre-provisioned node, not unrelated accepted bytes.
   fs.rmSync(join(stage.root,spec.path),{recursive:true});materialize(stage.root,after);validateBase(stage.root,base);
   const proposalFile=join(dir,'proposal.json');const proposal={version:1,run:id,created:new Date().toISOString(),file:proposalFile,before:stage.files,after};save(proposalFile,proposal);
-  const record={version:1,id,alias,node,base,owner:spec.owner,legacy,originalDigest:digest(original),stage:{root:stage.root,checkout:stage.checkout,head:stage.head},proposal:proposalFile,proposalHash:hash(proposal),receipt:{status:'staged'}};save(join(dir,'migration.json'),record);
-  return {status:'staged',migration:join(dir,'migration.json'),originalPreserved:true,stage:stage.root};
+  const record={version:1,id,alias,node,base,owner:spec.owner,legacy,originalDigest:digest(original),stage:{root:stage.root,checkout:stage.checkout,head:stage.head},proposal:proposalFile,proposalHash:hash(proposal),receipt:{status:'staged'}};save(recordFile,record);
+  return {status:'staged',migration:recordFile,originalPreserved:true,stage:stage.root};
+  } catch(e) {
+    save(recordFile,{version:1,id,alias,node,base,legacy,originalDigest:digest(original),receipt:{status:'failed',error:e.message,code:e.code||'E_MIGRATION',at:new Date().toISOString()}});
+    throw e;
+  }
+}
+/** Remove a migration record that never delivered anything (staged or failed).
+ *  The backup it holds is the legacy bundle, which still exists at its source;
+ *  a delivered record is custody and stays. */
+export function forgetMigration(bindings,id) {
+  identifier(id);const dir=join(bindings.stateDir,'migrations',id);const file=join(dir,'migration.json');
+  if(!fs.existsSync(dir)) fail('E_MIGRATION',`unknown migration ${id}`);
+  const status=fs.existsSync(file)?readJSON(file).receipt?.status:'incomplete';
+  if(!['failed','staged','incomplete'].includes(status)) fail('E_MIGRATION',`migration ${id} is ${status}: a delivered migration is custody and cannot be forgotten`);
+  fs.rmSync(dir,{recursive:true,force:true});
+  return {status:'forgotten',id,was:status};
 }
 export function deliverMigration(file) {
   safePath(file);const m=readJSON(file);const proposal=readJSON(m.proposal);if(hash(proposal)!==m.proposalHash) fail('E_MIGRATION','migration proposal changed');

package/capabilities/oats-okf/lib/sources.mjs

@@ -195,6 +195,7 @@ export function register(home) {
   const soul=fs.realpathSync(process.env.OATS_SOUL || join(home,'soul'));
   const work=fs.existsSync(join(home,'work'))?fs.realpathSync(join(home,'work')):join(home,'work');
   const decl=declaration(soul);
+  const soulId=process.env.OATS_SOUL_ID || null;
   const bindings=loadBindings(undefined,{sourceHome:home,sourceWork:work});
   const context=fs.realpathSync(process.env.OATS_CONTEXT || meta.repo || fail('E_CONFIG','source requires durable config context'));
   if(overlaps(home,context) && context.startsWith(home)) fail('E_PATH','config context cannot be in disposable home');
@@ -203,11 +204,7 @@ export function register(home) {
   if(!agent || !instance) fail('E_SOURCE','source instance/agent required');
   fs.mkdirSync(bindings.stateDir,{recursive:true,mode:0o700});
   const ownersFile=join(bindings.stateDir,'owners.json');
-  withLock(join(bindings.stateDir,'owners.lock'),()=>{
-    const owners=fs.existsSync(ownersFile)?readJSON(ownersFile):{};
-    if(Object.hasOwn(owners,decl.owner) && owners[decl.owner]!==soul) fail('E_OWNER','stable owner ID already identifies a different soul in this state namespace');
-    owners[decl.owner]=soul;save(ownersFile,owners);
-  });
+  pinOwner(ownersFile,decl.owner,{id:soulId,soulName:agent,path:soul});
   const id=randomUUID(); const dir=join(bindings.stateDir,'sources',id);
   // Copy only the role document, never instance.json wholesale, launch recipes,
   // environment, credentials, source worktree, or third-party message stores.
@@ -235,6 +232,24 @@ export function register(home) {
   }
   return finishRegistration({...source,file});
 }
+/** Pin a stable owner id to the soul it identifies. The kernel names a soul by
+ *  identity (OATS_SOUL_ID: repository key plus soul name) so the pin survives
+ *  the per-commit soul copies a workspace deployment materializes; a classic
+ *  soul keeps the resolved path. A row written by an earlier version as a path
+ *  under agents/<same soul name>/(soul|souls/<commit>) is rewritten to the
+ *  identity once; any other mismatch is a different soul and is refused. */
+export function pinOwner(ownersFile,owner,{id,soulName,path}) {
+  const value=id || path;
+  return withLock(join(dirname(ownersFile),'owners.lock'),()=>{
+    const owners=fs.existsSync(ownersFile)?readJSON(ownersFile):{};
+    if(!obj(owners)) fail('E_OWNER','invalid owner registry');
+    const prior=Object.hasOwn(owners,owner)?owners[owner]:undefined;
+    const samePath=typeof prior==='string' && new RegExp(`/agents/${soulName.replace(/[.*+?^${}()|[\]\\]/g,'\\$&')}/(soul|souls/[^/]+)$`).test(prior);
+    if(prior!==undefined && prior!==value && !(id && samePath)) fail('E_OWNER','stable owner ID already identifies a different soul in this state namespace');
+    if(prior!==value) {owners[owner]=value;save(ownersFile,owners);}
+    return value;
+  });
+}
 function enqueue(source,status,payload) {
   const id=hash(payload);const path=join(dirname(source.file),'inputs',`${id}.json`);
   if(!fs.existsSync(path)) save(path,payload);
@@ -246,19 +261,35 @@ export function input(source,id) {
   const value=readJSON(join(dirname(source.file),'inputs',`${id}.json`));
   if(hash(value)!==id) fail('E_INPUT','durable evidence hash mismatch');return value;
 }
-/** Switch a retired source's job off once nothing is pending. Idempotent; a
- *  scheduler failure is recorded, never thrown — the evidence is already safe. */
+/** Take a drained, retired source's job out of the kernel scheduler. The job is
+ *  first switched off, then removed: the definition it carried is kept as
+ *  evidence in this source's own schedule.json, so nothing about the run is
+ *  lost, and `oats schedule list` stops accumulating dead okf-<id> rows. A job
+ *  that is still running (or has unresolved effects) stays disabled and is
+ *  removed on the worker's next settle. Idempotent; a scheduler failure is
+ *  recorded, never thrown — the evidence is already safe. */
 export function settleRetiredSchedule(source) {
   const status=loadStatus(source);
-  if(status.schedule?.settled===true) return {status:'already-disabled',id:status.schedule.id};
+  if(status.schedule?.removed===true) return {status:'already-removed',id:status.schedule.id};
   if(!status.retired || status.auto || status.schedule?.id===undefined) return {status:'kept'};
+  const id=status.schedule.id;
+  const mark=(patch)=>updateStatus(source,current=>{current.schedule={...current.schedule,...patch};});
+  try {
+    if(status.schedule.settled!==true) {
+      oats(['schedule','disable',id,'--dir',source.context,'--json'],source.context);
+      mark({settled:true,settledAt:new Date().toISOString(),settleError:undefined});
+    }
+  } catch(e) {
+    if(e.code!=='E_SCHEDULE_UNKNOWN') {mark({settled:false,settleError:e.message});return {status:'disable-failed',id};}
+  }
   try {
-    oats(['schedule','disable',status.schedule.id,'--dir',source.context,'--json'],source.context);
-    updateStatus(source,current=>{current.schedule={...current.schedule,settled:true,settledAt:new Date().toISOString()};});
-    return {status:'disabled',id:status.schedule.id};
+    oats(['schedule','remove',id,'--dir',source.context,'--json'],source.context);
+    mark({removed:true,removedAt:new Date().toISOString(),removeError:undefined});
+    return {status:'removed',id};
   } catch(e) {
-    updateStatus(source,current=>{current.schedule={...current.schedule,settled:false,settleError:e.message};});
-    return {status:'disable-failed',id:status.schedule.id};
+    if(e.code==='E_SCHEDULE_UNKNOWN') {mark({removed:true,removedAt:new Date().toISOString(),removeError:undefined});return {status:'already-removed',id};}
+    mark({removed:false,removeError:e.message});
+    return {status:e.code==='E_SCHEDULE_RUNNING'?'disabled-pending-removal':'remove-failed',id};
   }
 }
 export function capture(source,{final=false,deadlineMs=85000}={}) {
@@ -336,8 +367,9 @@ export function capture(source,{final=false,deadlineMs=85000}={}) {
       if(final) {
         status.retired=true;status.retiredAt=new Date().toISOString();
         // A retired source whose every captured input is already processed has
-        // no further work: its schedule is switched off now (never deleted —
-        // the job definition stays as evidence). Anything still pending keeps
+        // no further work: its schedule is switched off and removed from the
+        // kernel scheduler (settleRetiredSchedule); the definition stays as
+        // evidence in this source's schedule.json. Anything still pending keeps
         // the job enabled until the worker drains it (see worker.mjs).
         const drained=status.captured.inputs.every(id=>status.processed.includes(id));
         status.auto=status.auto && !noLaunch && !drained;
@@ -349,10 +381,14 @@ export function capture(source,{final=false,deadlineMs=85000}={}) {
   });
 }
 export function scheduleSource(source) {
+  // A retired, drained source whose job was already taken out of the scheduler
+  // has nothing left to run: do not recreate the job (retire is re-entrant).
+  const current=loadStatus(source);
+  if(current.retired && current.schedule?.removed===true) return current.schedule.result;
   const captured=source.registration?.schemaVersion===1 && source.registration.kind==='captured';
   const argv=captured?['oats','okf','run-source','--source',source.file,'--deployment',source.executionBinding.deployment,'--resolution',source.executionBinding.resolution.id,'--json']
     :['oats','okf','run-source','--source',source.file,'--soul',source.agent,'--json'];
-  const spec={id:`okf-${source.id}`,kind:'command',enabled:loadStatus(source).auto,cron:source.bindings.cron,tz:source.bindings.tz,cwd:source.context,argv,
+  const spec={id:`okf-${source.id}`,kind:'command',enabled:current.auto,cron:source.bindings.cron,tz:source.bindings.tz,cwd:source.context,argv,
     ...(captured?{definitionVersion:2,recurrencePolicy:'capture',responsibleHuman:source.responsibleHuman}: {})};
   const file=join(dirname(source.file),'schedule.json');
   try {

package/capabilities/oats-okf/lib/stores.mjs

@@ -3,7 +3,7 @@ import { spawnSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { fs, join, dirname, safePath, readJSON, save, atomic, tree, materialize, digest, hash, withLock, exec, cleanEnv, fail, relPath, overlaps, resolve } from './io.mjs';
-import { metadata, noGit } from './config.mjs';
+import { metadata, noGit, gitTimeoutMs } from './config.mjs';
 const validator = fileURLToPath(new URL('../skills/okf/scripts/okf-validate.mjs', import.meta.url));
 // Never let local replace refs reinterpret frozen OIDs, including inside Git's
 // transport subprocesses. Override even an explicitly supplied command env.
@@ -17,11 +17,19 @@ export function validateBase(root, base) {
   if(result.errors.length || result.warnings.length) fail('E_VALIDATION', [...result.errors,...result.warnings].join('; '));
   return {files,meta,digest:digest(files)};
 }
-function rawBlob(cwd,oid) {
-  const result=spawnSync('git',['--no-replace-objects','-c','core.hooksPath=/dev/null','-C',cwd,'cat-file','blob',oid],{cwd,env:gitEnv(),timeout:30000,maxBuffer:16*1024*1024});
+/** Write a blob straight to a file descriptor: no in-memory buffer, so object
+ *  size never limits what a base may hold. The remote budget applies because a
+ *  partial clone fetches a missing blob on its first read. */
+function writeBlob(cwd,oid,target,mode) {
+  const fd=fs.openSync(target,'wx',mode);
+  let result; try { result=spawnSync('git',['--no-replace-objects','-c','core.hooksPath=/dev/null','-C',cwd,'cat-file','blob',oid],{cwd,env:gitEnv(),timeout:gitTimeoutMs(),stdio:['ignore',fd,'pipe']}); } finally { fs.closeSync(fd); }
   if(result.error || result.status!==0) fail('E_COMMAND','Git object read failed');
-  return result.stdout;
+  fs.chmodSync(target,mode);
 }
+/** A tree entry the store never materializes: outside the knowledge base root.
+ *  Its absence from a staging tree is by construction; its presence is a
+ *  worker's doing and is judged like any other change. */
+const outsideBase=(base,p)=>!(base.root==='.' || p===base.root || p.startsWith(base.root+'/'));
 function materializeGitObjects(base,dest,head) {
   immutableCommit(dest,head);
   const entries=gitTreeEntries(dest,head);
@@ -35,20 +43,32 @@ function materializeGitObjects(base,dest,head) {
   // Index/HEAD updates do not apply content filters. They preserve the normal
   // Git worktree needed by existing diff/publication guards without checkout.
   git(dest,['read-tree',head]);git(dest,['update-ref','--no-deref','HEAD',head]);
+  // Only the knowledge base is materialized: the index carries the whole tree
+  // for publication, but bytes outside the base root are never read, so the
+  // size of the rest of the repository does not matter. The scope checks know
+  // that an entry outside the root is expected to be absent (see outsideBase).
   for(const [p,entry] of entries) {
+    if(outsideBase(base,p)) continue;
     const target=safePath(join(dest,p));fs.mkdirSync(dirname(target),{recursive:true});
-    if(entry.mode==='160000') {fs.mkdirSync(target);continue;}
-    const bytes=rawBlob(dest,entry.oid);
-    if(entry.mode==='120000') fs.symlinkSync(bytes.toString('utf8'),target);
-    else {fs.writeFileSync(target,bytes,{flag:'wx',mode:entry.mode==='100755'?0o755:0o644});fs.chmodSync(target,entry.mode==='100755'?0o755:0o644);}
+    writeBlob(dest,entry.oid,target,entry.mode==='100755'?0o755:0o644);
   }
 }
 function clone(base, dest, selectedHead) {
   safePath(dest);
   if(fs.existsSync(dest)) fail('E_PATH',`staging destination exists: ${dest}`);
   fs.mkdirSync(dirname(dest),{recursive:true});
-  git(dirname(dest),['clone','--no-hardlinks','--no-checkout','--',base.repository,dest]);
-  git(dest,['fetch','origin',`refs/heads/${base.acceptedBranch}`]);
+  // Fetch only what the store reads: the accepted branch, trees now and blobs
+  // on demand. Only a remote that does not offer object filtering gets a plain
+  // single-branch clone instead; any other failure is the failure it is. The
+  // ancestry the publication checks walk is present either way.
+  const cloneArgs=['clone','--no-hardlinks','--no-checkout','--single-branch','--branch',base.acceptedBranch];
+  try { git(dirname(dest),[...cloneArgs,'--filter=blob:none','--',base.repository,dest],{timeout:gitTimeoutMs()}); }
+  catch(e) {
+    if(e.code!=='E_COMMAND' || !/filter/i.test(e.message)) throw e;
+    fs.rmSync(dest,{recursive:true,force:true});
+    git(dirname(dest),[...cloneArgs,'--',base.repository,dest],{timeout:gitTimeoutMs()});
+  }
+  git(dest,['fetch','origin',`refs/heads/${base.acceptedBranch}`],{timeout:gitTimeoutMs()});
   const head=selectedHead ?? git(dest,['rev-parse','FETCH_HEAD']);
   verifyRemote(base,dest);
   materializeGitObjects(base,dest,head);
@@ -142,7 +162,9 @@ function withVerificationIndex(cwd,fn) {
 }
 export function verifyGitScope(base, dest, baseline, { checkModes = true } = {}) {
   return withVerificationIndex(dest,read=>{
-    const names=read(['diff','--name-only','-z',baseline,'--']).split('\0').filter(Boolean);
+    // Entries outside the root are never materialized, so their absence is
+    // not a deletion; a present outside file that differs still is a change.
+    const names=read(['diff','--name-only','-z',baseline,'--']).split('\0').filter(Boolean).filter(p=>!(outsideBase(base,p) && !fs.existsSync(join(dest,p))));
     // A restored working file can conceal a staged, unauthorized index entry.
     names.push(...read(['diff','--cached','--name-only','-z',baseline,'--']).split('\0').filter(Boolean));
     names.push(...read(['ls-files','--others','--exclude-standard','-z']).split('\0').filter(Boolean));
@@ -303,7 +325,7 @@ export function gitPublish(base, stage, proposal, receipt, persist, {beforePubli
   const baseline=immutableCommit(cwd,stage.head);
   verifyPublicationTree(base,cwd,baseline.tree,baseline.tree,proposal.before);
   // Baseline must still be accepted. Never rebase model output without rejudging it.
-  git(cwd,['fetch','origin',`refs/heads/${base.acceptedBranch}`]);
+  git(cwd,['fetch','origin',`refs/heads/${base.acceptedBranch}`],{timeout:gitTimeoutMs()});
   const accepted=git(cwd,['rev-parse','FETCH_HEAD']);
   if(accepted!==stage.head) {
     // A known or uncertain previously created PR may be reconciled, but a
@@ -350,13 +372,13 @@ export function gitPublish(base, stage, proposal, receipt, persist, {beforePubli
   const publication=immutableCommit(cwd,receipt.commit);
   if(publication.parents.length!==1 || publication.parents[0]!==stage.head) fail('E_CONFIRM','publication commit must have exactly the frozen baseline as its parent');
   verifyPublicationTree(base,cwd,baseline.tree,publication.tree,proposal.after,proposal.before);
-  const remoteTip=()=>git(cwd,['ls-remote','--heads','origin',`refs/heads/${branch}`]).split(/\s/)[0] || null;
+  const remoteTip=()=>git(cwd,['ls-remote','--heads','origin',`refs/heads/${branch}`],{timeout:gitTimeoutMs()}).split(/\s/)[0] || null;
   let tip=remoteTip();
   if(tip && tip!==receipt.commit) fail('E_PR','publication branch has unexpected commit; never force push');
   if(tip!==receipt.commit) {
     beforePublish();
     receipt.status='push-intent'; persist();
-    try { verifyRemote(base,cwd);git(cwd,['push','--no-follow-tags','--recurse-submodules=no','origin',`${receipt.commit}:refs/heads/${branch}`]); }
+    try { verifyRemote(base,cwd);git(cwd,['push','--no-follow-tags','--recurse-submodules=no','origin',`${receipt.commit}:refs/heads/${branch}`],{timeout:gitTimeoutMs()}); }
     catch(e) { receipt.status='push-unknown'; receipt.error=e.message; persist(); throw e; }
     tip=remoteTip(); if(tip!==receipt.commit) {receipt.status='push-unknown';persist();fail('E_CONFIRM','pushed head not confirmed');}
   }
@@ -375,7 +397,7 @@ export function gitPublish(base, stage, proposal, receipt, persist, {beforePubli
   const pr=matching[0];receipt.pr=pr;receipt.status='delivered';receipt.deliveredAt ||= new Date().toISOString();persist();
   if(pr.state==='CLOSED' && !pr.mergedAt) {receipt.status='rejected';persist();fail('E_PR','PR closed without merge; retained proposal requires operator review');}
   if(pr.mergedAt) {
-    git(cwd,['fetch','origin',`refs/heads/${base.acceptedBranch}`]);
+    git(cwd,['fetch','origin',`refs/heads/${base.acceptedBranch}`],{timeout:gitTimeoutMs()});
     const merge=pr.mergeCommit?.oid;
     if(!merge) fail('E_CONFIRM','merged PR lacks merge commit');
     git(cwd,['merge-base','--is-ancestor',merge,'FETCH_HEAD']);

package/capabilities/oats-okf/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "2.1.3",
+  "version": "2.1.4",
   "compatibility": {
     "oats": ">=0.24.4"
   },
@@ -26,6 +26,9 @@
     },
     "state-dir": {
       "description": "Absolute host-owned durable state directory for portable bindings. It is never derived from an instance home."
+    },
+    "git-timeout": {
+      "description": "Seconds allowed for each Git operation that talks to a remote (clone, fetch, push, ls-remote); default 600. Local object reads keep a short fixed limit. Raise it for large repositories behind slow links."
     }
   },
   "agents": [

package/capabilities/oats-okf/skills/okf/SKILL.md

@@ -121,8 +121,9 @@ captured ProviderBinding as execution authority:
   `payload.bindings`. Workspace, adoption, and operator values remain separate
   inputs to the shared resolver; OKF does not select their precedence.
 - Durable placement is explicit selected settings: physical absolute
-  `bindings-file` and `state-dir`, plus selected `harvest-runtime` and optional
-  `harvest-model`. Never derive state from an instance home.
+  `bindings-file` and `state-dir`, plus selected `harvest-runtime`, optional
+  `harvest-model` and optional `git-timeout` (seconds for remote Git
+  operations, default 600). Never derive state from an instance home.
 - Provider codecs run only after exact retained executable approval. Their
   populated binding is not proof of readiness, enrollment, credentials, privacy
   or publication authority. Respect typed non-ready results.

package/docs/capabilities.md

@@ -262,6 +262,17 @@ return `meta`, `brief`, `warning`, or runtime-specific `launch` arguments. A
 **spawn hook only** may also return an `env` object for the launched process;
 returning `env` from retire or soul-scaffold is an explicit contract error.
 
+A **launch hook** runs at every start and restart of a home for each provider
+captured at spawn (under its captured settings). Its `launch` arguments and
+`env` replace that provider's previous contribution whole. Its `meta`, when
+returned, replaces that provider's entry in `instance.json.capabilityMeta`
+after the start succeeds — the same record the spawn hook wrote and the retire
+hook later reads as `OATS_META` — so a provider that re-issues a credential at
+start (a renewed session grant, for example) leaves the CURRENT one on record. A
+launch hook that answers without `meta` keeps its previous entry; a start whose
+preparation fails changes nothing. (Kernel ≥ 0.25.5; earlier kernels collected
+launch `meta` and discarded it.)
+
 Hook environment values are strings, at most 8192 UTF-8 bytes, with no NUL or
 newlines. Names use the portable environment grammar and must belong to an
 unambiguous vendor namespace. Only a dotted capability ID participates: its

package/docs/design/2026-09-20-redesign-program-board.md

@@ -2,7 +2,7 @@
 
 **Purpose:** the one accurate view of every work stream in the redesign, what is on main, what is in flight, who owns it, and what blocks it. Lead: `oats-expert` (redesign lead). Updated whenever anything merges, is returned, or reality changes. Older per-lane boards are superseded by this file.
 
-**Last update:** 2026-09-23 20:00Z · **0.25.0 + 0.25.1 + 0.25.2 PUBLISHED** (workspace model A–C + team-review fixes + operator-rebuild round) · Phase D plan next · **Desktop engineer paused by the human** (10B-0 uncommitted foundation preserved; resume is the human's call; 0.24.14 to be cut from a maintenance branch off `e5cdaf95` when its PR lands) · parity pipeline ⏸.
+**Last update:** 2026-09-23 20:00Z · **0.25.0–0.25.4 PUBLISHED** (workspace model A–C; team-review fixes; operator-rebuild round; OATS_SOUL_ID; quarantine-retry fix) · **OKF 2.1.4 content complete on oats-okf main, tag pending human GO** · **oats.aweb 1.12.0 (PR #107) in rehearsal round 4; decision 27 (per-spawn identity) proposed to the human** · Phase D plan next · **Desktop engineer paused by the human** (10B-0 uncommitted foundation preserved; resume is the human's call; 0.24.14 to be cut from a maintenance branch off `e5cdaf95` when its PR lands) · parity pipeline ⏸.
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 

package/docs/design/2026-09-23-workspace-module-contracts.md

@@ -565,6 +565,18 @@ is a member; a soul that lives in it may need a work clone). Under an explicit
 `oats-local.yaml` `standalone:` header the next steps say the view is standalone
 and list only that repo.
 
+### 0.25.5 — launch-hook `meta` is persisted
+
+`runLifecycleHooks("launch")` collected each capability's `meta` and the
+start/restart path discarded it (only `contributions` and `env` were consumed).
+From 0.25.5 a successful start merges `res.meta` per capability into
+`instance.json.capabilityMeta` — the record spawn writes and retire reads as
+`OATS_META`. A hook answering without `meta` keeps its prior entry; a failed
+launch preparation writes nothing. No new field, flag or hook event; this is
+the documented hook return finally honoured (decision 27, K3′). Driver: a
+provider renewing a session grant at every start would otherwise leave the
+original grant id on record and retire would revoke the wrong grant.
+
 ### 0.25.3 — `OATS_SOUL_ID` (stable soul identity for providers)
 
 The per-commit soul cache (0.25.1, M1) made `realpath(<home>/soul)` change with every

package/docs/integrations.md

@@ -85,10 +85,11 @@ can spawn. `owns`/`reads` are responsibility/context, not ACLs. See
 [knowledge](knowledge.md) for the **prepared** version scope, provisioning and
 commands, and [migration](knowledge-migration.md) before updating v1.
 
-**`oats.aweb`** fills `messaging`: mints an instance identity at spawn,
-removes it at retire, contributes the aweb messaging and team skills, wires
-the channel plugin so sessions are woken by mail, and exposes
-`oats aweb roster` and `oats aweb setup`. Requires the `aw` CLI.
+**`oats.aweb`** fills `messaging`: mints an instance identity at spawn (local
+mode) or grants an instance an expiring session as a resident global identity
+(global mode), removes or revokes it at retire, contributes the aweb messaging
+and team skills, wires the channel plugin so sessions are woken by mail, and
+exposes `oats aweb roster` and `oats aweb setup`. Requires the `aw` CLI.
 
 **`oats.jira`** fills `tasks`: the `jira-tasks` protocol and an advisory
 spawn hook. Requires `acli`; settings commonly include `site` and `project`.
@@ -135,6 +136,9 @@ remove it on `retire`; supply the roster; teach send, reply, chat, and "read
 the event first" in the inject and skill; contribute launch arguments so the
 session is woken; enforce the soul type's `reach` on both sides; state
 whether the address outlives the instance; and keep task coordination out.
+Any messaging provider emits `identity: { mode, alias, team, address|null,
+resident|null, grant?: { id, expiresAt, scopes } }` in its spawn meta;
+`oats.aweb` is the reference implementation.
 
 **Tasks.** Teach claim, update, block, hand off, and complete; identify the
 instance to the tracker in a way that survives it; keep conversation out.
@@ -197,12 +201,57 @@ warning naming the fresh-purpose remedy. On an older `aw` the pre-1.36.1
 report stands (`aliasReusable: false`, warning naming aweb-abim), because
 that CLI cannot revoke the certificate.
 
-## oats.aweb settings (1.10.0)
+## oats.aweb settings (1.12.0)
 
 Set in `oats-local.yaml` under `settings.oats.aweb.<key>` (host-owned), in the
 soul's `messaging:` payload (true of every instance), or per spawn with
-`oats spawn … --provider oats.aweb <key>=<value>`.
-
+`oats spawn … --provider oats.aweb <key>=<value>`. The effective payload is
+merged in order: workspace messaging, `byTeam[team]`, soul messaging,
+`oats-local.yaml` `settings.oats.aweb`, then per-spawn `--provider` values.
+`residents` is host-file-only: put custody paths only in `oats-local.yaml`,
+never in a committed workspace or soul file (current kernels document this rule
+but do not yet enforce provenance in the hook payload).
+
+- `team: <team id>`. The payload team wins over `OATS_TEAM_ID`/
+  `OATS_TEAM_NAME`; if both are set and differ, the hook warns and uses the
+  payload. Workspace v2 spawns can have an empty `OATS_TEAM_ID`, so set this in
+  the payload for global grants.
+- `identity.mode: local | global` (default `local`). Any other value is fatal.
+  Local mode is the historical behavior: a spawned team identity is minted for
+  the instance, or `identity.source` uses the existing retained-seat flow below.
+  Its spawn meta includes `identity: { mode: "local", alias, team, address:
+  null, resident: null }` beside the existing top-level `alias`, `team`, and
+  `delivery` keys.
+- `identity.mode: global` makes the instance act as a resident global identity
+  through an aweb session grant; it never mints a new global identity and never
+  copies root keys into the instance home. `identity.resident` is required and
+  resolves through `residents.<name>` to an absolute custody directory whose
+  `.aw/identity.yaml` already exists. Missing or unresolved residents fail with
+  the `oats-local.yaml settings.oats.aweb.residents.<name>` key to set. Optional
+  `identity.scopes` defaults to exactly `[mail.read, mail.send, chat.read,
+  chat.send]`; optional `identity.ttl` defaults to `8h` (aw accepts `60s` to
+  `720h`). Spawn runs `aw id grant mint --scope <comma-list> --ttl <ttl>
+  --label oats:<instance> --out <home>/.aweb-identity --json` from the custody
+  directory with `AWEB_IDENTITY_HOME` removed from the child environment: in aw
+  1.36.1, grant commands are not identity-home-aware and intentionally refuse
+  both `--identity-home` and external `AWEB_IDENTITY_HOME`, so cwd selects the
+  custody identity. The hook parses the whole JSON document because aw `--json`
+  output is indented across lines, with a fallback to the first brace-prefixed
+  block when progress lines precede it; it then verifies the minted grant's
+  `team_id` and returns
+  `env.AWEB_IDENTITY_HOME=<home>/.aweb-identity`. If the minted team differs,
+  the hook revokes the grant and keeps nothing. As of aw 1.36.1, receiving,
+  wake registration and `aw whoami` work through a grant, but sending mail or
+  chat through a grant is rejected by the server with 422 (`from_did must match
+  the authenticated sender`) because the aw client signs with the grant-key DID
+  where the server expects the resident's. Retire revokes
+  `meta.identity.grant.id` through the custody directory; with no grant id it
+  reports `nothing-to-revoke`. A failed revoke exits nonzero and reports the TTL
+  expiry.
+- `residents: { <name>: /abs/custody/dir }` is the host-owned map for global
+  mode. Each custody directory's `.aw` holds the resident identity root keys and
+  team certificate. Do not put this map in committed source; the hook cannot
+  distinguish payload provenance.
 - `delivery: channel | session` (default `channel`). `session` hands
   notification delivery to the host wake broker: `AWEB_DELIVERY=session` in
   the launch environment (declared by the manifest), no Claude channel flag,

package/docs/rebuild-to-v2.md

@@ -48,8 +48,9 @@ capabilities plus `oats.core`), so a public soul stays usable.
 Two teams that need two different messaging identities (an open-source team
 and a hosted-operations team, say) stay in ONE workspace: `team:` is a label,
 and the provider payload is addressed by label under `messaging.byTeam` (§2).
-Read §8b before relying on it: the kernel merges `byTeam`, but oats.aweb 1.11.2
-does not yet read the `team` it delivers.
+Read §8b before relying on it: oats.aweb 1.12.0 mints into the `team` the
+payload names, but the `.aw` root it mints FROM is still found by search and
+must hold that team's membership (1.11.2 ignored `team` altogether).
 
 ## 2. Write `oats-workspace.yaml` v2 in the host repo
 
@@ -76,8 +77,8 @@ members:
   - git:github.com/acme/platform
 packages:
   oats.framework: v1.1.3
-  oats.okf: v2.1.3
-  oats.aweb: v1.11.2
+  oats.okf: v2.1.4
+  oats.aweb: v1.12.0
 teams:
   global: { description: Org-wide }
   engineering: { description: Platform }
@@ -136,7 +137,7 @@ they enumerate `souls/*/soul.yaml`. A soul left under `agents/` is invisible to
 | 0.24 | v2 |
 |---|---|
 | `schemaVersion: 1` | `schemaVersion: 2` |
-| `requires.knowledge: { capability: oats.okf, source: git:…@v2.1.3#oats-package }` | `capabilities: { oats.okf: { from: package } }` — or nothing, if the workspace default already says so |
+| `requires.knowledge: { capability: oats.okf, source: git:…@v2.1.4#oats-package }` | `capabilities: { oats.okf: { from: package } }` — or nothing, if the workspace default already says so |
 | `requires.capabilities.<cap>: { source: git:… }` | `<cap>: { from: package }` (published) or `<cap>: { from: here }` / `{ from: <repo key> }` (a member capability) |
 | `source: repo:…` / `path:` | `{ from: here }` |
 | `defaults.capabilities` | fold into `capabilities:`; use `off` to remove a workspace default |
@@ -217,8 +218,8 @@ messaging identity per team (§1), a soul that loses its label silently lands
 outside every team-addressed payload; nothing refuses it. Label the membership
 when a whole repo belongs to one team, and the soul when it does not.
 
-**Per-soul memory-harvest opt-out:** not available in OKF 2.1.3 — an OKF 2.1.4
-item. Neither `okf.json` (`version`, `owner`, `owns`, `reads`) nor the settings
+**Per-soul memory-harvest opt-out:** not available in OKF 2.1.3 or 2.1.4 — a
+later OKF item. Neither `okf.json` (`version`, `owner`, `owns`, `reads`) nor the settings
 payload (`bindings-file`, `state-dir`, `harvest-runtime`, `harvest-model`) has a
 key that keeps a soul registered for reads while excluding it from harvest. A
 soul that must not be harvested today says `knowledge: none` (no OKF at all for
@@ -327,7 +328,7 @@ Member capabilities need no approval: membership is the trust.
 **Non-interactive approval (CI, scripted rebuilds):**
 
 ```bash
-oats sync --approve oats.okf@v2.1.3 --approve oats.aweb@v1.11.2
+oats sync --approve oats.okf@v2.1.4 --approve oats.aweb@v1.12.0
 ```
 
 `--approve <id>@<version>` is repeatable and approves **exactly** the entry the
@@ -337,6 +338,13 @@ type a digest. An `--approve` that names an id or version the resolution does
 not contain is an error, not a silent skip; an entry the flags do not cover
 stays unapproved (exit `2`, as above).
 
+`<version>` is the value `sync --json` reports as `approvalNeeded[].version`,
+which is what the lock records as the package's `version`. For a **catalog**
+package that is the published version (`oats.okf@2.1.4`). For a **git** source
+pinned by commit (`git:github.com/awebai/oats-okf@<oid>`) it is the **full
+commit OID**, not the `git:` reference and not a tag name — copy it from the
+`approvalNeeded` line rather than from your workspace file.
+
 ## 7b. OKF 2: start a FRESH `state-dir` — do not re-point the old one
 
 OKF 2 pins each knowledge **owner** to a soul by path: at source registration
@@ -398,11 +406,11 @@ machine-level setting would give the seat to EVERY instance of every messaging
 soul on that machine, and a seat can be held once. The Desktop's
 confirmed apply carries the same map.
 
-## 8b. Where the team `.aw` lives now (oats.aweb 1.11.2), and what `byTeam` does today
+## 8b. Where the team `.aw` lives now, and what `byTeam` does today
 
 A freshly minted identity (every spawn without `identity.source`) needs an
 **initialised aweb root**: a directory holding `.aw` with a team membership to
-mint into. oats.aweb 1.11.2's spawn hook looks for `.aw` among these, first hit
+mint into. oats.aweb's spawn hook (1.11.2 and 1.12.0 alike) looks for `.aw` among these, first hit
 wins: the declared team scope (`OATS_TEAM_SCOPE`, from the removed
 `oats-config.yaml` `team:` block — **empty under v2**), the instance home, the
 git repo containing the home, the resolution context (the soul's work repo) and

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

@@ -0,0 +1,21 @@
+# OATS 0.25.4
+
+Patch release: one kernel fix found by an operator rehearsal on 0.25.3.
+
+## Fixed
+
+- **Quarantine retry never re-ran the owed retire hook on a workspace-mode
+  home.** When a required spawn hook fails and its compensation is incomplete,
+  the kernel retains the home with a cleanup descriptor
+  (`.oats-rollback-incomplete.json`). Module materialization had already
+  written a pre-hook `instance.json` stub (`{ modules, providers,
+  resolutionRevision }`), and `oats retire` trusted that stub over the
+  descriptor — so `meta.repo` was undefined, the retry reported *"retire hook
+  <cap>: did not run on this retry"* and *"cleanup descriptor lost its context
+  repo"* on every attempt, and only `--force` could remove the home (leaving
+  the provider's external state to be cleaned by hand). The retry now reads
+  the cleanup descriptor whenever the live record is not a complete spawn
+  record; the owed hook runs, the home stays while it fails, and is removed
+  once it succeeds. Regression test in `test/spawn-workspace.test.mjs`.
+
+No contract changes. `oats version --json` is unchanged apart from the version.

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

@@ -0,0 +1,42 @@
+# OATS 0.25.5
+
+Patch release: one lifecycle-contract defect fixed; two provider releases
+pinned in the official catalog.
+
+## Fixed
+
+- **Launch-hook `meta` was collected and discarded.** A capability's `launch`
+  hook may return `meta` like the spawn hook does, but the start/restart path
+  consumed only its `launch` arguments and `env`, so `instance.json.capabilityMeta`
+  kept the spawn-time value forever. A provider that re-issues a credential at
+  every start (e.g. a renewed messaging session grant) would have left the
+  ORIGINAL id on record, and retire — which reads that record as `OATS_META` —
+  would have revoked the wrong one while the live one ran to its TTL. After a
+  successful start the kernel now merges each capability's launch `meta` over
+  its entry; a hook answering without `meta` keeps its prior entry; a failed
+  launch preparation changes nothing. Regression test in
+  `test/session-restart.test.mjs`; contract paragraph in `docs/capabilities.md`.
+
+No new flags, fields or hook events. `oats version --json` unchanged apart from
+the version.
+
+## Catalog
+
+- **oats.okf → v2.1.4** (mirror in `capabilities/oats-okf` synced, published
+  tag `2af47ad3`): sparse staging to `base.root` from a single-branch partial
+  clone with streamed object reads (large repositories and large files outside
+  the knowledge base no longer matter), `git-timeout` binding key (600 s for
+  remote operations), migration record hygiene + `oats okf migrate --forget`,
+  owners keyed by `OATS_SOUL_ID` with a one-time rewrite of same-name path pins
+  (closes the `E_OWNER`-after-member-commit regression; needs kernel ≥ 0.25.3),
+  and retire removes a drained source's `okf-<id>` scheduler job.
+- **oats.aweb → v1.12.0** (byte-identical to `capabilities/oats-aweb`):
+  resident identity session grants — `identity.mode: local | global`, `team`
+  read from the payload (so `messaging.byTeam.<label>.team` is now the per-label
+  identity), host-only `residents` map, and the messaging-layer meta key
+  `identity` on every spawn. Known limitation: sending mail/chat through a
+  grant is rejected by the aweb server as of aw 1.36.1 (client bug; receive,
+  wake and whoami work). Guide truths in `docs/workspaces.md` and
+  `docs/rebuild-to-v2.md` updated from "1.11.2 ignores `team`" to what 1.12.0
+  does.
+

package/docs/workspace-adoption.md

@@ -29,7 +29,7 @@ two roles never collapse: `oats-okf`, `oats-aweb`, `oats-jira`, `oats-linear`,
 their `oats-package/` is consumed only as a package: `from: package`, pinned
 in the workspace's `packages:`, locked and approved per version. The framework's
 own souls therefore say `oats.okf: { from: package }` even though `oats-okf` is
-a member. A bare version in `packages:` (`oats.okf: v2.1.3`) resolves through
+a member. A bare version in `packages:` (`oats.okf: v2.1.4`) resolves through
 the catalog; a package outside it is written `git:<repo>@<ref>`.
 
 ## Join it on your machine

package/docs/workspaces.md

@@ -61,7 +61,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.3
+  oats.okf: v2.1.4
   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
@@ -383,13 +383,16 @@ a label under `byTeam` that is not declared in `teams:` is `E_WORKSPACE_SCHEMA`.
 **`byTeam` is kernel-merged; whether a provider honours what arrives is the
 provider's.** `spawn --preview` shows the merged `settings.<cap>` so the
 delivery is verifiable, and `instance.json.providers.<cap>` records it — but
-oats.aweb **1.11.2 does not read `team` from its payload** (it resolves the
-team from the removed `oats-config.yaml` `team:` block, else the active team at
-the `.aw` root it finds), so for 1.11.2 `byTeam` is a recorded intent, not a
-per-label identity; the per-repo `.aw` placement in
-[rebuild-to-v2.md §8b](rebuild-to-v2.md#8b-where-the-team-aw-lives-now-oatsaweb-1112-and-what-byteam-does-today)
-is the working alternative. An oats.aweb release that reads `team` from the
-payload closes the gap without a workspace edit (release notes will name it).
+**oats.aweb 1.12.0 reads `team` from its payload** and mints into exactly that
+team (`--team-id`), warning when the payload disagrees with an `OATS_TEAM_*`
+value — so `byTeam.<label>.team` IS the per-label identity. What the payload
+does not change is **where the `.aw` root is found**: the hook still searches
+the bounded candidates in
+[rebuild-to-v2.md §8b](rebuild-to-v2.md#8b-where-the-team-aw-lives-now-and-what-byteam-does-today)
+and that root must hold a membership of the named team (the deployment's `.aw`
+joined to every team its labels name is the simple layout). On oats.aweb
+1.11.2 `team` was ignored (the root's active team won), so `byTeam` there is
+a recorded intent only.
 A store (`stores: { <name>: <repo ref> }`) names a repository; where a
 knowledge base lives inside it is the knowledge provider's own concern — for
 OKF 2.1.3 that is the **bindings file** (`bases.<alias>.repository` + `root`,

package/lib/core.mjs

@@ -6097,7 +6097,7 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
   const inst = instance || meta?.instance || basename(home);
   const command = renderLaunchRecipe(recipe, { home, instance: inst });
   const selectionSource = frozen ? (config?.frozen || (!config && !selection.launchConfig && !selection.runtime) ? "frozen" : "config") : "config";
-  return { recipe, command, runtime, model: model || undefined, modelSource, yolo, config, executable, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen };
+  return { recipe, command, runtime, model: model || undefined, modelSource, yolo, config, executable, preflight: problems, ok: problems.every((c) => c.ok), selectionSource, frozen, ...(hooks.meta ? { hookMeta: hooks.meta } : {}) };
 }
 /** The environment a planned launch runs under: the host's base, the
  *  capabilities' validated env, the configuration's literals and its
@@ -8296,6 +8296,7 @@ export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, c
   // prepares the target runtime under its CAPTURED settings.
   const ctx = contextDir || meta.repo;
   const withLaunchHook = [];
+  let hookMeta;
   for (const p of capturedProviders(meta, frozen)) {
     const manifest = ctx ? capabilityManifest(p.id, ctx) : undefined;
     if (!manifest) throw oatsError("E_LAUNCH_PREPARATION", `${p.id} was part of this home's launch at spawn but is no longer installed in the scope; reinstall it (oats install) or respawn the instance; nothing was stopped`);
@@ -8328,6 +8329,12 @@ export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, c
       refreshed.push(c.capability);
     }
     Object.assign(env, res.env || {});
+    // A launch hook's `meta` is part of its documented return (the same shape
+    // spawn persists as capabilityMeta). It was collected and then dropped
+    // here, so a provider that re-issues a credential at every start — a
+    // renewed session grant, for instance — left the ORIGINAL id on record and
+    // retire undid the wrong one. Carry it to the caller; the start records it.
+    hookMeta = res.meta && Object.keys(res.meta).length ? res.meta : undefined;
   }
   const unprepared = contributions.filter((c) => c.capability !== null && !refreshed.includes(c.capability) && c.launch && c.launch[frozen.runtime] !== undefined && c.launch[runtime] === undefined).map((c) => c.capability);
   const legacyArgs = contributions.filter((c) => c.capability === null && c.launch && Object.keys(c.launch).length);
@@ -8335,7 +8342,7 @@ export function prepareLaunchHooks({ frozen, runtime, resolvedCfg, home, meta, c
   if (unprepared.length) throw oatsError("E_LAUNCH_PREPARATION", `${unprepared.join(", ")} contributed ${frozen.runtime} launch arguments at spawn and none for ${runtime}; change that capability's setting (for example its delivery mode), or the provider must declare a launch hook; nothing was stopped`);
   const launch = {};
   for (const c of contributions) { if (c.capability === null && refreshed.length) continue; for (const [rt, args] of Object.entries(c.launch || {})) if (args) launch[rt] = `${launch[rt] ? `${launch[rt]} ` : ""}${args}`; }
-  return { launch, env, contributions: contributions.filter((c) => !(c.capability === null && refreshed.length)), refreshed };
+  return { launch, env, contributions: contributions.filter((c) => !(c.capability === null && refreshed.length)), refreshed, ...(hookMeta ? { meta: hookMeta } : {}) };
 }
 
 /** Start a stopped instance again in its existing home: no new home, no
@@ -8639,7 +8646,7 @@ export function startInstanceSession(home, o = {}) {
   // The independent receipt first (retire and session consult it), then the
   // mutable metadata; both tmp+rename. A failure between them is what the
   // pending receipt exists for.
-  const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, runtime: newRuntime, yolo: newYolo, stop, nativeRecordId }, clearPending = true) => {
+  const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, runtime: newRuntime, yolo: newYolo, stop, nativeRecordId, hookMeta }, clearPending = true) => {
     checkRoots();
     const baselinePath = retirementBaselinePath(realHome);
     let baseline;
@@ -8654,7 +8661,10 @@ export function startInstanceSession(home, o = {}) {
     const restarts = (Array.isArray(meta.restarts) ? meta.restarts : []).slice(recorded ? -20 : -19);
     if (!recorded) restarts.push({ startedAt, model: model ?? null, reused });
     const next = { ...meta, model, command, launched: true, startId: id, restarts, restartCount: (meta.restartCount || 0) + (recorded ? 0 : 1),
-      ...(launch ? { launch } : {}), ...(newRuntime ? { runtime: newRuntime } : {}), ...(newYolo !== undefined ? { yolo: newYolo } : {}) };
+      ...(launch ? { launch } : {}), ...(newRuntime ? { runtime: newRuntime } : {}), ...(newYolo !== undefined ? { yolo: newYolo } : {}),
+      // Launch-hook meta lands per capability over the spawn's record; a hook
+      // that answered without meta keeps its previous entry (retire reads it).
+      ...(hookMeta ? { capabilityMeta: { ...(meta.capabilityMeta || {}), ...hookMeta } } : {}) };
     if (backend === "herdr") { next.sessionTarget = target; delete next.tmux; }
     else { next.tmux = { session: target.session, window: target.window, socket: resolve(target.socket) }; delete next.sessionTarget; }
     if (capturedStart) atomicWriteFileSync(metaPath, canonicalJson(next), { assertRoots: checkRoots });
@@ -8753,7 +8763,7 @@ export function startInstanceSession(home, o = {}) {
       const resolvedCfg = resolveOatsConfig(context, meta.agent);
       let agent; try { agent = findAgent(dirname(dirname(dirname(realHome))), meta.agent); } catch { agent = undefined; }
       const plan = planLaunch({ home: realHome, instance: meta.instance, meta, contextDir: context, agentLike: agent || { runtime: meta.runtime, model: meta.model, yolo: meta.yolo }, selection: { launchConfig: o.launchConfig, runtime: o.runtime, model: o.model, yolo: o.yolo }, resolvedCfg, env: o.env || process.env, assertRoots: checkRoots });
-      launchPlan = { recipe: plan.recipe, command: plan.command, runtime: plan.runtime, model: plan.model, yolo: plan.yolo };
+      launchPlan = { recipe: plan.recipe, command: plan.command, runtime: plan.runtime, model: plan.model, yolo: plan.yolo, ...(plan.hookMeta ? { hookMeta: plan.hookMeta } : {}) };
       command = launchPlan.command; model = launchPlan.model;
     } else if (o.model !== undefined && o.model !== null && String(o.model).trim() !== "") {
       const resolved = resolveModelPreference(String(o.model), runtime);
@@ -8770,6 +8780,7 @@ export function startInstanceSession(home, o = {}) {
     const paneEnvExports = paneEnv.map((r) => `export ${r.name}=${shq(r.value)}; `).join("");
     checkRoots(); // launch hooks/preparation have run; no backend has been observed
     const planExtra = launchPlan ? { launch: launchPlan.recipe, runtime: launchPlan.runtime, yolo: launchPlan.yolo,
+      ...(launchPlan.hookMeta ? { hookMeta: launchPlan.hookMeta } : {}),
       ...(capturedStart ? { capturedIntent: capturedStart.intent } : {}) } : {};
     let target = receipt.target;
     let state = { present: false, state: "not-launched" };
@@ -9301,7 +9312,17 @@ export function retireInstance(root, name, o = {}) {
     } catch { markerUnusable = true; }
   }
   const liveMeta = existsSync(metaPath) ? JSON.parse(readFileSync(metaPath, "utf8")) : undefined;
-  const meta = liveMeta || quarantine?.cleanup || {};
+  // A quarantined home may carry an instance.json that is NOT the spawn record:
+  // module materialization writes a pre-hook stub ({ modules, providers,
+  // resolutionRevision }) before the spawn hooks run, and a required-hook
+  // failure retains the home with that stub in place. Trusting it over the
+  // cleanup descriptor left meta.repo undefined, so the retry never re-ran the
+  // owed retire hook and reported "cleanup descriptor lost its context repo"
+  // on every attempt — only --force could clear the home (found by an operator
+  // rehearsal on 0.25.3). The descriptor is written FOR this retry; a live
+  // record only wins when it is a complete spawn record (repo + work present).
+  const liveIsSpawnRecord = !!liveMeta && nonEmptyString(liveMeta.repo) && WORK_MODES.includes(liveMeta.work);
+  const meta = liveIsSpawnRecord || !quarantine ? (liveMeta || quarantine?.cleanup || {}) : { ...liveMeta, ...quarantine.cleanup };
   // Compensation metadata is the SPAWN's, from whichever record survived — never
   // a failed retry's report, which says nothing about what still needs undoing.
   if (!liveMeta?.capabilityMeta && quarantine?.cleanup?.capabilityMeta) meta.capabilityMeta = quarantine.cleanup.capabilityMeta;

package/package-catalog.json

@@ -3,12 +3,12 @@
   "packages": {
     "oats.okf": {
       "url": "https://github.com/awebai/oats-okf.git",
-      "ref": "v2.1.3",
+      "ref": "v2.1.4",
       "path": "oats-package"
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.11.2",
+      "ref": "v1.12.0",
       "path": "oats-package"
     },
     "oats.jira": {

package/package.json

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