@awebai/oats 0.25.9 → 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)) {
@@ -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;
@@ -283,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 : {};
@@ -314,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");
@@ -321,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");
@@ -331,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;
@@ -373,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(" | ") } : {}),
     });
@@ -398,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);
   }
 }
@@ -407,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
@@ -513,7 +671,7 @@ 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 });
@@ -541,7 +699,10 @@ 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);
@@ -594,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;
     }
@@ -607,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; })(),
@@ -656,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}` : ""}` });
@@ -688,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
@@ -721,80 +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.
-  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);
+  // 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);
   }
+  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 = candidate?.root ? resolve(candidate.root) : process.cwd();
-  console.log(`aweb onboarding — messaging root: ${scope}${teamName ? `, team: ${teamName}` : ""}\n`);
-  if (!teamName) {
-    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);
-  }
+  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);
   }
-  if (!existsSync(join(scope, ".aw"))) {
-    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);
-  }
-  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)`);
 }

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

@@ -8,8 +8,13 @@ Some instances serve a resident global identity through an expiring session
 grant instead of holding their own root keys. In that mode, your TASK.md and
 `instance.json` identify the resident alias, scopes, and expiry; root keys are
 not in your home, and mint/revoke/join/identity-lifecycle commands are not yours
-to run. If `aw mail` or `aw chat` says the grant expired or was revoked, stop
-messaging and report the condition to your coordinator/human.
+to run. Your grant home is attached to the resident's custody service; if a
+message you sent shows unverified at the receiver, the attachment is missing:
+report it, do not retry. If `aw mail` or `aw chat` reports a terminal grant condition —
+`grant_expired`, `grant_revoked`, `grant_subject_inactive`,
+`grant_issuer_revoked`, or `grant_freshness_unavailable` — report the exact
+condition to your coordinator/human and stop using messaging. The host restarts
+you with a fresh grant when renewal is available.
 
 **Load the skills at the right moments — do not work from memory:**