@awebai/oats 0.22.2 → 0.22.3

package/lib/core.mjs

@@ -671,7 +671,7 @@ export function resolveCapabilities(contextDir, soulName) {
       }
     }
     const ranked = [...list].sort((a, b) => a.specificity - b.specificity || b.scope - a.scope || a.target.localeCompare(b.target));
-    const settings = {};
+    const settings = Object.create(null); // manifest-declared names such as "constructor" must read as unset
     // Setting names come from parsed config, so the RANK table — a key→info
     // lookup, unlike `settings` itself, which is data handed to consumers — is
     // null-prototype: an inherited name must not read as an already-taken rank.
@@ -685,12 +685,28 @@ export function resolveCapabilities(contextDir, soulName) {
         settings[key] = value; settingRank[key] = rank;
       }
     }
+    // Declared defaults (manifest `settings: { <name>: { default } }`) are part
+    // of the effective settings: a requirement conditional on a setting must
+    // see the default for a deployment that never set it, or the default path
+    // silently loses its requirements (aweb review of oats.aweb 1.10.0).
+    const declaredSettings = manifest.settings && typeof manifest.settings === "object" && !Array.isArray(manifest.settings) ? manifest.settings : {};
+    for (const [key, decl] of Object.entries(declaredSettings)) {
+      if (!decl || typeof decl !== "object") continue;
+      if (settings[key] === undefined && decl.default !== undefined) settings[key] = decl.default;
+    }
     const strongest = [...list].sort((a, b) => b.specificity - a.specificity || a.scope - b.scope || a.target.localeCompare(b.target));
     const top = strongest[0];
     const tied = strongest.filter((c) => c.specificity === top.specificity && c.scope === top.scope);
     const enabledValues = new Set(tied.map((c) => c.binding.enabled === undefined ? true : !!c.binding.enabled));
     if (enabledValues.size > 1) throw new Error(`ambiguous enabled/excluded bindings for ${id} at equal specificity (${tied.map((c) => c.target).join(", ")})`);
     if (![...enabledValues][0]) continue;
+    // A declared value set is enforced for an ACTIVE capability: a misspelling
+    // must not switch a conditional requirement off by matching nothing.
+    for (const [key, decl] of Object.entries(declaredSettings)) {
+      if (decl && typeof decl === "object" && Array.isArray(decl.values) && settings[key] !== undefined && !decl.values.some((v) => String(v) === String(settings[key]))) {
+        throw new Error(`capability setting ${id}.${key} is ${JSON.stringify(settings[key])}, not one of ${decl.values.map((v) => JSON.stringify(v)).join(", ")}`);
+      }
+    }
     const compatibility = capabilityCompatibility(manifest);
     if (!compatibility.compatible) throw new Error(`capability "${id}" requires OATS ${compatibility.range}; running ${compatibility.version}`);
     const trust = capabilityTrust(manifest, contextDir);
