@awebai/oats 0.25.8 → 0.26.0

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

@@ -7,8 +7,8 @@
  *   oats-aweb retire   gracefully self-delete it (BEFORE the home dir is removed)
  *   oats-aweb roster   list the aweb team's members — the cross-machine directory
  *                     of live instances (alias = instance name) and humans
- *   oats-aweb setup    guided onboarding: check the aw CLI, initialize the team
- *                     scope's aweb workspace, create/join the team
+ *   oats-aweb setup    guided onboarding: check the aw CLI, initialize the
+ *                     messaging root with aw init / aw team join, verify team
  *
  * Env contract (set by the kernel):
  *   OATS_EVENT     spawn|retire
@@ -43,7 +43,8 @@ import { join, dirname, resolve, delimiter, isAbsolute } from "node:path";
 import { loadCapturedAwebExecution, requireCapturedAwebAction } from "../lib/captured-execution.mjs";
 import { assessCapturedSessionReadiness, querySelectedKernel } from "../lib/session-readiness.mjs";
 import { runCapturedNative } from "../lib/captured-native.mjs";
-import { parseBindingJson } from "../lib/binding-wire.mjs";
+import { CUSTODY_ATTACH_MIN, grantYamlCustodySocket, parseBindingJson } from "../lib/binding-wire.mjs";
+import { custodyPreflight } from "../lib/grant-custody.mjs";
 
 /** Run a command as ARGV — never a shell string. Team ids, aliases, instance
  * names and invite tokens all flow through here; quoting them correctly is a
@@ -93,14 +94,20 @@ const parseSecretJson = (text, what) => {
  * would read as "aw is missing" on every such host. */
 /** The installed aw's version from `aw version` ("aw 1.36.1 ..."), or
  *  undefined when it cannot be read; compared as numeric triples. */
+function awVersionTriple() {
+  try { return /aw\s+v?(\d+)\.(\d+)\.(\d+)/.exec(run(["aw", "version"], undefined, 10000)); } catch { return undefined; }
+}
 function awAtLeast(floor) {
-  let v;
-  try { v = /aw\s+v?(\d+)\.(\d+)\.(\d+)/.exec(run(["aw", "version"], undefined, 10000)); } catch { return false; }
+  const v = awVersionTriple();
   if (!v) return false;
   const a = v.slice(1, 4).map(Number), b = floor.split(".").map(Number);
   for (let i = 0; i < 3; i++) { if (a[i] !== b[i]) return a[i] > b[i]; }
   return true;
 }
+function awVersionLabel() {
+  const v = awVersionTriple();
+  return v ? v.slice(1, 4).join(".") : "unknown";
+}
 
 function onPath(cmd) {
   for (const dir of String(process.env.PATH || "").split(delimiter)) {
@@ -137,7 +144,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; },
     });
