@awebai/oats 0.25.8 → 0.25.9

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-24-desktop-phase-f-boundary.md

@@ -87,15 +87,26 @@ 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. **Work** comes from the soul's `work:` mode, and a `checkout` soul is
-offered "Use a worktree instead?" (`--work worktree`). 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 **Advanced** section holds harness permissions, launch
-config, relation, messaging identity (`--provider <cap> identity.mode=…`,
-decision 27), branch/base overrides and the execution server. Every modal gets a darker backdrop.
+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

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

@@ -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)

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/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.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/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.8",
+  "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",