@@ -703,7 +719,7 @@ export function resolveCapabilities(contextDir, soulName) {
     active.push({
       id, capability: id, manifest, layer: manifest.layer, command: manifest.command,
       level: top.level, origin: manifest._origin, provenance: list.map((c) => `${c.target} @ ${c.level}`),
-      settings, skills: capabilitySkillDirs(id, contextDir), inject,
+      settings: { ...settings }, skills: capabilitySkillDirs(id, contextDir), inject,
       // What the manifest PROMISES, so preflight can tell "declared nothing"
       // from "declared and missing" — the two are indistinguishable in the
       // resolved lists above.
@@ -717,6 +733,7 @@ export function resolveCapabilities(contextDir, soulName) {
       // what required:true claims to prevent (aggregate review at 798b156).
       requiredHooks: manifestRequiredHooks(manifest),
       environment: trust.trusted ? [...(manifest.environment || [])] : [],
+      environmentNamespaces: trust.trusted ? [...(manifest.environmentNamespaces || [])] : [],
       missingRequires: capabilityMissingRequires(id, contextDir), compatibility, trust, executable,
       retirement: trust.trusted ? manifest.retirement : undefined,
       _scope: top.scope,
@@ -889,6 +906,18 @@ function validateCapabilityManifest(m, mf) {
       const vendor = id.match(/^([a-z][a-z0-9]*)\./)?.[1];
       if (!vendor) throw new Error(`capability ${id} must use a lowercase dotted vendor ID to declare launch environment`);
       const prefix = `${vendor.toUpperCase()}_`;
+      // A capability may declare additional namespaces it speaks for, e.g.
+      // the official oats.aweb integration setting the aweb extensions'
+      // AWEB_ variables. Declared, never implied: the names are disclosed at
+      // trust time with the rest of the launch environment, and the reserved
+      // core and bootstrap namespaces can never be claimed this way.
+      const extraNamespaces = m.environmentNamespaces === undefined ? [] : m.environmentNamespaces;
+      if (!Array.isArray(extraNamespaces) || extraNamespaces.some((ns) => typeof ns !== "string")) throw new Error(`capability ${id} manifest environmentNamespaces must be an array of prefixes`);
+      for (const ns of extraNamespaces) {
+        if (!/^[A-Z][A-Z0-9]*_$/.test(ns)) throw new Error(`capability ${id} manifest environmentNamespaces entry ${JSON.stringify(ns)} must be an uppercase prefix ending in an underscore`);
+        if (ns === "OATS_" || ns === "PI_AGENT_" || PROCESS_BOOTSTRAP_PREFIXES.some((reserved) => ns.startsWith(reserved) || reserved.startsWith(ns))) throw new Error(`capability ${id} manifest environmentNamespaces entry ${ns} is a reserved namespace`);
+      }
+      const allowed = [prefix, ...extraNamespaces];
       for (const name of m.environment) {
         if (!PORTABLE_ENV_NAME_RE.test(name)) throw new Error(`capability ${id} manifest environment name ${JSON.stringify(name)} is invalid`);
         if (CORE_LAUNCH_ENV.has(name) || name.startsWith("OATS_") || name.startsWith("PI_AGENT_")) {
@@ -897,7 +926,7 @@ function validateCapabilityManifest(m, mf) {
         if (PROCESS_BOOTSTRAP_ENV.has(name) || PROCESS_BOOTSTRAP_PREFIXES.some((reserved) => name.startsWith(reserved))) {
           throw new Error(`capability ${id} manifest environment name ${name} collides with a reserved process bootstrap variable`);
         }
-        if (!name.startsWith(prefix)) throw new Error(`capability ${id} manifest environment name ${name} is outside its ${prefix} namespace`);
+        if (!allowed.some((ns) => name.startsWith(ns))) throw new Error(`capability ${id} manifest environment name ${name} is outside its ${allowed.join(", ")} namespace${allowed.length > 1 ? "s" : ""} (declare another in environmentNamespaces)`);
       }
     }
   }
@@ -1309,6 +1338,7 @@ export function capabilityTrust(a, b) {
       commands: Object.keys(manifest?.commands || {}),
       hooks: Object.keys(manifest?.hooks || {}),
       environment: [...(manifest?.environment || [])],
+      ...(manifest?.environmentNamespaces?.length ? { environmentNamespaces: [...manifest.environmentNamespaces] } : {}),
     };
     return { ...t, package: t.package || manifest?._package, executableSurface: surface };
   }
@@ -2591,6 +2621,7 @@ function executableSurfaceOf(manifest) {
     commands: Object.keys(manifest?.commands || {}),
     hooks: Object.keys(manifest?.hooks || {}),
     environment: [...(manifest?.environment || [])],
+    ...(manifest?.environmentNamespaces?.length ? { environmentNamespaces: [...manifest.environmentNamespaces] } : {}),
   };
 }
 function hasExecutableSurface(manifest) {
@@ -4254,6 +4285,27 @@ export function packageSpecIdentity(spec) {
 /** What the runtime reports about a required package: is it there, where did it
  * land, and does the user's entry filter its resources? A settings row alone is
  * NOT proof the capability's extension will load (reviewer-8518c49). */
+/** The installed version of a runtime package: neither pi's nor Claude's
+ *  listing reports one, so it is read from the package.json under the
+ *  install directory the listing names; undefined when there is none. */
+export function installedRuntimePackageVersion(runtime, spec, status) {
+  const dir = status?.dir;
+  if (dir && existsSync(join(dir, "package.json"))) {
+    try {
+      const v = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).version;
+      if (typeof v === "string" && /^\d+\.\d+\.\d+/.test(v)) return v.match(/^\d+\.\d+\.\d+/)[0];
+    } catch { /* unreadable manifest: unknowable */ }
+  }
+  return undefined;
+}
+
+export function compareVersionTriples(a, b) {
+  const pa = String(a).split(".").map((x) => Number.parseInt(x, 10) || 0);
+  const pb = String(b).split(".").map((x) => Number.parseInt(x, 10) || 0);
+  for (let i = 0; i < 3; i++) { const d = (pa[i] || 0) - (pb[i] || 0); if (d) return d; }
+  return 0;
+}
+
 export function runtimePackageStatus(runtime, spec, env = process.env, opts = {}) {
   const mgr = RUNTIME_PACKAGE_MANAGERS[runtime];
   if (!mgr) return { installed: false };
@@ -4342,6 +4394,12 @@ function validateHookEnvironment(capabilityID, value, owners, declarations) {
     throw new HookEnvironmentContractError(`${capabilityID} hook env requires a dotted lowercase alphanumeric vendor component; hyphen, @, and / forms cannot claim an environment namespace`);
   }
   const prefix = `${vendorComponent.toUpperCase()}_`;
+  // The runtime half of the same contract the manifest validator enforces:
+  // a hook may set names under its vendor prefix or under a namespace its
+  // trusted manifest declared (environmentNamespaces), and only names the
+  // manifest listed. Manifest and runtime must permit exactly the same set.
+  const declared = declarations.get(capabilityID) || { names: new Set(), namespaces: [] };
+  const allowed = [prefix, ...(declared.namespaces || [])];
   const accepted = {};
   for (const name of Object.keys(value).sort()) {
     const envValue = value[name];
@@ -4354,10 +4412,10 @@ function validateHookEnvironment(capabilityID, value, owners, declarations) {
     if (PROCESS_BOOTSTRAP_ENV.has(name) || PROCESS_BOOTSTRAP_PREFIXES.some((reserved) => name.startsWith(reserved))) {
       throw new HookEnvironmentContractError(`${capabilityID} hook env name ${name} collides with a reserved process bootstrap variable`);
     }
-    if (!name.startsWith(prefix)) {
-      throw new HookEnvironmentContractError(`${capabilityID} hook env name ${name} is outside its ${prefix} namespace`);
+    if (!allowed.some((ns) => name.startsWith(ns))) {
+      throw new HookEnvironmentContractError(`${capabilityID} hook env name ${name} is outside its ${allowed.join(", ")} namespace${allowed.length > 1 ? "s" : ""}`);
     }
-    if (!(declarations.get(capabilityID) || new Set()).has(name)) {
+    if (!declared.names.has(name)) {
       throw new HookEnvironmentContractError(`${capabilityID} hook env name ${name} is not declared in its trusted manifest environment`);
     }
     if (typeof envValue !== "string") {
@@ -4382,7 +4440,7 @@ function validateHookEnvironment(capabilityID, value, owners, declarations) {
 export function runLifecycleHooks(event, { home, instance, agentName, soulDir, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {} }) {
   const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [] };
   const envOwners = new Map();
-  const envDeclarations = new Map((resolved.capabilities || []).map((cap) => [cap.id, new Set(cap.environment || [])]));
+  const envDeclarations = new Map((resolved.capabilities || []).map((cap) => [cap.id, { names: new Set(cap.environment || []), namespaces: [...(cap.environmentNamespaces || [])] }]));
   const caps = [...(resolved.capabilities || [])];
   if (event === "retire") caps.reverse();
   for (const cap of caps) {
@@ -4999,6 +5057,11 @@ function verifyRuntimePackages(runtime, resolved, contextDir) {
   for (const cap of resolved.capabilities || []) {
     for (const raw of cap.manifest?.requires || []) {
       if (!raw || typeof raw !== "object" || raw.runtime !== runtime) continue;
+      // A requirement may be conditional on the capability's effective
+      // settings (`when: { delivery: "channel" }`): rows whose condition does
+      // not hold are not requirements of this spawn at all.
+      if (raw.when !== undefined && (!raw.when || typeof raw.when !== "object" || Array.isArray(raw.when))) { problems.push(`${cap.id}: a requirement's \`when\` must be an object of setting names to values`); continue; }
+      if (raw.when && !Object.entries(raw.when).every(([k, v]) => String(cap.settings?.[k] ?? "") === String(v))) continue;
       const spec = raw.package;
       if (!safeRuntimePackageSpec(spec, runtime)) { problems.push(`${cap.id}: ${runtime} package spec is not a plain source token (${JSON.stringify(spec)})`); continue; }
       if (raw.marketplace !== undefined && !safeRuntimeSourceRef(raw.marketplace)) { problems.push(`${cap.id}: marketplace is not a plain source reference (${JSON.stringify(raw.marketplace)})`); continue; }
@@ -5007,7 +5070,10 @@ function verifyRuntimePackages(runtime, resolved, contextDir) {
       const stepList = mgr?.steps ? mgr.steps(spec, raw, probeOpts) : [mgr?.argv(spec, raw, probeOpts) || []];
       const direct = stepList.filter((a) => a.length).map((a) => a.join(" ")).join(" && ");
       const remedy = `run \`oats install --accept-requirement ${runtime}:${runtimePackageIdentity(runtime, spec)} --dir ${contextDir}\`${direct ? ` (or \`${direct}\` directly)` : ""}`;
-      if (!status.installed) { problems.push(`${cap.id} requires the ${runtime} package ${spec}, which is not installed — ${remedy}`); continue; }
+      // `ifInstalled: true`: the row constrains a package that may be absent
+      // (an ambient extension must honour a contract IF it is there); absence
+      // satisfies it. Without the flag, absence fails as before.
+      if (!status.installed) { if (raw.ifInstalled === true) continue; problems.push(`${cap.id} requires the ${runtime} package ${spec}, which is not installed — ${remedy}`); continue; }
       // A settings row is not proof the extension loads. Both of these leave the
       // capability silently absent, which is the loss this gate exists to stop.
       if (status.unverified) { problems.push(`${cap.id} requires the ${runtime} package ${spec}: it is configured, but OATS could not verify it is installed (${status.unverified}) — a config entry is not an installation; ${remedy}`); continue; }
@@ -5019,6 +5085,16 @@ function verifyRuntimePackages(runtime, resolved, contextDir) {
       }
       if (status.disabled) { problems.push(`${cap.id} requires the ${runtime} package ${spec}, which is installed but DISABLED, so it will not load — enable it (\`${probeOpts.bin || runtime} plugin enable ${spec}\` for Claude), or drop the capability for this soul`); continue; }
       if (status.extensionsDisabled) { problems.push(`${cap.id} requires the ${runtime} package ${spec}, but your ${runtime} settings entry sets "extensions": [], which loads none of them — remove that filter, or drop the capability for this soul`); continue; }
+      // A floor on the installed version (`minVersion`), checked once presence
+      // and loadability are settled: a package whose manifest states an older
+      // version, or none, fails closed with the same remedy, since an old
+      // extension that ignores a newer contract (AWEB_DELIVERY) is exactly
+      // what the floor guards.
+      if (raw.minVersion) {
+        const have = installedRuntimePackageVersion(runtime, spec, status);
+        if (!have) { problems.push(`${cap.id} requires the ${runtime} package ${spec} at ${raw.minVersion} or later, but its installed version cannot be established (no package manifest under its install directory) — ${remedy}`); continue; }
+        if (compareVersionTriples(have, raw.minVersion) < 0) { problems.push(`${cap.id} requires the ${runtime} package ${spec} at ${raw.minVersion} or later; ${have} is installed — ${remedy}`); continue; }
+      }
       if (status.extensionsFilter?.length) {
         // Unverifiable, not merely auditable: proving the filter selects this
         // capability's extension means implementing pi's glob semantics, and
@@ -5803,6 +5879,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
         settings: cap.settings, provenance: cap.provenance, skills: cap.skills || [],
         hooks: Object.keys(cap.hooks || {}), trusted: !!cap.trust?.trusted,
         ...(cap.environment?.length ? { environment: [...cap.environment] } : {}),
+        ...(cap.environmentNamespaces?.length ? { environmentNamespaces: [...cap.environmentNamespaces] } : {}),
       })),
       skills: [...chosen].sort(([a], [b]) => a.localeCompare(b)).map(([name, v]) => ({ name, source: v.source })),
       instructions: composition.blocks.map((b) => ({ source: b.source, file: b.file })),
@@ -5845,7 +5922,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       },
       capabilityRuntime: resolvedCfg.capabilities.map((cap) => ({
         id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings,
-        hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment,
+        hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment, environmentNamespaces: cap.environmentNamespaces,
         missingRequires: cap.missingRequires, trust: cap.trust,
         executable: cap.executable,
       })),
@@ -6099,7 +6176,7 @@ function quarantineInstanceHome({ home, instance, agent, incomplete, failed, out
         outstanding: { hooks: [...outstandingHooks], git: [...outstandingGit] },
         capabilityRuntime: (resolvedCfg.capabilities || []).map((cap) => ({
           id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings,
-          hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment,
+          hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment, environmentNamespaces: cap.environmentNamespaces,
           missingRequires: cap.missingRequires,
           trust: cap.trust, executable: cap.executable,
         })),
@@ -6414,17 +6491,44 @@ const RECOVERABLE_GIT_ADMIN = [
   "BISECT_LOG", "BISECT_START", "BISECT_NAMES", "rebase-apply", "rebase-merge", "sequencer",
 ];
 
+/** Object ids among `oids` that `repo` does not have, from one
+ *  `cat-file --batch-check` process. */
+export function missingGitObjects(repo, oids) {
+  if (!oids.length) return [];
+  const out = execFileSync("git", ["-C", repo, "cat-file", "--batch-check=%(objectname) %(objecttype)"], { input: oids.join("\n") + "\n", encoding: "utf8", maxBuffer: GIT_MAX_BUFFER });
+  const missing = [];
+  for (const line of out.split("\n")) {
+    if (!line.endsWith(" missing")) continue;
+    missing.push(line.slice(0, line.indexOf(" ")));
+  }
+  return missing;
+}
+
 function restoreStandaloneGitState(sourceWork, recoveredRepo) {
   const sourceGit = execFileSync("git", ["-C", sourceWork, "rev-parse", "--absolute-git-dir"], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
   const recoveredGit = join(recoveredRepo, ".git");
   const indexRows = execFileSync("git", ["-C", sourceWork, "ls-files", "--stage", "-z"], { maxBuffer: GIT_MAX_BUFFER });
+  // The staged blobs the recovered index will point at. The clone already
+  // holds every blob reachable from a commit; only content that is staged but
+  // never committed is missing, so ask once which objects the recovered
+  // repository lacks (one process for the whole index) and copy only those.
+  // Copying every row cost two Git processes per index entry: a clean 9,500
+  // file tree took ~19,000 launches and looked like a hang. Gitlink rows
+  // (mode 160000) name commits of nested repositories, which
+  // materializeNestedRepositories restores; they are never blobs here.
+  const staged = new Set();
   for (const row of indexRows.toString("utf8").split("\0").filter(Boolean)) {
-    const match = row.match(/^\d+ ([0-9a-f]+) \d+\t/);
-    if (!match) continue;
-    const blob = execFileSync("git", ["-C", sourceWork, "cat-file", "blob", match[1]], { maxBuffer: GIT_MAX_BUFFER });
+    const match = row.match(/^(\d+) ([0-9a-f]+) \d+\t/);
+    if (!match || match[1] === "160000") continue;
+    staged.add(match[2]);
+  }
+  for (const oid of missingGitObjects(recoveredRepo, [...staged])) {
+    const blob = execFileSync("git", ["-C", sourceWork, "cat-file", "blob", oid], { maxBuffer: GIT_MAX_BUFFER });
     const restored = execFileSync("git", ["-C", recoveredRepo, "hash-object", "-w", "--stdin"], { input: blob, encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
-    if (restored !== match[1]) throw new Error(`recovered Git object ${restored} did not match source ${match[1]}`);
+    if (restored !== oid) throw new Error(`recovered Git object ${restored} did not match source ${oid}`);
   }
+  const stillMissing = missingGitObjects(recoveredRepo, [...staged]);
+  if (stillMissing.length) throw new Error(`recovered repository lacks ${stillMissing.length} staged object(s) after restore: ${stillMissing.slice(0, 3).join(", ")}`);
   copyFileSync(join(sourceGit, "index"), join(recoveredGit, "index"));
   for (const name of RECOVERABLE_GIT_ADMIN) {
     const source = join(sourceGit, name);
@@ -6479,12 +6583,22 @@ function preserveRetirementWork(observation, meta, instance) {
   const staging = mkdtempSync(join(recoveryRoot, `.${instance}-`));
   const recovery = join(recoveryRoot, basename(staging).slice(1));
   try {
+    // A home-only change (notes, runtime files, credentials) needs a home
+    // snapshot, not another copy of an otherwise disposable clean worktree.
+    // In-progress Git operations retain the full standalone recovery even
+    // when porcelain status has no changed paths.
+    let homeOnly = observation.classes.length === 1 && observation.classes[0] === "changed instance-home bytes"
+      && meta.work === "worktree" && existsSync(observation.work);
+    if (homeOnly) {
+      const gitDir = execFileSync("git", ["-C", observation.work, "rev-parse", "--absolute-git-dir"], { encoding: "utf8", maxBuffer: GIT_MAX_BUFFER }).trim();
+      homeOnly = !RECOVERABLE_GIT_ADMIN.some((name) => existsSync(join(gitDir, name)));
+    }
     const recoveredHome = join(staging, "home");
     copyRecoveryTree(observation.home, recoveredHome, { excludeRoot: new Set(["work"]) });
     if (fingerprintTree(observation.home, { excludeRoot: new Set(["work"]) }) !== fingerprintTree(recoveredHome)) {
       throw new Error("home recovery verification disagreed with the source");
     }
-    if (meta.work === "worktree" && meta.repo && meta.branch && (existsSync(observation.work) || observation.branchExists)) {
+    if (!homeOnly && meta.work === "worktree" && meta.repo && meta.branch && (existsSync(observation.work) || observation.branchExists)) {
       const recoveredRepo = join(staging, "repo");
       execFileSync("git", ["clone", "--no-local", "--quiet", "--branch", meta.branch, meta.repo, recoveredRepo], { stdio: ["ignore", "pipe", "pipe"] , maxBuffer: GIT_MAX_BUFFER });
       const sourceGitContext = existsSync(observation.work) ? observation.work : meta.repo;
@@ -6508,10 +6622,11 @@ function preserveRetirementWork(observation, meta, instance) {
       const sourceHead = execFileSync("git", ["-C", meta.repo, "rev-parse", `refs/heads/${meta.branch}`], { encoding: "utf8" , maxBuffer: GIT_MAX_BUFFER }).trim();
       if (recoveredHead !== sourceHead) throw new Error("recovery clone does not retain the instance branch tip");
     }
-    writeFileSync(join(staging, "recovery.json"), JSON.stringify({ version: 1, instance, classes: observation.classes, sourceHome: observation.home, createdAt: new Date().toISOString() }, null, 2) + "\n", { mode: 0o600 });
+    const repoCopy = homeOnly ? { copied: false, reason: "Only instance-home bytes changed; no work state requires a repository copy", source: meta.repo, branch: meta.branch } : undefined;
+    writeFileSync(join(staging, "recovery.json"), JSON.stringify({ version: 1, instance, classes: observation.classes, sourceHome: observation.home, createdAt: new Date().toISOString(), ...(repoCopy ? { repoCopy } : {}) }, null, 2) + "\n", { mode: 0o600 });
     mkdirSync(dirname(recovery), { recursive: true });
     renameSync(staging, recovery);
-    return { path: recovery, classes: observation.classes };
+    return { path: recovery, classes: observation.classes, ...(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}`);
@@ -6562,12 +6677,12 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
   const intent = {
     instance: name, agent: found.agent.name, root: resolve(root),
     requestedAt: new Date().toISOString(), requestedByPid: process.pid, delaySec,
-    options: { deleteBranch: !!o.deleteBranch, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session }, resultPath,
+    options: { home: found.home, deleteBranch: !!o.deleteBranch, ...(o.keepDir ? { keepDir: true } : {}), tmuxSession: session }, resultPath,
   };
   const env = { ...process.env, OATS_RETIRE_INTENT: JSON.stringify(intent) };
   for (const k of CORE_LAUNCH_ENV) delete env[k];
   rmSync(resultPath, { force: true });
-  const scheduleFailed = (why) => oatsError("E_SELF_RETIRE_SCHEDULE_FAILED", `could not start the deferred retirement of ${name}: ${why}. Nothing was inspected, run, or removed; the instance is still live and can be retired externally with \`oats retire ${name}\``);
+  const scheduleFailed = (why) => oatsError("E_SELF_RETIRE_SCHEDULE_FAILED", `could not start the deferred retirement of ${name}: ${why}. Nothing was inspected, run, or removed; the instance is still live and can be retired externally with \`oats retire ${name} --home ${found.home}\``);
   let fd, child;
   try {
     fd = openSync(logPath, "w");
@@ -6586,7 +6701,7 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
   // debt instead of an uncaught exception behind a success message.
   child.on("error", (e) => {
     try {
-      writeFileSync(resultPath, JSON.stringify({ instance: name, agent: found.agent.name, requestedAt: intent.requestedAt, completedAt: new Date().toISOString(), ok: false, error: { code: e.code, message: `the deferred retirement could not start: ${e.message}` }, retry: `oats retire ${name}` }, null, 2) + "\n");
+      writeFileSync(resultPath, JSON.stringify({ instance: name, agent: found.agent.name, requestedAt: intent.requestedAt, completedAt: new Date().toISOString(), ok: false, error: { code: e.code, message: `the deferred retirement could not start: ${e.message}` }, retry: `oats retire ${name} --home ${found.home}` }, null, 2) + "\n");
     } catch { /* the marker alone then shows RETIRING; status names its age */ }
   });
   child.unref();
@@ -6625,20 +6740,21 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
   let result;
   try {
     result = retireInstance(intent.root, intent.instance, {
-      deleteBranch: !!intent.options?.deleteBranch, keepDir: !!intent.options?.keepDir, tmuxSession: intent.options?.tmuxSession,
+      home: intent.options?.home, deleteBranch: !!intent.options?.deleteBranch, keepDir: !!intent.options?.keepDir, tmuxSession: intent.options?.tmuxSession,
     });
   } catch (e) {
-    record({ ok: false, error: { code: e.code, message: e.message }, retry: `oats retire ${intent.instance}` });
+    record({ ok: false, error: { code: e.code, message: e.message }, retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
     console.error(`deferred retirement of ${intent.instance} failed: ${e.message}`);
     return false;
   }
   if (result.rollbackIncomplete) {
-    record({ ok: false, result, retry: `oats retire ${intent.instance}` });
+    record({ ok: false, result, retry: `oats retire ${intent.instance}${intent.options?.home ? ` --home ${intent.options.home}` : ""}` });
     console.error(`deferred retirement of ${intent.instance} is INCOMPLETE; the home is retained:\n  ${result.rollbackIncomplete.join("\n  ")}`);
     return false;
   }
   if (intent.options?.keepDir) {
-    const retained = findInstanceHome(intent.root, intent.instance);
+    // The kept home is the one the intent names, never a same-named twin.
+    const retained = intent.options?.home ? { home: intent.options.home } : findInstanceHome(intent.root, intent.instance);
     if (retained) rmSync(retirePendingMarkerPath(retained.home), { force: true });
   }
   // Success leaves nothing beside the home: the home is gone, the marker went
@@ -6655,8 +6771,23 @@ export function retireInstance(root, name, o = {}) {
   // retirement is deferred to a detached external completion (below); with
   // --keep-dir the old in-process path runs and kills the window LAST.
   const self = o.self === true;
-  const found = findInstanceHome(root, name);
-  if (!found) throw new Error(`no instance named "${name}"`);
+  // Names are unique per agent dir only: two agents can own an instance of
+  // the same name (dev --purpose foo-1 and agent dev-foo). Retirement is
+  // destructive, so a name that resolves to several homes is refused unless
+  // the caller says which home (--home), and a home is accepted only when it
+  // is one of that name's homes under this root.
+  const matches = findInstanceHomes(root, name);
+  if (!matches.length) throw new Error(`no instance named "${name}"`);
+  const sameHome = (a, b) => { try { return realpathSync(a) === realpathSync(b); } catch { return resolve(a) === resolve(b); } };
+  let found;
+  if (o.home) {
+    found = matches.find((m) => sameHome(m.home, o.home));
+    if (!found) throw oatsError("E_HOME_MISMATCH", `instance "${name}" has no home at ${o.home} under this agents root (its home${matches.length === 1 ? " is" : "s are"} ${matches.map((m) => m.home).join(", ")})`);
+  } else if (matches.length > 1) {
+    throw oatsError("E_AMBIGUOUS_INSTANCE", `"${name}" names ${matches.length} instances under this agents root (${matches.map((m) => `${m.agent.name}: ${m.home}`).join("; ")}); retire with --home <path> to say which`);
+  } else {
+    found = matches[0];
+  }
   const metaPath = join(found.home, "instance.json");
   // A QUARANTINED home (spawn failed after a required hook and compensation did
   // not finish) has no instance.json — it never got that far. Its marker carries