@@ -152,6 +159,9 @@ try {
 const event = process.env.OATS_EVENT || process.argv[2];
 const instance = process.env.OATS_INSTANCE;
 const home = process.env.OATS_HOME || process.cwd();
+const AWEB_ALIAS_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+const AWEB_ALIAS_RULE = "invalid alias: aweb aliases must be 1-64 characters, start with a letter or digit, and then contain only letters, digits, '-' or '_'";
+const ALIAS_REUSE_REMEDY = "spawn with a different --name (kernels 0.26.0+) or a different --purpose";
 // Effective capability settings, injected by kernel dispatch (OATS_SETTINGS).
 // delivery: "channel" (default) keeps the native channel packages waking the
 // instance; "session" hands delivery to the host wake broker (aweb-abil):
@@ -166,6 +176,7 @@ const deliveryMode = (() => {
 const identitySettings = settings.identity && typeof settings.identity === "object" && !Array.isArray(settings.identity) ? settings.identity : {};
 const identityMode = identitySettings.mode === undefined || identitySettings.mode === null || identitySettings.mode === "" ? "local" : String(identitySettings.mode);
 if (!["local", "global"].includes(identityMode) && ["spawn", "retire"].includes(event)) fatal(`identity.mode must be either "local" or "global" (got ${JSON.stringify(identitySettings.mode)})`);
+if (event === "spawn" && identityMode === "local" && !identitySettings.source && (!instance || !AWEB_ALIAS_RE.test(instance))) fatal(`${AWEB_ALIAS_RULE}; OATS_INSTANCE is ${instance ? "not valid" : "missing"}, so no identity could be minted`);
 const payloadTeam = () => {
   const fromSettings = typeof settings.team === "string" && settings.team.trim() ? settings.team.trim() : undefined;
   const fromEnv = process.env.OATS_TEAM_ID || process.env.OATS_TEAM_NAME || undefined;
@@ -194,7 +205,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 +217,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
@@ -253,8 +294,23 @@ function wakeRegister(instanceHome, identityHome) {
 function wakeDeregister(instanceHome) {
   try { run(["aw", "wake", "deregister", "--home", instanceHome], instanceHome, 60000); return true; } catch { return false; }
 }
-const DEFAULT_GRANT_SCOPES = ["mail.read", "mail.send", "chat.read", "chat.send"];
+// The first aw release whose grant subtree accepts `aw id grant mint --team
+// <team-id>` (and the full normal/reviewer scope lists): aw 1.36.2, paired with
+// aweb server 1.27.5 for complete custody operations. aw 1.36.1 has neither.
+const GRANT_TEAM_FLAG_MIN = "1.36.2";
+const NORMAL_GRANT_SCOPES = ["mail.read", "mail.send", "chat.read", "chat.send", "events.read", "coord.read", "coord.write", "presence.write", "contacts.read", "contacts.write"];
+const REVIEWER_GRANT_SCOPES = ["mail.read", "chat.read", "events.read", "coord.read", "presence.write"];
 const residentKeyHint = (name) => `oats-local.yaml settings.oats.aweb.residents.${name || "<name>"}`;
+const grantProfile = () => identitySettings.profile === undefined || identitySettings.profile === null || identitySettings.profile === "" ? "normal" : String(identitySettings.profile);
+function grantScopes() {
+  if (Array.isArray(identitySettings.scopes) && identitySettings.scopes.length) return identitySettings.scopes.map(String);
+  const profile = grantProfile();
+  if (profile === "normal") return [...NORMAL_GRANT_SCOPES];
+  if (profile === "reviewer") return [...REVIEWER_GRANT_SCOPES];
+  fatal(`identity.profile must be one of "normal" or "reviewer" (got ${JSON.stringify(identitySettings.profile)})`);
+}
+const grantE2eeRequired = () => identitySettings.e2ee !== false;
+const grantRenewMode = () => identitySettings.renew === undefined || identitySettings.renew === null || identitySettings.renew === "" ? "off" : String(identitySettings.renew);
 function resolveResidentCustody(name) {
   if (!name) fatal(`identity.mode "global" requires identity.resident; set ${residentKeyHint("<name>")} to the absolute custody directory for that resident identity`);
   const residents = settings.residents && typeof settings.residents === "object" && !Array.isArray(settings.residents) ? settings.residents : {};
@@ -284,6 +340,21 @@ function revokeGrant(custody, grantId) {
     throw e;
   }
 }
+function grantYamlNestedScalar(text, sectionName, key) {
+  const lines = String(text ?? "").split(/\r?\n/);
+  let inSection = false, baseIndent = 0;
+  for (const line of lines) {
+    const section = new RegExp(`^(\\s*)${sectionName}:\\s*(?:#.*)?$`).exec(line);
+    if (section) { inSection = true; baseIndent = section[1].length; continue; }
+    if (inSection) {
+      const ind = /^(\s*)/.exec(line)?.[1].length || 0;
+      if (line.trim() && ind <= baseIndent) inSection = false;
+      const value = new RegExp(`^\\s*${key}:\\s*["']?([^"'\\n#]+)["']?\\s*$`).exec(line);
+      if (value) return value[1].trim();
+    }
+  }
+  return undefined;
+}
 function recoverGrantHome(grantHome) {
   try {
     const text = readFileSync(join(grantHome, "grant.yaml"), "utf8");
@@ -291,9 +362,120 @@ function recoverGrantHome(grantHome) {
       const m = text.match(new RegExp(`^\\s*${key}:\\s*["']?([^"'\\n#]+)["']?\\s*$`, "m"));
       return m ? m[1].trim() : undefined;
     };
-    return { grantId: scalar("grant_id"), team: scalar("team_id"), expiresAt: scalar("expires_at") };
+    return { grantId: scalar("grant_id"), team: scalar("team_id"), expiresAt: scalar("expires_at"), subjectAlias: grantYamlNestedScalar(text, "subject", "alias"), custodySocket: grantYamlCustodySocket(text) };
   } catch { return {}; }
 }
+function readGrantYamlCustodySocket(grantHome) {
+  const text = readFileSync(join(grantHome, "grant.yaml"), "utf8");
+  return grantYamlCustodySocket(text);
+}
+function verifyGrantCustodyAttachment({ grantHome, custodySocket, alias, team }) {
+  const recorded = readGrantYamlCustodySocket(grantHome);
+  if (!recorded) throw new Error(`grant.yaml custody.socket_path is missing`);
+  if (recorded !== custodySocket) throw new Error(`grant.yaml custody.socket_path ${recorded} differs from preflight ${custodySocket}`);
+  const raw = run(["aw", "custody", "status", "--json"], grantHome, 20000, { env: { AWEB_IDENTITY_HOME: grantHome }, secretSafe: true });
+  const status = parseAwJson(raw, "aw custody status");
+  if (String(status.status || "") !== "running") throw new Error(`grant custody status is ${status.status || "unknown"}, not running`);
+  if (status.socket_path !== custodySocket) throw new Error(`grant custody status socket_path ${status.socket_path || "<missing>"} differs from preflight ${custodySocket}`);
+  if (status.resident?.alias !== alias) throw new Error(`grant custody resident alias ${status.resident?.alias || "<missing>"} differs from ${alias}`);
+  const teamRow = (Array.isArray(status.teams) ? status.teams : []).find((t) => t && (t.team_id || t.id) === team);
+  if (!teamRow || teamRow.ready !== true) throw new Error(`grant custody team ${team} is not ready`);
+  return status;
+}
+function preflightCustodySocket(preflight) {
+  return typeof preflight.status?.socket_path === "string" && preflight.status.socket_path.trim() ? preflight.status.socket_path.trim() : undefined;
+}
+function requirePreflightCustodySocket(preflight) {
+  const socket = preflightCustodySocket(preflight);
+  if (!socket) fatal("custody preflight reported no socket_path, so the grant cannot be attached to custody");
+  return socket;
+}
+function grantHomeDirs() {
+  try {
+    return readdirSync(home)
+      .filter((name) => name === ".aweb-identity" || /^\.aweb-identity-\d+$/.test(name))
+      .map((name) => join(home, name))
+      .filter((p) => { try { return statSync(p).isDirectory(); } catch { return false; } });
+  } catch { return []; }
+}
+function removeGrantHomes() { for (const p of grantHomeDirs()) { try { rmSync(p, { recursive: true, force: true }); } catch { /* best effort */ } } }
+function newestGrantHome() {
+  const dirs = grantHomeDirs().map((p) => {
+    try { return { path: p, mtime: statSync(p).mtimeMs }; } catch { return { path: p, mtime: 0 }; }
+  }).sort((a, b) => b.mtime - a.mtime || b.path.localeCompare(a.path));
+  return dirs[0]?.path || join(home, ".aweb-identity");
+}
+const priorGrantHome = (meta = {}) => typeof meta.identity?.grant?.home === "string" && meta.identity.grant.home ? meta.identity.grant.home : newestGrantHome();
+function retainedLaunchOutput(meta = {}, identityHome = priorGrantHome(meta)) {
+  const delivery = meta.delivery || deliveryMode;
+  const env = {};
+  if (delivery === "session") env.AWEB_DELIVERY = "session";
+  if (meta.identity?.mode === "global" && meta.identity?.grant?.id) env.AWEB_IDENTITY_HOME = identityHome;
+  const launch = (process.env.OATS_RUNTIME || "") === "claude" && delivery === "channel" ? { claude: "--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace" } : undefined;
+  return { ...(Object.keys(env).length ? { env } : {}), ...(launch ? { launch } : {}) };
+}
+function grantMintArgv({ team, scopes, ttl, grantHome, custodySocket }) {
+  return ["aw", "id", "grant", "mint", ...(awAtLeast(GRANT_TEAM_FLAG_MIN) ? ["--team", team] : []), "--scope", scopes.join(","), "--ttl", ttl, "--label", `oats:${instance}`, "--out", grantHome, "--custody-socket", custodySocket, "--json"];
+}
+function validateMintedGrant(minted, grantHome) {
+  const grantId = typeof minted.grant_id === "string" ? minted.grant_id : undefined;
+  const expiresAt = typeof minted.expires_at === "string" ? minted.expires_at : undefined;
+  const mintedTeam = typeof minted.team_id === "string" ? minted.team_id : undefined;
+  const mintedOut = typeof minted.out === "string" ? minted.out : undefined;
+  if (!grantId || !expiresAt || !mintedTeam || !mintedOut) throw new Error("aw id grant mint JSON lacked grant_id, expires_at, team_id, or out");
+  if (resolve(mintedOut) !== resolve(grantHome)) throw new Error(`aw id grant mint wrote ${mintedOut}, not ${grantHome}`);
+  return { minted, grantId, expiresAt, mintedTeam, alias: typeof minted.alias === "string" && minted.alias ? minted.alias : undefined, address: typeof minted.address === "string" && minted.address ? minted.address : null };
+}
+function parseMintedGrant(raw, grantHome) { return validateMintedGrant(parseAwJson(raw, "aw id grant mint"), grantHome); }
+function globalGrantRenew() {
+  const mode = grantRenewMode();
+  const oldMeta = JSON.parse(process.env.OATS_META || "{}");
+  if (mode === "off") out(retainedLaunchOutput(oldMeta));
+  if (mode !== "launch") fatal(`identity.renew must be "off" or "launch" (got ${JSON.stringify(identitySettings.renew)})`);
+  if (oldMeta.identity?.mode !== "global" || !oldMeta.identity?.grant?.id) out(retainedLaunchOutput(oldMeta));
+  const resident = String(identitySettings.resident || oldMeta.identity.resident || "");
+  const custody = resolveResidentCustody(resident);
+  const team = payloadTeam().team || oldMeta.identity.team;
+  if (!team) fatal("identity.renew launch needs the prior grant team or settings.oats.aweb.team");
+  const scopes = grantScopes();
+  const ttl = identitySettings.ttl === undefined || identitySettings.ttl === null || identitySettings.ttl === "" ? "8h" : String(identitySettings.ttl);
+  const oldHome = priorGrantHome(oldMeta);
+  let preflight;
+  try { preflight = custodyPreflight({ custody, resident, team, e2eeRequired: grantE2eeRequired(), fatalOnError: false, runAw: (argv, cwd, options) => run(argv, cwd, 60000, options), fatal }); }
+  catch (e) { out({ meta: oldMeta, ...retainedLaunchOutput(oldMeta, oldHome), warning: `oats-aweb: renewal custody preflight failed (${e.message || e}); keeping previous grant ${oldMeta.identity.grant.id}` }); }
+  const custodySocket = preflightCustodySocket(preflight);
+  if (!custodySocket) out({ meta: oldMeta, ...retainedLaunchOutput(oldMeta, oldHome), warning: `oats-aweb: renewal custody preflight reported no socket_path, so the grant cannot be attached to custody; keeping previous grant ${oldMeta.identity.grant.id}` });
+  if (!awAtLeast(CUSTODY_ATTACH_MIN)) out({ meta: oldMeta, ...retainedLaunchOutput(oldMeta, oldHome), warning: `oats-aweb: aw ${awVersionLabel()} cannot attach a grant to custody (--custody-socket); grants need aw >= ${CUSTODY_ATTACH_MIN}; keeping previous grant ${oldMeta.identity.grant.id}` });
+  let stamp = Math.floor(Date.now() / 1000);
+  let grantHome = join(home, `.aweb-identity-${stamp}`);
+  while (existsSync(grantHome)) grantHome = join(home, `.aweb-identity-${++stamp}`);
+  let parsed;
+  try {
+    parsed = parseMintedGrant(run(grantMintArgv({ team, scopes, ttl, grantHome, custodySocket }), custody, 60000, { unsetEnv: ["AWEB_IDENTITY_HOME"] }), grantHome);
+  } catch (e) {
+    try { rmSync(grantHome, { recursive: true, force: true }); } catch { /* best effort */ }
+    out({ meta: oldMeta, ...retainedLaunchOutput(oldMeta, oldHome), warning: `oats-aweb: renewal mint failed (${e.message || e}); keeping previous grant ${oldMeta.identity.grant.id}` });
+  }
+  const { grantId, expiresAt, mintedTeam, alias: mintedAlias, address } = parsed;
+  const recovered = recoverGrantHome(grantHome);
+  const alias = recovered.subjectAlias || mintedAlias || oldMeta.identity.alias || resident;
+  const newMeta = { ...oldMeta, delivery: oldMeta.delivery || deliveryMode, identity: identityMeta({ mode: "global", alias, team: mintedTeam, address: address || oldMeta.identity.address || null, resident, grant: { id: grantId, expiresAt, scopes, home: grantHome } }) };
+  if (mintedTeam !== team) {
+    try { revokeGrant(custody, grantId); } catch { /* minted mismatch expires by TTL if revoke fails */ }
+    try { rmSync(grantHome, { recursive: true, force: true }); } catch { /* best effort */ }
+    out({ meta: oldMeta, ...retainedLaunchOutput(oldMeta, oldHome), warning: `oats-aweb: renewal minted grant team ${mintedTeam} differs from ${team}; keeping previous grant ${oldMeta.identity.grant.id}` });
+  }
+  try { verifyGrantCustodyAttachment({ grantHome, custodySocket, alias: newMeta.identity.alias, team: mintedTeam }); }
+  catch (e) {
+    try { revokeGrant(custody, grantId); } catch { /* new grant expires by TTL if revoke fails */ }
+    try { rmSync(grantHome, { recursive: true, force: true }); } catch { /* best effort */ }
+    out({ meta: oldMeta, ...retainedLaunchOutput(oldMeta, oldHome), warning: `oats-aweb: renewal grant ${grantId} custody attachment failed (${e.message || e}); keeping previous grant ${oldMeta.identity.grant.id}` });
+  }
+  let warning;
+  try { revokeGrant(custody, oldMeta.identity.grant.id); }
+  catch (e) { warning = `oats-aweb: previous grant ${oldMeta.identity.grant.id} was not revoked (${e.message || e}); new grant ${grantId} is kept and the previous grant still expires at ${oldMeta.identity.grant.expiresAt || "its TTL"}`; }
+  out({ meta: newMeta, ...retainedLaunchOutput(newMeta, grantHome), ...(warning ? { warning } : {}) });
+}
 function globalGrantSpawn() {
   const { team, payload, env: envTeam } = payloadTeam();
   if (!team) fatal("identity.mode \"global\" requires settings.oats.aweb.team (or OATS_TEAM_ID/OATS_TEAM_NAME) before minting a grant");
@@ -301,37 +483,40 @@ function globalGrantSpawn() {
   const custody = resolveResidentCustody(resident);
   const grantHome = join(home, ".aweb-identity");
   if (existsSync(grantHome)) fatal(`${grantHome} already exists; refusing to overwrite an existing aweb session grant home`);
-  const scopes = Array.isArray(identitySettings.scopes) && identitySettings.scopes.length ? identitySettings.scopes.map(String) : DEFAULT_GRANT_SCOPES;
+  const scopes = grantScopes();
   const ttl = identitySettings.ttl === undefined || identitySettings.ttl === null || identitySettings.ttl === "" ? "8h" : String(identitySettings.ttl);
+  const preflight = custodyPreflight({ custody, resident, team, e2eeRequired: grantE2eeRequired(), runAw: (argv, cwd, options) => run(argv, cwd, 60000, options), fatal });
+  const custodySocket = requirePreflightCustodySocket(preflight);
+  if (!awAtLeast(CUSTODY_ATTACH_MIN)) fatal(`aw ${awVersionLabel()} cannot attach a grant to custody (--custody-socket); grants need aw >= ${CUSTODY_ATTACH_MIN}`);
   let meta;
   const cleanup = () => { try { rmSync(grantHome, { recursive: true, force: true }); } catch { /* best effort */ } };
   const failAfterMint = (message, code = 1) => { cleanup(); out({ ...(meta ? { meta } : {}), warning: `oats-aweb: ${String(message).slice(0, 300)}` }, code); };
   try {
-    const raw = run(["aw", "id", "grant", "mint", "--scope", scopes.join(","), "--ttl", ttl, "--label", `oats:${instance}`, "--out", grantHome, "--json"], custody, 60000, { unsetEnv: ["AWEB_IDENTITY_HOME"] });
+    const raw = run(grantMintArgv({ team, scopes, ttl, grantHome, custodySocket }), custody, 60000, { unsetEnv: ["AWEB_IDENTITY_HOME"] });
     let minted;
-    try { minted = parseAwJson(raw, "aw id grant mint"); }
+    try { minted = parseMintedGrant(raw, grantHome).minted; }
     catch (parseError) {
       const recovered = recoverGrantHome(grantHome);
       if (recovered.grantId) {
-        meta = { delivery: deliveryMode, identity: identityMeta({ mode: "global", alias: resident, team: recovered.team || team, resident, grant: { id: recovered.grantId, expiresAt: recovered.expiresAt || "unknown", scopes } }) };
+        meta = { delivery: deliveryMode, identity: identityMeta({ mode: "global", alias: resident, team: recovered.team || team, resident, grant: { id: recovered.grantId, expiresAt: recovered.expiresAt || "unknown", scopes, home: grantHome } }) };
         try { revokeGrant(custody, recovered.grantId); failAfterMint(`${parseError.message}; recovered grant ${recovered.grantId} from grant.yaml, revoked it, and removed the grant home`); }
         catch (revokeError) { failAfterMint(`${parseError.message}; recovered grant ${recovered.grantId} from grant.yaml, but revoke failed: ${revokeError.message || revokeError}`); }
       }
       throw parseError;
     }
-    const grantId = typeof minted.grant_id === "string" ? minted.grant_id : undefined;
-    const expiresAt = typeof minted.expires_at === "string" ? minted.expires_at : undefined;
-    const mintedTeam = typeof minted.team_id === "string" ? minted.team_id : undefined;
-    const mintedOut = typeof minted.out === "string" ? minted.out : undefined;
-    if (!grantId || !expiresAt || !mintedTeam || !mintedOut) throw new Error("aw id grant mint JSON lacked grant_id, expires_at, team_id, or out");
-    if (resolve(mintedOut) !== resolve(grantHome)) throw new Error(`aw id grant mint wrote ${mintedOut}, not ${grantHome}`);
-    const alias = typeof minted.alias === "string" && minted.alias ? minted.alias : resident;
-    const address = typeof minted.address === "string" && minted.address ? minted.address : null;
-    meta = { delivery: deliveryMode, identity: identityMeta({ mode: "global", alias, team: mintedTeam, address, resident, grant: { id: grantId, expiresAt, scopes } }) };
+    const { grantId, expiresAt, mintedTeam, alias: mintedAlias, address } = validateMintedGrant(minted, grantHome);
+    const recovered = recoverGrantHome(grantHome);
+    const alias = recovered.subjectAlias || mintedAlias || resident;
+    meta = { delivery: deliveryMode, identity: identityMeta({ mode: "global", alias, team: mintedTeam, address, resident, grant: { id: grantId, expiresAt, scopes, home: grantHome } }) };
     if (mintedTeam !== team) {
       try { revokeGrant(custody, grantId); failAfterMint(`minted grant team ${mintedTeam} differs from ${team}; the grant was revoked and nothing was kept`); }
       catch (e) { failAfterMint(`minted grant team ${mintedTeam} differs from ${team}; revoke failed: ${e.message || e}`); }
     }
+    try { verifyGrantCustodyAttachment({ grantHome, custodySocket, alias, team: mintedTeam }); }
+    catch (e) {
+      try { revokeGrant(custody, grantId); failAfterMint(`minted grant ${grantId} custody attachment failed: ${e.message || e}; the grant was revoked and nothing was kept`); }
+      catch (revokeError) { failAfterMint(`minted grant ${grantId} custody attachment failed: ${e.message || e}; revoke failed: ${revokeError.message || revokeError}`); }
+    }
     const launch = (process.env.OATS_RUNTIME || "") === "claude" && deliveryMode === "channel"
       ? { claude: "--dangerously-load-development-channels plugin:aweb-channel@awebai-marketplace" }
       : undefined;
@@ -343,15 +528,16 @@ function globalGrantSpawn() {
         catch (revokeError) { failAfterMint(`session delivery registration failed for minted grant ${grantId}: ${e.message || e}; revoke failed: ${revokeError.message || revokeError}`); }
       }
     }
-    const warnings = [];
+    const warnings = [...preflight.warnings];
     if (payload && envTeam && payload !== envTeam) warnings.push(`oats-aweb: settings.oats.aweb.team ${payload} differs from OATS team ${envTeam}; using payload team`);
+    const e2eeBrief = preflight.warnings.length ? ` Warning: ${preflight.warnings.join(" ")}` : "";
     const deliveryBrief = deliveryMode === "session"
       ? ` Notification delivery: external (AWEB_DELIVERY=session): the host wake broker (aw wake) is registered for this home and nudges you when mail or chat arrives; the native aweb channel is not running. If you have waited long with nothing arriving, check \`aw mail inbox\` and \`aw chat pending\` yourself at task boundaries.`
       : "";
     out({
       meta,
       env,
-      brief: `Comms: you act as resident aweb identity "${alias}" on team ${mintedTeam} through a session grant for ${resident}; scopes: ${scopes.join(", ")}; expires: ${expiresAt}. Root keys are not in this home, and identity lifecycle commands are not yours to run.${deliveryBrief} Use \`aw mail\`/\`aw chat\` for messaging (see the aweb-messaging skill); coordination stays in your deployment's task layer.`,
+      brief: `Comms: you act as resident aweb identity "${alias}" on team ${mintedTeam} through a session grant for ${resident}; scopes: ${scopes.join(", ")}; expires: ${expiresAt}. Root keys are not in this home, and identity lifecycle commands are not yours to run; your grant home is attached to the resident's custody service. If a message you sent shows unverified at the receiver, report it, do not retry.${e2eeBrief}${deliveryBrief} Use \`aw mail\`/\`aw chat\` for messaging (see the aweb-messaging skill); coordination stays in your deployment's task layer.`,
       ...(launch ? { launch } : {}),
       ...(warnings.length ? { warning: warnings.join(" | ") } : {}),
     });
@@ -368,8 +554,10 @@ function globalGrantRetire(meta) {
   const custody = resolveResidentCustody(resident);
   try {
     revokeGrant(custody, id);
+    removeGrantHomes();
     out({ meta: { retired: true, identityRevoked: true, grant: id } });
   } catch (e) {
+    removeGrantHomes();
     out({ meta: { retired: false, reason: "grant-revoke-failed", grant: id }, warning: `oats-aweb: grant ${id} was not revoked (${e.message || e}); it still expires at ${meta.identity?.grant?.expiresAt || "its TTL"}` }, 1);
   }
 }
@@ -377,7 +565,7 @@ const seatLockPath = (source) => join(dirname(source), ".aw-retained-seat.json")
 /** The alias a home's .aw/workspace.yaml records under memberships (indented),
  *  or undefined. Read only when the hook has no alias of its own. */
 const workspaceAliasOf = (homeDir) => {
-  try { const m = readFileSync(join(homeDir, ".aw", "workspace.yaml"), "utf8").match(/^\s*alias:\s*["']?([a-z0-9][a-z0-9._-]{0,127})["']?\s*$/mi); return m ? m[1] : undefined; }
+  try { const m = readFileSync(join(homeDir, ".aw", "workspace.yaml"), "utf8").match(/^\s*alias:\s*["']?([a-z0-9][a-z0-9_-]{0,63})["']?\s*$/mi); return m ? m[1] : undefined; }
   catch { return undefined; }
 };
 /** A join that the CLI reported as failed (or that this hook killed on
@@ -411,9 +599,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
@@ -483,14 +671,14 @@ function retainedSeatSpawn(source, takeOver) {
     if (expectedDid && shownDid !== expectedDid) throw new Error(`aw whoami shows did ${shownDid || "(none)"}, not the retained identity's ${expectedDid}; the seat is not the same identity`);
     if (expectedAddress && shownAddress !== expectedAddress) throw new Error(`aw whoami shows address ${shownAddress || "(none)"}, not the retained identity's ${expectedAddress}; the seat is not the same identity`);
     const aliasRaw = String(ws.alias || st.alias || (expectedAddress || "").split("/").pop() || instance);
-    if (!/^[a-z0-9][a-z0-9._-]{0,127}$/i.test(aliasRaw)) throw new Error(`aw workspace status reports an alias that is not a plausible alias; the seat is not briefed`);
+    if (!AWEB_ALIAS_RE.test(aliasRaw)) throw new Error(`aw workspace status reports an alias that is not a plausible alias; the seat is not briefed`);
     const alias = aliasRaw;
     if (expectedAddress && !expectedAddress.endsWith(`/${alias}`)) throw new Error(`aw workspace status shows alias ${alias}, not the retained identity's address ${expectedAddress}; the seat is not the same identity`);
     writeFileSync(lockPath, JSON.stringify({ home, instance, alias, team, takenAt: new Date().toISOString(), host: hostname(), ...(takenOver ? { tookOverFrom: takenOver } : {}) }, null, 2) + "\n", { mode: 0o600 });
     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 +688,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(" | ") } : {}),
@@ -511,13 +699,20 @@ function retainedSeatSpawn(source, takeOver) {
   }
 }
 
-if (event === "spawn") {
+if (event === "launch") {
+  if (identityMode === "global" || grantRenewMode() === "launch") globalGrantRenew();
+  out(retainedLaunchOutput(JSON.parse(process.env.OATS_META || "{}")));
+} else if (event === "spawn") {
   if (identityMode === "global" && identitySettings.source) fatal('identity.mode "global" cannot be combined with identity.source; use identity.mode "local" with identity.source for a retained seat, or identity.mode "global" with identity.resident for a resident grant');
   if (identityMode === "global") globalGrantSpawn();
   if (identityMode === "local" && settings.identity && typeof settings.identity === "object" && settings.identity.source) retainedSeatSpawn(String(settings.identity.source), settings.identity.takeOver === true);
   let minted;                 // external identity, once `aw team join` succeeds
   const root = awebRoot();
-  if (!root) fatal(`no initialized aweb root (.aw) among the bounded candidates (home, its git repo, context repo, workspace ${process.env.OATS_WORKSPACE || "?"}), so no identity could be minted and this instance would have no messaging — run \`oats aweb setup\` for guided onboarding`);
+  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 +722,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.
@@ -559,7 +755,7 @@ if (event === "spawn") {
       // re-spawn under the same name is refused by AWID. Say that, and the
       // remedy, instead of relaying a bare join error.
       if (e.aliasConflict) {
-        fatal(`alias "${instance}" already holds a certificate on ${team} (a retired instance of that name is not reusable until aweb-abim ships), so no identity could be minted — spawn with a fresh --purpose instead`);
+        fatal(`alias "${instance}" already holds a certificate on ${team} (a retired instance of that name is not reusable until aweb-abim ships), so no identity could be minted — ${ALIAS_REUSE_REMEDY}`);
       }
       throw e;
     }
@@ -572,7 +768,7 @@ if (event === "spawn") {
     // token; otherwise fall back to what WE asked for, which is always known.
     const clean = (v) => (typeof v === "string" && v.trim() && !v.includes(inv.token) ? v.trim() : undefined);
     const joined = {
-      alias: (() => { const a = clean(raw.alias); return a && /^[a-z0-9][a-z0-9._-]{0,127}$/i.test(a) ? a : instance; })(),
+      alias: (() => { const a = clean(raw.alias); return a && AWEB_ALIAS_RE.test(a) ? a : instance; })(),
       // Team ids are "<name>:<domain>"; anything else is not one, and the
       // requested team is the honest fallback.
       team_id: (() => { const t = clean(raw.team_id); return t && /^[^\s:]+:[^\s:]+$/.test(t) ? t : team; })(),
@@ -597,7 +793,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 +801,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 } : {}),
@@ -621,7 +817,7 @@ if (event === "spawn") {
   // A retained seat: release the lock and leave the identity alone. Never
   // aw workspace delete (it would soft-delete the standing identity's row)
   // and never team retire; the source .aw stays until a human removes it.
-  if (meta.delivery === "session") { if (!wakeDeregister(home)) process.stderr.write("oats-aweb: aw wake deregister failed; the broker treats a retired home as inactive on its own\n"); }
+  if (meta.delivery === "session" && (meta.retained || meta.identity?.mode !== "global")) { if (!wakeDeregister(home)) process.stderr.write("oats-aweb: aw wake deregister failed; the broker treats a retired home as inactive on its own\n"); }
   if (meta.retained) {
     if (meta.lock) { try { rmSync(meta.lock, { force: true }); } catch { /* the lock may already be gone */ } }
     out({ meta: { retired: true, retained: true, identityReleased: true, ...(meta.tookOverFrom ? { tookOverFrom: meta.tookOverFrom } : {}) }, warning: `oats-aweb: released the retained identity "${meta.alias}" (lock ${meta.lock || "?"} removed); the identity itself and ${meta.source || "its source"} are untouched${meta.tookOverFrom ? `; this seat had taken over from ${meta.tookOverFrom}` : ""}` });
@@ -653,14 +849,14 @@ if (event === "spawn") {
       // aw 1.36.1 prints the cause as alias_released_reason (workspace.go,
       // workspace_self_retire.go); `reason` is tolerated for a later rename.
       const reason = typeof doc?.alias_released_reason === "string" ? doc.alias_released_reason : typeof doc?.reason === "string" ? doc.reason : (doc ? "unstated" : "no JSON answer");
-      out({ meta: { retired: true, aliasReusable: released, aliasReason: reason }, ...(released ? {} : { warning: `oats-aweb: workspace "${meta.alias}" deleted but its alias was not released (${reason}); spawn successors with a fresh --purpose until it is` }) });
+      out({ meta: { retired: true, aliasReusable: released, aliasReason: reason }, ...(released ? {} : { warning: `oats-aweb: workspace "${meta.alias}" deleted but its alias was not released (${reason}); spawn successors with a different --name (kernels 0.26.0+) or a different --purpose until it is` }) });
     }
     run(["aw", "workspace", "delete", meta.alias], home);
     // Honest: the workspace row is deleted, but a hosted local member cannot
     // revoke its own AWID certificate (aweb-abim), so the alias is NOT
     // reusable. retired stays true because the cleanup is as complete as the
     // platform allows; the field and the line carry the truth.
-    out({ meta: { retired: true, aliasReusable: false }, warning: `oats-aweb: workspace "${meta.alias}" deleted; its certificate is not revoked (aweb-abim), so the alias is not reusable — spawn successors with a fresh --purpose` });
+    out({ meta: { retired: true, aliasReusable: false }, warning: `oats-aweb: workspace "${meta.alias}" deleted; its certificate is not revoked (aweb-abim), so the alias is not reusable — spawn successors with a different --name (kernels 0.26.0+) or a different --purpose` });
   } catch (e) {
     // Exit nonzero: during a required-hook rollback this is the signal that
     // compensation did NOT complete, so the spawn is not reported as cleanly
@@ -673,9 +869,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); }
@@ -686,39 +882,105 @@ if (event === "spawn") {
   console.log("\nAliases minted by OATS are instance names; message one with `aw mail send --to <alias> --subject \"...\" --body \"...\"`.");
   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 (!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);
+  // Guided onboarding — idempotent, prints what it finds and can run one
+  // existing aw primitive when the operator supplies the needed authority.
+  const args = process.argv.slice(3).filter((arg) => arg !== "--json");
+  const usage = "usage: oats aweb setup [--username <hosted-user> | --invite <token>]";
+  let username, invite;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--username" && args[i + 1]) { username = args[++i]; continue; }
+    if (arg.startsWith("--username=") && arg.length > "--username=".length) { username = arg.slice("--username=".length); continue; }
+    if (arg === "--invite" && args[i + 1]) { invite = args[++i]; continue; }
+    if (arg.startsWith("--invite=") && arg.length > "--invite=".length) { invite = arg.slice("--invite=".length); continue; }
+    console.error(`oats aweb setup: ${usage}`);
+    process.exit(2);
   }
-  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).");
+  const apiKey = !!process.env.AWEB_API_KEY;
+  const actions = [username ? "--username" : null, invite ? "--invite" : null, apiKey ? "AWEB_API_KEY" : null].filter(Boolean);
+  if (actions.length > 1) { console.error(`oats aweb setup: choose exactly one onboarding authority (${actions.join(", ")})\n${usage}`); process.exit(2); }
+
+  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 = isClassicDeployment() && settings.root === undefined && settings.roots === undefined && settings.team === undefined
+    ? resolve(process.env.OATS_TEAM_SCOPE || process.cwd())
+    : (candidate?.root ? resolve(candidate.root) : process.cwd());
+  const classic = isClassicDeployment() && settings.root === undefined && settings.roots === undefined && settings.team === undefined;
+  console.log(`aweb onboarding — ${classic ? "team scope" : "messaging root"}: ${scope}${teamName ? `, team: ${teamName}` : ""}\n`);
+  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);
   }
-  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)");
+  const defaultTeamForUsername = username ? `default:${username}.aweb.ai` : undefined;
+  const readTeams = () => {
+    try { return parseAwJson(run(["aw", "team", "list", "--json"], scope), "aw team list"); }
+    catch { return { memberships: [] }; }
+  };
+  const matchingTeam = (teams) => want ? teamIdsOf(teams).find((tid) => String(tid) === want || String(tid).startsWith(`${want}:`)) : undefined;
+  const printVerdict = (teams) => {
+    const match = matchingTeam(teams);
+    if (match) {
+      console.log(`readiness: ready`);
+      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`");
+      return;
+    }
+    console.log(`readiness: needs-configuration`);
+    if (!want) {
+      console.log(`  no team: ${teamConfigRemedy()}`);
+      const active = teams.active_team || teamIdsOf(teams)[0];
+      if (active) console.log(`  This root is a member of ${active}; map the workspace team to that id in the workspace file or settings.oats.aweb.team.`);
+      else if (defaultTeamForUsername) console.log(`  New hosted users create ${defaultTeamForUsername}; map the workspace team to that id if this is the intended team.`);
+      return;
+    }
+    console.log(`  Workspace initialized, but no membership matching "${want}".`);
+    if (defaultTeamForUsername) console.log(`  New hosted users create ${defaultTeamForUsername}; set messaging.byTeam.<label>.team or settings.oats.aweb.team to that id, then re-run setup.`);
+    console.log("  Existing team path: ask a member for an invite token, then run `oats aweb setup --invite <token>` (uses `aw team join <token>` at the root).");
+    console.log("  Team API-key path: set AWEB_API_KEY in the environment and run `oats aweb setup` (uses `aw init` at the root; the key is never printed).");
+    console.log("  New hosted-account path: run `oats aweb setup --username <u>` (uses `aw init --username <u>` and creates default:<u>.aweb.ai).");
+  };
+
+  try {
+    const hasRoot = existsSync(join(scope, ".aw"));
+    if (!hasRoot && !actions.length) {
+      console.log(`No aweb workspace at the ${classic ? "team scope" : "messaging root"} yet (${candidate?.key || "settings.oats.aweb.root"}).`);
+      if (!want) console.log(`  Also choose the aweb team for this deployment: ${teamConfigRemedy()}.`);
+      console.log("  Choose one guided setup path:");
+      console.log("    oats aweb setup --username <u>     # runs `aw init --username <u>` and creates default:<u>.aweb.ai");
+      console.log("    AWEB_API_KEY=<key> oats aweb setup  # runs `aw init` for the hosted team behind the key");
+      console.log("    oats aweb setup --invite <token>    # runs `aw team join <token>` from an existing-team invite");
+      console.log("  Or set settings.oats.aweb.root to an absolute directory whose .aw is the aweb minting root, then re-run setup.");
+      console.log("  Own your domain? Use the aweb-team-membership skill for BYOT flows.");
+      process.exit(0);
+    }
+    let teams = hasRoot ? readTeams() : { memberships: [] };
+    if (hasRoot && !matchingTeam(teams) && !actions.length) { printVerdict(teams); process.exit(0); }
+    if (!hasRoot || !matchingTeam(teams)) {
+      if (actions.length) mkdirSync(scope, { recursive: true });
+      if (username) {
+        console.log(`Running aw init --username <u> at ${scope} (username withheld from repeated logs).`);
+        run(["aw", "init", "--username", username], scope, 120000, { secrets: [username], unsetEnv: ["AWEB_API_KEY"] });
+      } else if (invite) {
+        console.log(`Running aw team join <token> at ${scope} (token withheld).`);
+        run(["aw", "team", "join", invite], scope, 120000, { secrets: [invite], secretSafe: true });
+      } else if (apiKey) {
+        console.log(`Running aw init at ${scope} with AWEB_API_KEY from the environment (key withheld).`);
+        run(["aw", "init"], scope, 120000, { secretSafe: true });
+      }
+      teams = readTeams();
+    }
+    printVerdict(teams);
+    process.exit(0);
+  } catch (e) {
+    console.error(`oats aweb setup: ${e.message || e}`);
+    process.exit(1);
   }
-  process.exit(0);
 } else {
   warn(`unknown event "${event}" (expected spawn|retire)`);
 }