@awebai/oats 0.25.7 → 0.25.9

package/bin/oats.mjs

@@ -2938,7 +2938,7 @@ async function paneCmd() {
  * remotes, confirm membership, resolve `packages:`, approve (TTY) or list what
  * needs approval (exit 2), write `oats-lock.json`. Nothing is installed, no soul
  * is created, nothing is spawned, no `oats-config.yaml` is written: the member
- * clones and the setup expert are the operator's next steps, printed here. */
+ * clones and the operator expert are the operator's next steps, printed here. */
 async function onboardCmd() {
   const bail = (code, message, details) => (JSON_MODE ? jsonFail(code, message, details) : die(message));
   const usage = "usage: oats onboard [<dir>] --workspace <repo ref> [--json]   (or --dir <dir>)";
@@ -3015,11 +3015,11 @@ async function onboardCmd() {
   // (4) The taught layout as next steps (design doc §4), and the envelope.
   const standalone = synced.discovery.standalone === true;
   const members = synced.report.members;
-  // The setup expert is suggested only when THIS workspace lists a soul by that name (a
+  // The operator expert is suggested only when THIS workspace lists a soul by that name (a
   // confirmed member's or, standalone, the repo's own); otherwise any listed soul is spawnable.
   const soulNames = synced.items.souls.map((s) => s.name);
-  const setupExpert = soulNames.includes("oats-setup-expert");
-  const spawnHint = setupExpert ? `oats spawn oats-setup-expert --dir ${shortPath(dir)}` : null;
+  const setupExpert = soulNames.includes("oats-operator-expert");
+  const spawnHint = setupExpert ? `oats spawn oats-operator-expert --dir ${shortPath(dir)}` : null;
   const anySoulHint = `spawn any listed soul: oats spawn <soul> --dir ${shortPath(dir)}${soulNames.length ? ` (e.g. ${soulNames.slice(0, 3).join(", ")})` : ""}`;
   // A member's clone goes beside oats-local.yaml under its repo name; `agents/` is the instance
   // homes, so a member called "agents" is cloned as `agents-repo/` (design doc §4). The HOST is
@@ -3060,7 +3060,7 @@ Next:
   2. Check who may read the host: ${synced.discovery.key}${hostIsMember ? " is itself a member" : " is a dedicated host"}. The workspace file
      names every member, so if any member is private the host must be a private repo that is not
      a public member; public contributors then get the standalone case (from: here + oats.core).
-  3. ${setupExpert ? "Spawn the setup expert to guide the rest (souls, teams, provider settings, approvals):" : "No soul named oats-setup-expert is listed here —"}
+  3. ${setupExpert ? "Spawn the operator expert to guide the rest (souls, teams, provider settings, approvals):" : "No soul named oats-operator-expert is listed here —"}
        ${spawnHint ?? anySoulHint}${synced.approvalNeeded.length ? `\n  (first: \`oats sync --dir ${shortPath(dir)}\` in a terminal to approve ${synced.approvalNeeded.map((a) => `${a.id} ${a.version}`).join(", ")})` : ""}`);
   process.exitCode = synced.approvalNeeded.length ? 2 : 0;
 }
@@ -3911,7 +3911,7 @@ Usage:
       [--json]                               and agents/, then runs the oats sync path (lock v3;
                                             exit 2 while approvals are pending) and prints the
                                             next steps (clone members you work IN, spawn
-                                            oats-setup-expert); creates no soul, spawns nothing
+                                            oats-operator-expert); creates no soul, spawns nothing
   oats create <name> [--local] [--no-oats-core] create an agent soul; --local = full
       [--description <d>] [--repo <r>]      soul under local-agents/ (uncommitted,
       [--work <mode>] [--runtime pi|claude|codex] gitignored; same memory + lifecycle)

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

@@ -137,7 +137,7 @@ try {
     const manifest = JSON.parse(readFileSync(new URL("../oats.json", import.meta.url), "utf8"));
     const selected = requireCapturedAwebAction(loaded, event, manifest);
     const settings = parseBindingJson(Buffer.from(process.env.OATS_SETTINGS || "{}"));
-    if (!settings || typeof settings !== "object" || Array.isArray(settings) || Object.keys(settings).some(k => k !== "delivery")) throw new Error("captured settings support delivery only; no identity copying or ambient fallback");
+    if (!settings || typeof settings !== "object" || Array.isArray(settings) || Object.keys(settings).some(k => !["delivery", "team", "root", "roots"].includes(k))) throw new Error("captured settings support delivery/team/root readiness only; no identity copying or ambient fallback");
     const checked = assessCapturedSessionReadiness({ binding: selected.binding, invocation: selected.context, settings }, {
       query(args, options) { selected.assertCurrent(); const result = querySelectedKernel(args, options); selected.assertCurrent(); return result; },
     });
@@ -194,7 +194,7 @@ function gitRootOf(startDir) {
     d = parent;
   }
 }
-function awebRoot() {
+function classicAwebRoot() {
   const candidates = [];
   const push = (p) => { if (p && !candidates.includes(resolve(p))) candidates.push(resolve(p)); };
   push(process.env.OATS_TEAM_SCOPE);
@@ -206,6 +206,36 @@ function awebRoot() {
   for (const c of candidates) if (existsSync(join(c, ".aw"))) return c;
   return undefined;
 }
+const hasWorkspaceV2Facts = () => !!(process.env.OATS_WORKSPACE_KEY || process.env.OATS_WORKSPACE_NAME || process.env.OATS_TEAM_LABEL);
+const isClassicDeployment = () => !!process.env.OATS_TEAM_SCOPE && !hasWorkspaceV2Facts();
+const teamConfigRemedy = () => `set messaging.byTeam.<label>.team in the workspace file or settings.oats.aweb.team${isClassicDeployment() ? " (classic: set team.id in oats-config.yaml)" : ""}`;
+function declaredRootCandidate(team = payloadTeam().team) {
+  const roots = settings.roots && typeof settings.roots === "object" && !Array.isArray(settings.roots) ? settings.roots : {};
+  if (team && typeof roots[team] === "string" && roots[team].trim()) return { root: roots[team].trim(), key: `settings.oats.aweb.roots[${JSON.stringify(team)}]`, declared: true };
+  if (typeof settings.root === "string" && settings.root.trim()) return { root: settings.root.trim(), key: "settings.oats.aweb.root", declared: true };
+  return undefined;
+}
+function rootSettingCandidate(team = payloadTeam().team) {
+  const declared = declaredRootCandidate(team);
+  if (declared) return declared;
+  const fallback = process.env.OATS_WORKSPACE || (!isClassicDeployment() ? process.env.OATS_TEAM_SCOPE : undefined) || process.cwd();
+  return fallback ? { root: fallback, key: "settings.oats.aweb.root", declared: false } : undefined;
+}
+function awebRootProblem(candidate) {
+  if (!candidate?.root) return `no messaging root at ${process.cwd()}: run oats aweb setup there or set settings.oats.aweb.root`;
+  if (!isAbsolute(candidate.root)) return `${candidate.key} must be an absolute directory whose .aw is the aweb minting root`;
+  return `no messaging root at ${resolve(candidate.root)}: run oats aweb setup there or set ${candidate.key}`;
+}
+function resolveAwebRoot() {
+  const declared = declaredRootCandidate();
+  if (declared && isAbsolute(declared.root) && existsSync(join(resolve(declared.root), ".aw"))) return resolve(declared.root);
+  if (declared?.declared) return undefined;
+  if (isClassicDeployment()) return classicAwebRoot();
+  const candidate = rootSettingCandidate();
+  if (candidate && isAbsolute(candidate.root) && existsSync(join(resolve(candidate.root), ".aw"))) return resolve(candidate.root);
+  return undefined;
+}
+function awebRoot() { return resolveAwebRoot(); }
 
 /** Team memberships from `aw team list --json`. The current CLI returns
  * `memberships`; older output used `teams`. Spawn resolution and `oats aweb
@@ -411,9 +441,9 @@ function retainedSeatSpawn(source, takeOver) {
   const service = process.env.OATS_AWEB_URL || yamlScalar(srcWorkspace, "aweb_url");
   if (!service) fatal(`cannot determine the aweb service for ${source} (no aweb_url in its workspace.yaml)`);
   const role = yamlScalar(srcWorkspace, "role_name");
-  let team = process.env.OATS_TEAM_ID;
+  let team = payloadTeam().team;
   if (!team && existsSync(join(source, "teams.yaml"))) team = yamlScalar(readFileSync(join(source, "teams.yaml"), "utf8"), "active_team") || yamlScalar(readFileSync(join(source, "teams.yaml"), "utf8"), "active");
-  if (!team || !team.includes(":")) fatal(`cannot determine the team for the retained identity (set team.id in oats-config.yaml, or an active team in ${join(source, "teams.yaml")})`);
+  if (!team || !team.includes(":")) fatal(`cannot determine the team for the retained identity (${teamConfigRemedy()}, or keep an active team in ${join(source, "teams.yaml")})`);
   const dest = join(home, ".aw");
   const legacyHome = dirname(source);
   // The lock is taken FIRST: a concurrent second spawn must see it before any
@@ -490,7 +520,7 @@ function retainedSeatSpawn(source, takeOver) {
     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" } : undefined;
+    const env = { ...(deliveryMode === "session" ? { AWEB_DELIVERY: "session" } : {}), AWEB_IDENTITY_HOME: dest };
     const deliveryBrief = deliveryMode === "session"
       ? ` Notification delivery: external (AWEB_DELIVERY=session); until the host wake broker registers this instance NOTHING wakes you: check \`aw mail inbox\` and \`aw chat pending\` at every task boundary.`
       : "";
@@ -500,7 +530,7 @@ function retainedSeatSpawn(source, takeOver) {
     if (hostNote) warnings.push(`oats-aweb: seated${hostNote}`);
     out({
       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 } : {}),
+      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 } : {}),
       ...(warnings.length ? { warning: warnings.join(" | ") } : {}),
@@ -517,7 +547,11 @@ if (event === "spawn") {
   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`);
+  if (!root) {
+    const candidate = rootSettingCandidate();
+    const classicHint = isClassicDeployment() ? " (classic fallback also checked the bounded team-scope candidates)" : "";
+    fatal(`${awebRootProblem(candidate)}, so no identity could be minted and this instance would have no messaging${classicHint}`);
+  }
   try {
     // Team correctness: the config's `team:` block wins (id, then name), else the
     // root's active team. ALWAYS pass --team-id explicitly — never inherit whatever
@@ -527,15 +561,16 @@ if (event === "spawn") {
     const resolvedTeam = payloadTeam();
     let team = resolvedTeam.team;
     const teamPayloadMismatch = resolvedTeam.payload && resolvedTeam.env && resolvedTeam.payload !== resolvedTeam.env;
+    if (!team && process.env.OATS_TEAM_LABEL) fatal(`cannot determine target team for workspace team label ${JSON.stringify(process.env.OATS_TEAM_LABEL)}, so no identity could be minted — ${teamConfigRemedy()}`);
     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");
+    if (!team) fatal(`cannot determine target team, so no identity could be minted — ${teamConfigRemedy()}, or activate a team at the aweb root`);
     // A bare team name (no namespace) resolves against the root's memberships.
     if (!team.includes(":")) {
       const teams = JSON.parse(run(["aw", "team", "list", "--json"], root));
       const match = teamIdsOf(teams).filter((tid) => String(tid).startsWith(`${team}:`));
       if (match.length === 1) team = match[0];
-      else if (match.length > 1) fatal(`team name "${team}" is ambiguous at ${root}: ${match.join(", ")}, so no identity could be minted — set team.id in oats-config.yaml`);
-      else fatal(`no membership matching team "${team}" at ${root}, so no identity could be minted — join or create it first (aweb-team-membership skill), or set team.id`);
+      else if (match.length > 1) fatal(`team name "${team}" is ambiguous at ${root}: ${match.join(", ")}, so no identity could be minted — ${teamConfigRemedy()}`);
+      else fatal(`no membership matching team "${team}" at ${root}, so no identity could be minted — join or create it first (aweb-team-membership skill), or ${teamConfigRemedy()}`);
     }
     // Both of these carry the invite token — one mints it, the other spends it —
     // so neither their output nor their diagnostics may reach a log.
@@ -597,7 +632,7 @@ if (event === "spawn") {
     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" } : undefined;
+    const env = { ...(deliveryMode === "session" ? { AWEB_DELIVERY: "session" } : {}), AWEB_IDENTITY_HOME: join(home, ".aw") };
     const channelWarning = undefined;
     if (deliveryMode === "session") wakeRegister(home, join(home, ".aw"));
     const deliveryBrief = deliveryMode === "session"
@@ -605,7 +640,7 @@ if (event === "spawn") {
       : "";
     out({
       meta: { team: joined.team_id, alias, delivery: deliveryMode, identity: identityMeta({ mode: "local", alias, team: joined.team_id }) },
-      ...(env ? { 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 } : {}),
       ...(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 } : {}),
@@ -673,9 +708,9 @@ if (event === "spawn") {
   // wherever they run (plus human members). Local liveness comes from
   // `oats status --team`; this is the network view.
   const root = awebRoot();
-  if (!root) { console.error("oats aweb roster: no initialized aweb root (.aw) found"); process.exit(1); }
+  if (!root) { console.error(`oats aweb roster: ${awebRootProblem(rootSettingCandidate())}`); process.exit(1); }
   const team = process.env.OATS_TEAM_ID || process.env.OATS_TEAM_NAME || JSON.parse(run(["aw", "team", "list", "--json"], root)).active_team;
-  if (!team) { console.error("oats aweb roster: cannot determine team (no config team block, no active team)"); process.exit(1); }
+  if (!team) { console.error(`oats aweb roster: cannot determine team (${teamConfigRemedy()}, or activate a team at the aweb root)`); process.exit(1); }
   const teamFlag = team.includes(":") ? ["--team-id", team] : ["--team", team];
   const r = JSON.parse(run(["aw", "id", "team", "members", ...teamFlag, "--json"], root, 60000));
   if (process.argv.includes("--json")) { console.log(JSON.stringify(r, null, 2)); process.exit(0); }
@@ -687,18 +722,59 @@ if (event === "spawn") {
   process.exit(0);
 } else if (event === "setup") {
   // Guided onboarding — idempotent, prints what it finds and the one next step.
-  const scope = process.env.OATS_TEAM_SCOPE || process.cwd();
-  const teamName = process.env.OATS_TEAM_NAME;
-  const teamId = process.env.OATS_TEAM_ID;
-  console.log(`aweb onboarding — team scope: ${scope}${teamName ? `, config team: ${teamName}${teamId ? ` (${teamId})` : ""}` : ""}\n`);
+  if (isClassicDeployment() && settings.root === undefined && settings.roots === undefined && settings.team === undefined) {
+    const scope = process.env.OATS_TEAM_SCOPE || process.cwd();
+    const teamName = process.env.OATS_TEAM_NAME;
+    const teamId = process.env.OATS_TEAM_ID;
+    console.log(`aweb onboarding — team scope: ${scope}${teamName ? `, config team: ${teamName}${teamId ? ` (${teamId})` : ""}` : ""}\n`);
+    if (!teamName) {
+      console.log("1. Declare your team in the deployment scope's oats-config.yaml first:");
+      console.log("     team:\n       name: <your-team>\n   then re-run `oats aweb setup` from there.");
+      process.exit(0);
+    }
+    if (!existsSync(join(scope, ".aw"))) {
+      console.log(`No aweb workspace at the team scope yet. Initialize it (interactive — creates or connects an aweb account):`);
+      console.log(`     cd ${scope} && aw init`);
+      console.log("   First time on aweb? `aw init` walks you through creating a hosted aweb.ai account.");
+      console.log("   Own your domain? Use `aw init --byod` (see the aweb-team-membership skill).");
+      process.exit(0);
+    }
+    let teams = { memberships: [] };
+    try { teams = JSON.parse(run(["aw", "team", "list", "--json"], scope)); } catch { /* fall through */ }
+    const want = teamId || teamName;
+    const match = teamIdsOf(teams).find((tid) => String(tid) === want || String(tid).startsWith(`${want}:`));
+    if (match) {
+      console.log(`✓ aweb workspace initialized and member of ${match}.`);
+      if (teams.active_team && teams.active_team !== match) console.log(`  Note: active team is ${teams.active_team}; instances join ${match} explicitly, but consider \`aw team switch ${match}\`.`);
+      console.log("  Done — spawned instances will join this team automatically (alias = instance name).");
+      console.log("  Roster: `oats aweb roster`  ·  local: `oats status --team`");
+    } else {
+      console.log(`Workspace initialized, but no membership matching "${want}".`);
+      console.log(`  Create the team:   cd ${scope} && aw team create ${teamName}`);
+      console.log("  Or join an existing one: get an invite token from a member, then `aw team join <token>`");
+      console.log("  (details: aweb-team-membership skill)");
+    }
+    process.exit(0);
+  }
+  const resolvedTeam = payloadTeam();
+  const teamName = resolvedTeam.team;
+  const teamId = typeof settings.team === "string" && settings.team.trim() ? settings.team.trim() : process.env.OATS_TEAM_ID;
+  const candidate = rootSettingCandidate(teamName);
+  const scope = candidate?.root ? resolve(candidate.root) : process.cwd();
+  console.log(`aweb onboarding — messaging root: ${scope}${teamName ? `, team: ${teamName}` : ""}\n`);
   if (!teamName) {
-    console.log("1. Declare your team in the deployment scope's oats-config.yaml first:");
-    console.log("     team:\n       name: <your-team>\n   then re-run `oats aweb setup` from there.");
+    console.log(`1. Choose the aweb team for this deployment: ${teamConfigRemedy()}.`);
+    console.log("   The workspace file's `messaging:` / `messaging.byTeam.<label>.team` payload is portable; host-specific overrides belong in `settings.oats.aweb.team`.");
+    process.exit(0);
+  }
+  if (!isAbsolute(scope)) {
+    console.log(`${candidate?.key || "settings.oats.aweb.root"} must be an absolute directory whose .aw is the aweb minting root.`);
     process.exit(0);
   }
   if (!existsSync(join(scope, ".aw"))) {
-    console.log(`No aweb workspace at the team scope yet. Initialize it (interactive — creates or connects an aweb account):`);
+    console.log(`No aweb workspace at the messaging root yet (${candidate?.key || "settings.oats.aweb.root"}). Initialize it (interactive — creates or connects an aweb account):`);
     console.log(`     cd ${scope} && aw init`);
+    console.log("   Or set settings.oats.aweb.root to an absolute directory whose .aw is the aweb minting root, then re-run `oats aweb setup`.");
     console.log("   First time on aweb? `aw init` walks you through creating a hosted aweb.ai account.");
     console.log("   Own your domain? Use `aw init --byod` (see the aweb-team-membership skill).");
     process.exit(0);

package/capabilities/oats-aweb/lib/binding-wire.mjs

@@ -1,3 +1,5 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
 import { TextDecoder } from 'node:util';
 import { assessCapturedSessionReadiness } from './session-readiness.mjs';
 import {
@@ -79,8 +81,12 @@ export function parseBindingJson(bytes,limits=BINDING_WIRE_LIMITS) {
 function settings(value) {
   if(!obj(value)) wireError('invalid-binding');
   if(Object.hasOwn(value,'identity')) wireError('provider-not-qualified');
-  keys(value,['delivery'],[]);
+  keys(value,['delivery','team','root','roots'],[]);
   if(value.delivery!==undefined && !['channel','session'].includes(value.delivery)) wireError('needs-configuration');
+  if(value.team!==undefined && (typeof value.team!=='string' || !value.team.trim())) wireError('needs-configuration');
+  if(value.root!==undefined && (typeof value.root!=='string' || !value.root.trim())) wireError('needs-configuration');
+  if(value.roots!==undefined && !obj(value.roots)) wireError('needs-configuration');
+  if(obj(value.roots)) for(const [team,root] of Object.entries(value.roots)) if(!team || typeof root!=='string' || !root.trim()) wireError('needs-configuration');
   return value;
 }
 function request(value,phase) {
@@ -142,6 +148,23 @@ function binding(value) {
   return value;
 }
 function checkResult(message) {return {status:'needs-configuration',problems:[{code:'needs-configuration',message}]};}
+function checkProblems(problems) {return problems.length?{status:'needs-configuration',problems}:null;}
+function teamFromSettings(settings) {return typeof settings.team==='string' && settings.team.trim()?settings.team.trim():(process.env.OATS_TEAM_ID || process.env.OATS_TEAM_NAME || undefined);}
+function classicEnv() {return !!process.env.OATS_TEAM_SCOPE && !(process.env.OATS_WORKSPACE_KEY || process.env.OATS_WORKSPACE_NAME || process.env.OATS_TEAM_LABEL);}
+function rootCandidate(settings,team) {
+  const roots=obj(settings.roots)?settings.roots:{};
+  if(team && typeof roots[team]==='string' && roots[team].trim()) return {root:roots[team].trim(),key:`settings.oats.aweb.roots[${JSON.stringify(team)}]`,declared:true};
+  if(typeof settings.root==='string' && settings.root.trim()) return {root:settings.root.trim(),key:'settings.oats.aweb.root',declared:true};
+  const candidates=classicEnv()?[process.env.OATS_TEAM_SCOPE,process.env.OATS_WORKSPACE].filter(Boolean):[process.env.OATS_WORKSPACE || process.env.OATS_TEAM_SCOPE || process.cwd()];
+  for(const root of candidates) if(isAbsolute(root) && existsSync(join(resolve(root),'.aw'))) return {root,key:'settings.oats.aweb.root',declared:false};
+  return {root:candidates[0] || process.cwd(),key:'settings.oats.aweb.root',declared:false};
+}
+function readinessFromSettings(settings) {
+  const team=teamFromSettings(settings),candidate=rootCandidate(settings,team),problems=[];
+  if(!candidate.root || !isAbsolute(candidate.root) || !existsSync(join(resolve(candidate.root),'.aw'))) problems.push({code:'needs-configuration',message:`no messaging root at ${candidate.root?resolve(candidate.root):process.cwd()}: run oats aweb setup there or set ${candidate.key}`});
+  if(!team) problems.push({code:'needs-configuration',message:'no team: set messaging.byTeam.<label>.team in the workspace file or settings.oats.aweb.team'});
+  return checkProblems(problems) || {status:'ready',problems:[]};
+}
 function checkPhase(req) {
   keys(req.input,['binding','context','action','invocation'],['binding','context','action']);
   if(!obj(req.input.action) || typeof req.input.action.kind!=='string') wireError('invalid-binding');
@@ -150,6 +173,9 @@ function checkPhase(req) {
   const invocation=Object.hasOwn(req.input,'invocation')?validateAwebInvocationContext(req.input.invocation,current,{context:req.input.context,action:req.input.action}):null;
   if(['command','hook','operation'].includes(req.input.action.kind) && (!invocation || invocation.instance===null || invocation.intent===null)) return checkResult('an admitted captured instance intent is required for execution');
   if(current.payload.privateTeam===null) return checkResult('an explicit private-team binding is required');
+  const hostReady=readinessFromSettings(req.settings);
+  if(hostReady.status!=='ready') return hostReady;
+  if(!invocation) return hostReady;
   // Read-only public kernel observations, not an account/grant attestation.
   // Native setup is performed only by the separately admitted execution path.
   return assessCapturedSessionReadiness({binding:current,invocation,settings:req.settings});

package/capabilities/oats-aweb/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.aweb",
   "command": "aweb",
-  "version": "1.12.0",
+  "version": "1.12.1",
   "compatibility": {
     "oats": ">=0.24.4"
   },
@@ -139,6 +139,12 @@
     "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."
     },
+    "root": {
+      "description": "Host-owned absolute directory whose .aw is the aweb minting root. Put this only in oats-local.yaml settings.oats.aweb.root; use oats aweb setup to initialize it."
+    },
+    "roots": {
+      "description": "Host-owned map of aweb team id to absolute directory whose .aw is that team's minting root, for deployments that mint into several teams. Put this only in oats-local.yaml settings.oats.aweb.roots."
+    },
     "identity": {
       "default": {
         "mode": "local"

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

@@ -175,7 +175,7 @@ else {
     } else if(event==='unlock') result=unlock(resolve(flags.lock),flags.token);
     else fail('E_USAGE',`unknown command ${event}; see --help`);
     answer=hook?result:{schemaVersion:1,ok:true,result};
-  } catch(e) {exit=1;answer=hook?{meta:{...(event==='retire'?{retired:false,reason:e.message}:{})},warning:`oats-okf: ${e.message}`}:{schemaVersion:1,ok:false,error:{code:e.code || 'E_OKF',message:e.message}};}
+  } catch(e) {const code=e.code || 'E_OKF';exit=1;answer=hook?{meta:{...(event==='retire'?{retired:false,reason:e.message}:{})},warning:`oats-okf ${code}: ${e.message}`}:{schemaVersion:1,ok:false,error:{code,message:e.message}};}
   // Let Node drain the pipe; no process.exit after a possibly large view.
   process.stdout.write(JSON.stringify(answer)+'\n');process.exitCode=exit;
 }

package/capabilities/oats-okf/lib/binding-wire.mjs

@@ -291,7 +291,7 @@ function checkPhase(req) {
     if(gitBases.length) scratch=fs.mkdtempSync(join(fs.realpathSync(tmpdir()),'oats-okf-binding-check-'));
     for(const [alias,base] of Object.entries(bindings.bases)) {
       stage=base.kind==='directory'?'validate':'stage';
-      accepted[alias]=(base.kind==='directory'?validateBase(base.path,base):stageBase(base,join(scratch,alias))).meta;
+      accepted[alias]=(base.kind==='directory'?validateBase(base.path,base):stageBase(base,join(scratch,alias),{alias})).meta;
     }
     stage='runtime';
     checkKnowledgeRuntime({rendered:runtime,accepted});

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

@@ -33,7 +33,7 @@ export function migrate(bindings,{legacy,alias,node,output}) {
   // 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);
+  const stage=stageBase(base,output,{alias});
   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
@@ -106,7 +106,7 @@ export function cutoverMigration(file,soul) {
   try {
     for(const alias of new Set([...decl.owns,...decl.reads].map(r=>splitRef(r)[0]))) {
       if(!Object.hasOwn(bindings.bases,alias)) fail('E_CONFIG',`unresolved base: ${alias}`);
-      const staged=stageBase(bindings.bases[alias],join(scratch,alias));
+      const staged=stageBase(bindings.bases[alias],join(scratch,alias),{alias});
       accepted[alias]=staged.meta;
       if(alias===m.alias) {
         if(hash(staged.meta.nodes[m.node] || null)!==hash(frozen)) fail('E_OWNER','accepted migration ownership/path differs from delivered node');

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

@@ -101,7 +101,7 @@ export function views(bindings, decl, target) {
     for(const [alias,base] of Object.entries(bindings.bases)) {
       const scratch=fs.mkdtempSync(join(bindings.stateDir,'read-'));
       try {
-        const staged=stageBase(base,join(scratch,'base'));
+        const staged=stageBase(base,join(scratch,'base'),{alias});
         all[alias]=staged.meta;
         const path=`bases/${alias}`;
         materialize(join(pending,path),staged.files);
@@ -192,7 +192,8 @@ export function register(home) {
   if(fs.existsSync(join(home,'knowledge'))) fail('E_VIEW','unregistered knowledge view exists; preserve it and inspect before registering');
   if(['.okf-harvest-record.json','.okf-harvest-record.next.json'].some(p=>fs.existsSync(join(home,p))) && !fs.existsSync(join(home,'.okf-v1-migration.json'))) fail('E_MIGRATION','legacy source watermarks require explicit oats okf migrate --source-home PATH before v2 registration; no cursor is silently trusted');
   const meta=fs.existsSync(join(home,'instance.json'))?readJSON(join(home,'instance.json')):{};
-  const soul=fs.realpathSync(process.env.OATS_SOUL || join(home,'soul'));
+  if(!process.env.OATS_SOUL) fail('E_OATS_SOUL_MISSING','OATS_SOUL is not set; oats.okf hooks and commands run only under the OATS kernel');
+  const soul=fs.realpathSync(process.env.OATS_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;
@@ -204,7 +205,6 @@ 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');
-  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.
@@ -217,6 +217,7 @@ export function register(home) {
   fs.mkdirSync(dir,{recursive:true,mode:0o700});
   try {
     source.acceptedView=views(bindings,decl,pending);
+    pinOwner(ownersFile,decl.owner,{id:soulId,soulName:agent,path:soul});
     source.acceptedNodes=Object.fromEntries(Object.entries(source.acceptedView).map(([alias,r])=>[alias,r.nodes]));
     save(file,source);
     save(join(dir,'status.json'),{version:1,captured:{notes:[],threads:{},inputs:[]},processed:[],delivered:{},accepted:{},retired:false,auto:true,activeRun:null});
@@ -245,7 +246,7 @@ export function pinOwner(ownersFile,owner,{id,soulName,path}) {
     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!==undefined && prior!==value && !(id && samePath)) fail('E_OWNER',`stable owner ID already identifies a different soul in this state namespace: existing soul ${prior}; new soul ${value}. Remedies: retire the existing registration first, or use a fresh state directory.`);
     if(prior!==value) {owners[owner]=value;save(ownersFile,owners);}
     return value;
   });

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

@@ -9,6 +9,31 @@ const validator = fileURLToPath(new URL('../skills/okf/scripts/okf-validate.mjs'
 // transport subprocesses. Override even an explicitly supplied command env.
 const gitEnv = (env = cleanEnv()) => ({...env,GIT_NO_REPLACE_OBJECTS:'1'});
 export const git = (cwd,args,opts={}) => exec('git',['--no-replace-objects','-c','core.hooksPath=/dev/null','-c','protocol.ext.allow=never','-C',cwd,...args],{cwd,...opts,env:gitEnv(opts.env)});
+function baseError(code,message,base,alias,step,reason) {throw Object.assign(new Error(message),{code,base:alias,repository:base.repository,step,reason});}
+function baseRemedy(alias) {return `fix the binding for base alias "${alias}" in the bindings file, or remove the base from the bindings`;}
+function classifyGitFailure(error) {
+  const text=String(error?.message || '');
+  if(error?.code==='ETIMEDOUT' || /ETIMEDOUT|timed out|timeout/i.test(text)) return 'timeout';
+  if(/authentication|permission denied|publickey|access denied|could not read Username|authorization|not authorized/i.test(text)) return 'auth';
+  if(/not found|repository .*not exist|does not exist|no such (file|repository)|couldn't find remote ref|Repository not found/i.test(text)) return 'not-found';
+  if(/could not resolve host|failed to connect|connection refused|network is unreachable|no route to host|proxy/i.test(text)) return 'network';
+  return 'unknown';
+}
+function unavailable(base,alias,step,error) {
+  const reason=classifyGitFailure(error),detail=reason==='unknown'?`; original Git failure: ${String(error?.message || 'unknown failure')}`:'';
+  const message=`Git base "${alias}" repository "${base.repository}" is required by the deployment's bindings, but ${step} failed (reason: ${reason}${detail}); ${baseRemedy(alias)}`;
+  baseError('E_BASE_UNAVAILABLE',message,base,alias,step,reason);
+}
+function requireNotShallow(base,alias,cwd) {
+  const shallow=git(cwd,['rev-parse','--is-shallow-repository']);
+  if(shallow==='true') baseError('E_BASE_SHALLOW',`Git base "${alias}" repository "${base.repository}" is required by the deployment's bindings, but the repository is shallow; oats.okf requires full accepted history before staging; ${baseRemedy(alias)}`,base,alias,'clone','shallow');
+}
+function preflightLocalRepository(base,alias) {
+  if(!base.repository.startsWith('/')) return;
+  if(!fs.existsSync(base.repository)) unavailable(base,alias,'clone',Object.assign(new Error('repository not found'),{code:'ENOENT'}));
+  try { requireNotShallow(base,alias,base.repository); }
+  catch(e) { if(e.code==='E_BASE_SHALLOW') throw e; unavailable(base,alias,'clone',e); }
+}
 export const baseLock = b => `${b.path}.okf-lock`;
 export const journalPath = b => `${b.path}.okf-publication.json`;
 export function validateBase(root, base) {
@@ -53,9 +78,10 @@ function materializeGitObjects(base,dest,head) {
     writeBlob(dest,entry.oid,target,entry.mode==='100755'?0o755:0o644);
   }
 }
-function clone(base, dest, selectedHead) {
+function clone(base, dest, selectedHead, { alias = base.id } = {}) {
   safePath(dest);
   if(fs.existsSync(dest)) fail('E_PATH',`staging destination exists: ${dest}`);
+  preflightLocalRepository(base,alias);
   fs.mkdirSync(dirname(dest),{recursive:true});
   // 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
@@ -64,25 +90,30 @@ function clone(base, dest, selectedHead) {
   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()});
+    if(e.code==='E_COMMAND' && /filter/i.test(e.message)) {
+      fs.rmSync(dest,{recursive:true,force:true});
+      try { git(dirname(dest),[...cloneArgs,'--',base.repository,dest],{timeout:gitTimeoutMs()}); }
+      catch(error) { unavailable(base,alias,'clone',error); }
+    } else unavailable(base,alias,'clone',e);
   }
-  git(dest,['fetch','origin',`refs/heads/${base.acceptedBranch}`],{timeout:gitTimeoutMs()});
+  try { requireNotShallow(base,alias,dest); }
+  catch(e) { if(e.code==='E_BASE_SHALLOW') throw e; unavailable(base,alias,'clone',e); }
+  try { git(dest,['fetch','origin',`refs/heads/${base.acceptedBranch}`],{timeout:gitTimeoutMs()}); }
+  catch(e) { unavailable(base,alias,'fetch',e); }
   const head=selectedHead ?? git(dest,['rev-parse','FETCH_HEAD']);
-  verifyRemote(base,dest);
-  materializeGitObjects(base,dest,head);
+  try { requireNotShallow(base,alias,dest);verifyRemote(base,dest);materializeGitObjects(base,dest,head); }
+  catch(e) { if(['E_BASE_SHALLOW','E_OWNER','E_CONFIRM','E_PATH','E_BASE','E_VALIDATION'].includes(e.code)) throw e; unavailable(base,alias,'checkout',e); }
   // Reject a linked bundle even if Git happily checked the link out.
   safePath(join(dest,base.root));
   return head;
 }
-export function stageBase(base, dest) {
+export function stageBase(base, dest, { alias = base.id } = {}) {
   safePath(dest);
   if(fs.existsSync(dest)) fail('E_PATH',`staging destination exists: ${dest}`);
   const acceptedPath=base.kind==='directory'?base.path:(base.repository.startsWith('/')?resolve(base.repository,base.root):null);
   if(acceptedPath && overlaps(acceptedPath,dest)) fail('E_PATH','stage overlaps accepted base');
   if(base.kind==='git') {
-    const head=clone(base,dest); const root=join(dest,base.root);
+    const head=clone(base,dest,undefined,{alias}); const root=join(dest,base.root);
     const validated=validateBase(root,base);
     verifyPublicationTree(base,dest,head,head,validated.files);
     return { ...validated, head, root, checkout:dest };

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

@@ -142,7 +142,7 @@ function prepareWorker(source,run) {
   for(const [alias,base] of Object.entries(source.bindings.bases)) {
     if(run.settled?.includes(alias)) continue;
     const dest=join(work,'bases',alias);
-    const staged=stageBase(base,dest);
+    const staged=stageBase(base,dest,{alias});
     const owned=source.decl.owns.map(splitRef).filter(([a])=>a===alias).map(([,n])=>n);
     for(const n of owned) if(staged.meta.nodes[n]?.owner!==source.owner || JSON.stringify(staged.meta.nodes[n])!==JSON.stringify(source.acceptedNodes[alias][n])) fail('E_OWNER','accepted ownership/path changed from frozen destination; explicit migration required');
     run.stages[alias]={root:staged.root,checkout:staged.checkout,head:staged.head,baseline:staged.files,digest:staged.digest,owned};persist(source,run);
@@ -235,7 +235,7 @@ export function complete(source,id,judgmentFile,opts={}) {
         if(base.kind==='git') verifyGitScope(base,s.checkout,s.head);
         const checkDir=fs.mkdtempSync(join(source.bindings.stateDir,'baseline-'));
         try {
-          const current=stageBase(base,join(checkDir,'base'));
+          const current=stageBase(base,join(checkDir,'base'),{alias});
           if(current.digest!==s.digest || (base.kind==='git' && current.head!==s.head)) fail('E_BASELINE','accepted base changed; rejudge on fresh baseline');
         } finally {fs.rmSync(checkDir,{recursive:true,force:true});}
         const claims=judgment.outcomes.flatMap(o=>o.concepts).filter(c=>c.base===alias).map(c=>c.path);
@@ -310,7 +310,7 @@ export function retry(source,{run:id,rejudge=false,launch=false,adoptHome}={}) {
     const stages={...run.stages},outstanding=Object.keys(stages).filter(a=>!settled.includes(a));
     for(const alias of outstanding) {
       const base=source.bindings.bases[alias];
-      const staged=stageBase(base,join(work,'rejudgments',attempt,'bases',alias));
+      const staged=stageBase(base,join(work,'rejudgments',attempt,'bases',alias),{alias});
       const owned=run.stages[alias].owned;
       for(const n of owned) if(staged.meta.nodes[n]?.owner!==source.owner || JSON.stringify(staged.meta.nodes[n])!==JSON.stringify(source.acceptedNodes[alias][n])) fail('E_OWNER','accepted ownership/path changed from frozen destination; explicit migration required');
       stages[alias]={root:staged.root,checkout:staged.checkout,head:staged.head,baseline:staged.files,digest:staged.digest,owned};

package/capabilities/oats-okf/oats.json

@@ -1,7 +1,7 @@
 {
   "capability": "oats.okf",
   "command": "okf",
-  "version": "2.1.4",
+  "version": "2.1.5",
   "compatibility": {
     "oats": ">=0.24.4"
   },

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-24 13:30Z · **0.25.0–0.25.6 PUBLISHED** (0.25.6 = decision 27 kernel half + Desktop 10B-0 terminal owner leases, native gate 23/23) (workspace model A–C; team-review fixes; operator-rebuild round; OATS_SOUL_ID; quarantine-retry fix; launch meta + catalog pins) · **OKF v2.1.4 + oats.aweb v1.12.0 TAGGED and pinned** · **decision 27 accepted; K1′/K1″/K2 kernel PR next** · **oats.aweb 1.13.0 (#110) queued** · **Desktop 10B-0 resumed** · 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-24 14:10Z · **0.25.0–0.25.7 PUBLISHED** (0.25.7 = v2 deployment root is a configuration boundary) (0.25.6 = decision 27 kernel half + Desktop 10B-0 terminal owner leases, native gate 23/23) (workspace model A–C; team-review fixes; operator-rebuild round; OATS_SOUL_ID; quarantine-retry fix; launch meta + catalog pins) · **OKF v2.1.4 + oats.aweb v1.12.0 TAGGED and pinned** · **decision 27 accepted; K1′/K1″/K2 kernel PR next** · **oats.aweb 1.13.0 (#110) queued** · **Desktop 10B-0 resumed** · 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-24-desktop-phase-f-boundary.md

@@ -81,6 +81,33 @@ identity.mode=… identity.resident=…` (decision 27 — there is no kernel fla
 `SPAWN_ARG_RULES` gains one `provider` rule (capability id, dotted key, value
 grammar); no identity-named rules. Work mode select includes `workspace`.
 
+**F3 amended by the human (2026-09-24). This supersedes design frame 02 and the
+text above wherever they differ.** The dialog leads with the **instance name**:
+the purpose field becomes a name field that shows `<soul>-<purpose>` live and
+then the kernel's final name from the preview. A no-prefix toggle maps to
+`spawn --name <slug>`, gated on the `spawn-name` feature; `--purpose` stays the
+default. **Runtime and model** are always visible, with their resolved value and
+its source. **Relationship** sits in the main form, shown by default: None /
+Child of / Sibling of / Parent of. There is **no** modules/capabilities list and
+no attach-knowledge / child-spawn / open-PR toggles, because those behaviours
+come from capabilities. There is **no** preview button either. The preview runs
+in the background to fill the real defaults, and apply still binds with
+`--expect-decision` (`E_DECISION_STALE` re-previews). A collapsed section named
+**Developer settings** holds:
+- **work**: base | branch and the worktree path. A `checkout` soul is offered
+  "Use a worktree instead?" (`--work worktree`); the work mode itself comes
+  from the soul's `work:`.
+- harness permissions
+- launch config
+- session backend
+- Run on (the execution server)
+- wake-up
+- messaging identity (`--provider <cap> identity.mode=…`, decision 27)
+
+(Second human redirect, same day: relationship moved into the main form, work
+moved into the collapsed section, and the section was renamed from "Advanced".)
+Every modal gets a darker backdrop.
+
 **F4 — Instance card and roster on v2 facts.** The served-identity line (`acts
 as <address> via grant, expires <t>` / `alias <a> on <team>`); module rows with
 "moved since" markers and a **re-spawn** action (preview → apply, then retire

package/docs/design/2026-09-24-phase-d-plan.md

@@ -22,7 +22,7 @@ pushes. Agreed by both on 2026-09-24:
 | oats.aweb 1.13.0 re-land end to end | Antares | assigned |
 | D1 operator node + integrations node | Antares | assigned (draft PR `d1/operator-node` handed over) |
 | aweb and okf package-expert seams | Antares | assigned |
-| D2, D3, D4, desktop + kernel bundle migrations (D1 remainder) | Antares | assigned (both humans agreed, 2026-09-24). D2's machine-bound onboard of the lead's deployment is run by the lead on Antares' word; kernel gaps come to the lead as asks. |
+| D2, D3, D4, desktop + kernel bundle migrations (D1 remainder) | lead, driven by the child instance `oats-expert-phase-d` | assigned (human, 2026-09-24: picked up by the lead's side after all, so as not to wait on the other deployment's human). The lead reviews and merges; Class B items go to Antares for ACK; D3's aweb/okf seams are drafted by the driver and settled with Antares. **Antares is a REQUIRED cross-reviewer** on D4's `oats.setup` rewrite (it must not drift from the operator node) and on D3's `aweb-expert` and `okf-expert` souls (the seams); the rest of the driver's PRs it reads without gating. |
 
 **Push protocol.**
 - **Class A** — notify after, one line: stewardship, docs and knowledge inside
@@ -42,6 +42,26 @@ pushes. Agreed by both on 2026-09-24:
 - `main` on these repositories carries no branch or tag protection: the parity
   gate and the cross-review are the only things between a merge and `main`.
 
+## Human decision (2026-09-24): no package approval
+
+**Package approval is removed from the kernel and from the Desktop.** People
+install a package only when they trust it. Declaring it in the workspace's
+`packages:` IS the trust decision, so there's no second, per-version approval
+step. This supersedes the "executables approved once per version" rule in
+`docs/workspaces.md` (§ Packages, lock, approval, catalog) and everything built
+on it:
+- `oats sync` exit 2 for pending approvals and `approvalNeeded`
+- `--approve <id>@<version>` and the interactive prompt
+- the lock's `approved` record
+- `E_PACKAGE_UNAPPROVED` at spawn and dispatch
+- the Desktop F2 approval flow (`E_APPROVAL_STALE`)
+- the planned pinned `--approve …=<digest>`
+
+What stays: the lock still pins each package to the exact commit and integrity,
+and restore still refuses drift (`E_PACKAGE_INTEGRITY`). Reproducibility is not
+approval. It's a breaking contract change, so it ships in a minor release, and
+the Desktop requires that kernel.
+
 ## Slices, in order
 
 ### D1 — Knowledge centralisation (IN PROGRESS)
@@ -118,14 +138,44 @@ for, never named by convention — decision 9) is the acceptance: `oats onboard`
 
 ### D3 — Souls to `souls/<name>` and the six package-expert souls (decision 20)
 
-Each package repo carries `souls/<pkg>-expert` (okf-expert, aweb-expert,
-jira-expert, linear-expert, authoring-expert, dev-expert), the expert in that
-package, with a node in the central base from day one. **Seams named in the
-charters** (roster amendment): `aweb-expert` READS
+Each package repo carries `souls/oats-<pkg>-expert` (oats-okf-expert,
+oats-aweb-expert, oats-jira-expert, oats-linear-expert, oats-authoring-expert,
+oats-dev-expert), the expert in that package, with a node in the central base
+from day one. **Messaging (human, 2026-09-24; supersedes the lead's per-soul rule):**
+`oats.aweb` is the workspace's messaging **default**
+(`defaults.messaging: { oats.aweb: { from: package } }`, oats#140); a soul
+without messaging says `messaging: none`. The human calls it "the most
+important capability, and most workspaces will use it as default", so the
+provider must work well as a default. Open items (oats.aweb unless noted):
+an unconfigured default must not make every soul unspawnable (onboarding sets
+the messaging root before the first spawn, and/or an unconfigured provider
+reports what is missing instead of refusing); error texts and `setup` must stop
+pointing at `oats-config.yaml`; the deployment names its messaging root
+explicitly rather than by search; `aw mail` usable from `work/`; retired aliases
+reusable. Kernel (lead): in v2 the team scope is the deployment directory and
+the team id comes from the messaging payload, not the classic `team:` block.
+#140 merges together with the first answer to the unspawnable-default item.
+**Teams (human, 2026-09-24): seamless by default.** (R1) Every person gets a
+**personal team per workspace**, created on first use with no invite and no
+manual initialisation — two people, or one person on two workspaces, get
+separate teams; stable across one person's machines. (R2) When a soul whose
+`team:` label the workspace maps to a shared team (`messaging.byTeam.<label>.team`)
+is spawned, the instance **joins that team seamlessly**. Authorization for R2
+(what entitles a person to join without an invite) is oats.aweb's design call
+with the aweb project, fail-closed and visible when the entitlement is missing.
+Kernel (lead): pass the soul's team label and the workspace identity so the
+provider derives the personal team deterministically; an unmapped team means
+"personal". The onboarding skill's manual invite-then-join step is the 1.12.0
+path and is rewritten when the provider ships R1/R2.
+**Naming (lead, 2026-09-24):** the `oats-` prefix on all six —
+it matches the repository names and the roster's `oats-kernel-`/`oats-desktop-`/
+`oats-operator-expert`, and it keeps instance aliases from colliding with the
+messaging project's own `aweb-expert` soul on a shared team. **Seams named in the
+charters** (roster amendment): `oats-aweb-expert` READS
 `aweb-protocol-expert` in base `aweb-oss-knowledge` (repo
 `github.com/awebai/aweb`, root `knowledge/`, branch `main`, OKF 2.1.x
 descriptor at `knowledge/okf-base.json`; owner `1913b77b-…`) through a
-read-only store reference; `okf-expert` names its seam to the knowledge-theory
+read-only store reference; `oats-okf-expert` names its seam to the knowledge-theory
 material in `oats-expert`. Whether the aweb bookshelf decisions the program
 rests on are published into that node is the aweb side's call (asked).
 
@@ -140,6 +190,27 @@ rule, the rebuild guide as procedure with the operator node as rationale.
 Developer souls in `oats.dev` gain `promotesTo: <node>` (roster amendment);
 the harvester delivers to that node as a PR the owning expert reviews.
 
+**D4 also removes the legacy the v2 model already declared gone** (human,
+2026-09-24; boundary §3b's native-rework rule applied to the repository):
+- **Docs, skills, examples** (driver, in D4): delete what v2 removed rather than
+  rewriting it (e.g. the OAS migration guide, the legacy Desktop succession
+  doc, `oats-config.yaml` examples, the `oats-config` skill); rewrite what
+  survives against `oats-local.yaml` and the workspace file; every remaining
+  mention of `oats-config.yaml` either describes its removal or is gone.
+- **Kernel** (lead, one Class B PR after D2 lands, because the OATS workspace
+  itself stops reading `oats-config.yaml` only once D2 converts it): the
+  `oats-config.yaml` scope chain and its readers, the `local-agents/` and
+  `tmp-agents/` layouts, the OAS-scope probes, the installed-capability tier
+  remnants. Removed, not flagged; the `REMOVED_VERBS` answers stay.
+- **In-repo package copies** (`capabilities/oats-{okf,aweb,jira,linear,authoring}`)
+  are NOT removed in D4: `package.json` ships `capabilities/` as the kernel's
+  bundled providers, pinned by the mirror-parity, release-packaging and
+  clean-room tests. Whether 0.26.0 still bundles them is a release decision
+  for D5 (lead); until then they stay unmarked. `private` becomes a schema key
+  (the kernel already reads it); `oats-review` is marked private.
+- **Legacy souls** (`agents/*` and their knowledge bundles) are NOT part of D4:
+  they go when the live instances linking them retire (human rule).
+
 ### D5 — Catalog update and 0.26.0
 
 Catalog pins for the new package versions; **widen Desktop `ACCEPT_RANGE` and

package/docs/desktop-cli-api.md

@@ -960,9 +960,15 @@ between preview and apply is `E_DECISION_STALE`):
   (unchanged since the newest previous instance), or
   `{ instance, was }` (`was` = the previous commit, or `null` when the previous
   instance had no such module).
-- `capabilities[]` / `skills[]` keep their Preview-1 meaning; on a workspace
-  spawn the authoritative module set is `modules[]` (`capabilities[]` may be
-  empty there, since capability rows are filled after materialization).
+- `capabilities[]` / `skills[]` on a **workspace** spawn are **objects**, not
+  Preview-1's strings: `capabilities[]` is `{ name, origin }` (`origin` =
+  `package:<id>@<version>` or `member:<repoKey>@<commit>`), and `skills[]` is
+  `{ name, source }`. Neither is a binding surface, because the authoritative
+  module set is `modules[]` and what apply binds is `decision.effective` /
+  `decision.resolution`. Consumers should read those fields, not project
+  `capabilities[]` / `skills[]`. (Corrected 2026-09-24: this said "keep their
+  Preview-1 meaning", which read as strings; found by the Desktop engineer in
+  F3.)
 - `workspace` is the workspace host's canonical key, `team` the soul's label
   (or `null`), `resolution` the 24-hex revision `decision.resolution` binds.
 - `--provider <cap> <key>=<value>` (repeatable; `a.b=c` nests) is accepted by

package/docs/desktop-succession.md

@@ -8,7 +8,7 @@ the OATS Desktop app (`packages/desktop/` in the framework repo):
 |---|---|
 | `oats.web` marketplace capability (`oats web start`, browser panel) | OATS Desktop app — the same zero-dependency loopback server is bundled at `packages/desktop/server/` and spawned by the app |
 | `oats pane` CLI command and the Control Pane TUI | OATS Desktop app (Active overview / instance roster) |
-| `@awebai/oats/control-pane` package export (`lib/control-pane/model.mjs`) | The roster model moved into `packages/desktop/server/model.mjs`; it is no longer a public kernel export |
+| `@awebai/oats/control-pane` package export (`lib/control-pane/model.mjs`) | The roster model moved into the Desktop app; under workspace model v2 the app reads the kernel's `oats status --json` instead ([deployment model](../packages/desktop/docs/desktop-deployment-model.md)). It is not a public kernel export |
 
 ## Migrating a deployment that used `oats.web`
 
@@ -45,9 +45,9 @@ solarized) exist in the app's theme system.
 `import ... from "@awebai/oats/control-pane"` no longer resolves. The
 model's pure helpers (`readMarkdownSection`, `parseTmuxWindows`,
 `parseGitStatus`, `parseGitDiffStat`, `buildConstellation`, `relativeAge`)
-live in `packages/desktop/server/model.mjs`, which is private to the desktop
-app. If you depended on this export, vendor the helpers or open an issue —
-no known external consumer existed at removal time.
+moved into the private Desktop app and were retired with its workspace-model v2
+rebuild. If you depended on this export, vendor the helpers from a released tag
+or open an issue — no known external consumer existed at removal time.
 
 ## Release gating (maintainers)
 

package/docs/integrations.md

@@ -218,27 +218,52 @@ 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.12.0)
+## oats.aweb settings (1.12.1)
 
 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>`. 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).
+`root`, `roots`, and `residents` are host-file-only: put absolute root/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; the manifest schema does not yet carry a host-only marker).
 
 - `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.
+  the workspace file's `messaging:` / `messaging.byTeam.<label>.team`, or in
+  `settings.oats.aweb.team` for a host override.
+- `root: /absolute/dir`. Host-owned absolute directory whose `.aw` is the aweb
+  minting root. A declared root without `.aw` is fatal; run `oats aweb setup`
+  there or set `settings.oats.aweb.root` to the initialized root.
+- `roots: { <team id>: /absolute/dir }`. Host-owned map for deployments that
+  mint into several aweb teams. When a team is known, `roots[team]` wins over
+  `root`.
+- Minting root resolution for spawn and setup is: `roots[team]` when the team is
+  known and present, else `root`. With no declared root, workspace v2 uses
+  `<OATS_WORKSPACE>` (the deployment directory whose `.aw` is used) and never
+  searches above it; classic deployments with `OATS_TEAM_SCOPE` keep the
+  historical bounded candidate search order exactly (team scope, home, home git
+  root, context, context git root, then workspace).
+- `binding-check` answers `needs-configuration` before spawn with one problem
+  per missing item: `no messaging root at <dir>: run oats aweb setup there or
+  set settings.oats.aweb.root`; `no team: set messaging.byTeam.<label>.team in
+  the workspace file or settings.oats.aweb.team`. With both present it answers
+  `ready` (subject to captured-session checks when an invocation is supplied).
+  In classic deployments this readiness check approximates the full bounded
+  spawn search by checking `OATS_TEAM_SCOPE` before `OATS_WORKSPACE`; the spawn
+  hook itself still keeps the exact 1.12.0 bounded candidate order.
 - `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.
+  `delivery` keys. Local-mode spawn output contributes
+  `env.AWEB_IDENTITY_HOME=<home>/.aw` (and retained-seat local mode contributes
+  the same path) so `aw mail`, `aw chat`, `aw whoami`, `aw wake`, and
+  `aw workspace status` work from the instance's `work/` or any other cwd.
 - `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

package/docs/rebuild-to-v2.md

@@ -77,8 +77,8 @@ members:
   - git:github.com/acme/platform
 packages:
   oats.framework: v1.1.3
-  oats.okf: v2.1.4
-  oats.aweb: v1.12.0
+  oats.okf: v2.1.5
+  oats.aweb: v1.12.1
 teams:
   global: { description: Org-wide }
   engineering: { description: Platform }
@@ -328,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.4 --approve oats.aweb@v1.12.0
+oats sync --approve oats.okf@v2.1.5 --approve oats.aweb@v1.12.1
 ```
 
 `--approve <id>@<version>` is repeatable and approves **exactly** the entry the
@@ -340,7 +340,7 @@ 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
+package that is the published version (`oats.okf@2.1.5`). 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.

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

@@ -0,0 +1,48 @@
+# OATS 0.25.8
+
+## Fixed
+
+- **Desktop: quotes are escaped in attribute contexts** (#139). The views share
+  one escaper (`escapeHtml`) for element content and attribute values.
+
+- **The roster reports an instance where it actually is.** `oats status`
+  reports each instance at the directory the kernel enumerated
+  (`<soul dir>/instances/<name>`), under that directory's name. An
+  `instance.json` whose `home` or `instance` disagrees no longer relocates or
+  renames the instance; the disagreeing values appear only as the diagnostics
+  `recordedHome` / `recordedInstance`. Before this, a hostile or corrupted
+  `instance.json` could make every consumer that acts on `home` (retire,
+  `inspect --home`, the Desktop's file roots) target a path outside the
+  deployment. Found by the Desktop engineer in Phase F slice F1.
+
+## Added
+
+- **Team facts for workspace-model hooks** (human decisions 2026-09-24:
+  `oats.aweb` is the messaging default; teams are seamless). A workspace
+  deployment has no classic `team:` block, so lifecycle hooks of a workspace
+  spawn now receive: `OATS_TEAM_SCOPE` = the deployment directory;
+  `OATS_TEAM_ID` = the messaging slot's merged payload `team` (workspace base ⊕
+  `byTeam[<soul team>]` ⊕ soul ⊕ host ⊕ spawn), **empty when no shared team is
+  mapped — meaning "personal"**; and new `OATS_TEAM_LABEL` (the soul's team
+  label), `OATS_WORKSPACE_NAME` and `OATS_WORKSPACE_KEY` (canonical repository
+  key), so a messaging provider can derive a personal team per person per
+  workspace deterministically. Classic deployments are unchanged.
+- **Desktop F2: Capabilities, Sources, sync and approval, onboarding** (#143).
+  The Workspace view gains a Capabilities table (Capability | Status | Used
+  by, from `oats capabilities --json`, filtered by team and source) and a
+  Sources tab. It can run `oats sync` and approve pending packages: the Desktop
+  admits an approval only when its (id, version, executables digest) exactly
+  match the latest sync report it holds, and refuses a mismatch with
+  `E_APPROVAL_STALE`. A picked folder that isn't yet a workspace can be
+  onboarded through single-use offers held by the main process. The 0.24
+  Deployment inventory and Workspace readiness blocks are removed.
+- **Desktop: design parity with Redesign v3 and brand artwork** (#137, #128).
+  The Desktop F1 deployment model on kernel JSON (#126) is included too.
+- **`oats.aweb` is the workspace messaging default** (#140, human decision).
+  The onboarding skill makes messaging setup its own step before the first
+  spawn (#141).
+- **The onboarding next-step hint names `oats-operator-expert`** (#134).
+- **Phase D:**
+  - The OATS repository hosts a workspace-model workspace (D2, #127).
+  - `oats-operator-expert` and `integrations-expert` souls, with the experts' instructions on the workspace model (D3, #129).
+  - `oats.core` and `oats.setup` rewritten for the workspace model (D4, #133).

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

@@ -0,0 +1,23 @@
+# OATS 0.25.9
+
+A pins-only patch: the kernel is unchanged since 0.25.8.
+
+## Updated
+
+- **`oats.aweb` 1.12.1** (catalog pin + bundled copy; #145). The messaging
+  root is explicit: `settings.oats.aweb.root` / `roots[team]` in
+  `oats-local.yaml`. On a workspace-model deployment it defaults to the
+  deployment directory and is never searched for upward. Error texts name the
+  workspace-model remedies. In local mode an instance gets `AWEB_IDENTITY_HOME`,
+  so `aw` works from any directory. `binding-check` answers
+  `needs-configuration` before spawn, with one problem per missing item (no
+  messaging root; no team), and an unmapped workspace team label fails the spawn
+  closed instead of inheriting the root's active team.
+- **`oats.okf` 2.1.5** (catalog pin + bundled copy; #148).
+  - Every configured base must be usable at spawn. A shallow base is refused
+    with `E_BASE_SHALLOW`; clone, fetch and checkout failures are
+    `E_BASE_UNAVAILABLE` naming the alias, repository, step and reason, never a
+    raw `ETIMEDOUT`.
+  - A missing `OATS_SOUL` is `E_OATS_SOUL_MISSING`; there's no fallback to the
+    home's soul link.
+  - Refusing an owner rename names both souls and both remedies.

package/injects/instance-boundary.md

@@ -6,24 +6,22 @@ hook as `$OATS_INSTANCE_HOME`. It is not your user home (`~`), not the repositor
 root, and not the work tree. Anything that says "your home" means this directory.
 
 - **Your brain and your state live here**: `AGENTS.md` (your composed
-  instructions), `soul/` (your durable knowledge), `TASK.md` (this task),
-  `instance.json` (what you were given and from where), and whatever working
-  state your role keeps — your knowledge layer names those files, if you have
-  one. They belong here, not in the work tree.
+  instructions), `TASK.md` (this task), `instance.json` (what you were given
+  and from where), and whatever working state your role keeps — your knowledge
+  layer names those files, if you have one. They belong here, not in the work
+  tree.
 - **Run OATS operational/lifecycle commands, and commands from active
   capabilities, from instance home** — `oats status`, `oats doctor`, `oats spawn`,
-  `oats retire`, and whatever your own capabilities add; for example, when the
+  and whatever your own capabilities add; for example, when the
   aweb messaging capability is active, run `aw` there too. They resolve their
   scope from the directory you run them in, so running them from the work tree
   points them at the wrong deployment. To act on a different package or config
   scope deliberately, pass an explicit resolved path: `oats <cmd> --dir <path>`.
-- **The home's `soul` link is not your edit surface.** It is there so you can
-  READ your durable knowledge. Writing through it changes durable state outside
-  your branch, where no review sees it and nothing records what changed or why.
-  If your TASK is to change soul content that lives in this repository, that is
-  ordinary code work — do it on tracked paths under `work/`, reviewed like the
-  rest. How your own learnings reach your soul is your knowledge layer's
-  business, and its instructions below say so if you have one.
+- **Soul work is repository work.** If your TASK is to change soul content that
+  lives in this repository, that is ordinary code work — do it on tracked paths
+  under `work/`, reviewed like the rest. How your own learnings reach your soul
+  is your knowledge layer's business, and its instructions below say so if you
+  have one.
 
 **`<instance-home>/work` is your repository or workspace view** — whatever your
 work mode grants you of the code.

package/injects/oats.md

@@ -1,10 +1,10 @@
 ## You run on OATS
 
 You are an agent instance in the OATS (Open Agent Team Specification) framework.
-You incarnate a durable soul (`./soul/`), you work in `./work/`, and you can
-be retired when your task ends. The **oats** skill teaches the essentials —
-your home layout, the agent roster (`oats status`), spawning and
-retiring instances (only when instructed), inspecting your configuration
+You incarnate a durable soul and you work in `./work/`.
+The **oats** skill teaches the essentials —
+your home layout, the agent roster (`oats status`), spawning
+instances (only when instructed), inspecting your configuration
 (`oats doctor`, `./instance.json`), and your lifecycle. **Load the oats skill
 before your first `oats` command of a session** and any time you reason about
 agents, spawning, or the framework itself — do not guess `oats` flags or

package/lib/core.mjs

@@ -4299,7 +4299,8 @@ export function composeInstanceAgentsMd(soulDir, contextDir, soulName, workMode,
     resolved.capabilities = Array.isArray(prepared.capabilityRows) && prepared.capabilityRows.length
       ? prepared.capabilityRows
       : plannedCapabilityRows(prepared.resolution);
-    resolved.workspace = { key: prepared.discovery?.key ?? null, commit: prepared.discovery?.commit ?? null, standalone: prepared.discovery?.standalone === true, revision: prepared.resolution.revision, team: prepared.resolution.soul?.team ?? null, slots: prepared.resolution.slots };
+    resolved.workspace = { key: prepared.discovery?.key ?? null, name: prepared.discovery?.workspace?.name ?? null, deployment: prepared.deployment ?? null, commit: prepared.discovery?.commit ?? null, standalone: prepared.discovery?.standalone === true, revision: prepared.resolution.revision, team: prepared.resolution.soul?.team ?? null, slots: prepared.resolution.slots };
+    resolved.payloads = prepared.resolution.payloads ?? {};
     resolved.layers = Object.fromEntries(Object.entries(prepared.resolution.slots || {}).map(([slot, mod]) => [slot, mod ? { capability: mod } : null]));
   }
   const wanted = [];
@@ -4837,6 +4838,28 @@ export function stableSoulId({ soulId, home, soulDir, agentName } = {}) {
 }
 export const workspaceSoulId = (repoKey, name) => `${repoKey}#${name}`;
 
+/** The team facts a lifecycle hook receives. Classic deployment: the config
+ * chain's `team:` block (name, id, the declaring scope). Workspace model: there is
+ * no `team:` block — the team SCOPE is the deployment directory, the team ID is the
+ * messaging slot's merged payload `team` (workspace base ⊕ byTeam[<soul team>] ⊕
+ * soul ⊕ host ⊕ spawn), and the provider also gets the soul's team LABEL and the
+ * workspace's name and canonical key, so it can derive a per-person, per-workspace
+ * personal team when no shared team is mapped (empty OATS_TEAM_ID = "personal").
+ * Human decision 2026-09-24 (messaging default; seamless teams). */
+export function teamEnv(resolved) {
+  const ws = resolved?.workspace;
+  if (!ws || typeof ws !== "object") {
+    return { OATS_TEAM_NAME: resolved?.team?.name || "", OATS_TEAM_ID: resolved?.team?.id || "", OATS_TEAM_SCOPE: resolved?.team?.scope || "" };
+  }
+  const messaging = ws.slots?.messaging;
+  const payload = messaging ? resolved.payloads?.[messaging] : null;
+  const teamId = payload && typeof payload === "object" && typeof payload.team === "string" ? payload.team : "";
+  return {
+    OATS_TEAM_NAME: "", OATS_TEAM_ID: teamId, OATS_TEAM_SCOPE: ws.deployment || "",
+    OATS_TEAM_LABEL: typeof ws.team === "string" ? ws.team : "",
+    OATS_WORKSPACE_NAME: typeof ws.name === "string" ? ws.name : "", OATS_WORKSPACE_KEY: typeof ws.key === "string" ? ws.key : "",
+  };
+}
 export function runLifecycleHooks(event, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {}, assertRoots }) {
   const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [], contributions: [] };
   const envOwners = new Map();
@@ -4866,7 +4889,7 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, s
           OATS_EVENT: event, OATS_INSTANCE: instance, OATS_INSTANCE_HOME: home, OATS_HOME: home, OATS_AGENT: agentName,
           OATS_CAPABILITY: cap.id, OATS_LAYER: cap.layer || "", OATS_ROOT: rootDir || "",
           OATS_SOUL: soulDir || "", OATS_SOUL_ID: stableSoulId({ soulId, home, soulDir, agentName }), OATS_CONTEXT: contextDir, OATS_WORKSPACE: workspaceDir || "", OATS_LEVEL: cap.level || "",
-          OATS_TEAM_NAME: resolved.team?.name || "", OATS_TEAM_ID: resolved.team?.id || "", OATS_TEAM_SCOPE: resolved.team?.scope || "",
+          ...teamEnv(resolved),
           ...extraEnv,
           // Hooks also run through direct core callers (not only bin/oats).
           // Author this from the running kernel, never PATH, ambient env or
@@ -7428,7 +7451,16 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
           catch (error) { liveness = { running: null, runtimeState: "unreachable", runtimeError: error.message }; }
         }
         const identity = servedIdentityOf(meta);
-        return { ...meta, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
+        // The home IS the directory enumerated here, and the instance its name:
+        // a file inside it cannot relocate or rename itself in the roster (every
+        // consumer acting on `home` — retire, inspect --home, the Desktop's file
+        // roots — would inherit the claim). A disagreeing claim survives only as
+        // a diagnostic.
+        const claims = {
+          ...(meta.home !== undefined && meta.home !== home ? { recordedHome: meta.home } : {}),
+          ...(meta.instance !== undefined && meta.instance !== e.name ? { recordedInstance: meta.instance } : {}),
+        };
+        return { ...meta, ...claims, home, instance: e.name, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
 
       });
   };

package/package-catalog.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.25.7",
+  "version": "0.25.9",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",
@@ -36,8 +36,6 @@
     "docs/",
     "README.md",
     "package-catalog.json",
-    "souls/oats-setup-expert/soul.yaml",
-    "souls/oats-setup-expert/AGENTS.md",
     "packages/record/bin/",
     "packages/record/lib/",
     "packages/record/docs/",

package/souls/oats-setup-expert/AGENTS.md

@@ -1,60 +0,0 @@
-# OATS Setup Expert
-
-Help an operator turn an empty deployment into a deliberately configured OATS
-workspace. Explain the next small decision, inspect the existing state, obtain
-approval for effects, and verify the result before moving on. Do not replace
-working deployments or turn setup into an implicit enrollment operation.
-
-## Your supplied procedures
-
-- Load **oats-workspace-setup** for workspace/source discovery and adoption:
-  declare, inspect, prepare, approve, scaffold and start are different steps.
-- Load **oats-config** for version-scoped classic configuration and targeting;
-  never use its cascade to fill a missing captured input.
-- Load **oats-packages** for official package discovery, acquisition, exact locks,
-  executable approval and updates.
-- Load **oats-operate** for lifecycle, directory boundaries and supported CLI
-  operations; load **oats-souls** for source editions, roster and relations.
-
-Use the procedures actually included in your composition. Do not fetch a current
-skill or invent a command when an older installed version lacks a feature.
-
-## Setup sequence
-
-1. Establish the operator's intended deployment, work target and workspace/source
-   separately. Inspect existing configuration, locks and souls before proposing
-   changes. A workspace is a shared definition, not a shared live runtime.
-2. Explain `oats-workspace.yaml` and each member's separate `oats.yaml` exports
-   and backlink. Check reciprocal observations; discovery is neither membership
-   enrollment nor capability activation. Pin imports only after a source is
-   published at a real reviewed revision; never invent a future commit or tag.
-3. Select capabilities and their exact sources with the operator. New souls
-   declare removable `oats.core` explicitly. Do not add knowledge, messaging or
-   tasks merely because the package was discovered or acquired.
-4. Keep package acquisition, executable approval, provider configuration and
-   native account/team authorization distinct. Inspect the exact artifact and
-   its effects before asking for approval. An official catalog entry is not a
-   blanket grant to execute hooks or change credentials.
-5. Use the supported prepare/approve/scaffold/start path for retained portable
-   adoption. Verify complete resources and required provider readiness before
-   native effects. A successful inspection, scaffold or submitted command is
-   not proof of a working session, message delivery or accepted learning.
-
-## Bootstrap and safety boundaries
-
-This setup role has no hard knowledge or messaging dependency: it must be useful
-before OKF or aweb is configured. Its defaults permit none. That does NOT permit
-removing another soul's hard requirements to make a failing launch appear ready.
-
-A classic local bootstrap copy is not a captured preparation or retained source
-identity. Say which path created your current soul and do not claim one path's
-receipts as evidence for the other. Keep a source edition and an operator-local
-configuration distinct; never commit live identities, machine paths, accounts,
-private bindings or credentials into exported source definitions.
-
-Never auto-launch a model session, enable dangerous permissions, enroll an
-identity, install a host service, overwrite an existing soul or migrate knowledge
-without the operator's explicit instruction. Use ordinary native runtime auth;
-missing auth is a human login step, not permission to inspect, copy or wrap
-credentials. Preserve existing instances, pending jobs, locks and failed receipts.
-Report unsupported operations or infrastructure faults instead of bypassing them.

package/souls/oats-setup-expert/soul.yaml

@@ -1,14 +0,0 @@
-schemaVersion: 1
-name: oats-setup-expert
-description: Guide an operator through OATS workspace adoption and explicit capability setup.
-work: directory
-requires:
-  capabilities:
-    oats.core:
-      source: repo:oats-package
-    oats.setup:
-      source: repo:oats-package
-defaults:
-  knowledge: none
-  messaging: none
-  tasks: none