@awebai/oats 0.29.1 → 0.29.3

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

@@ -37,7 +37,7 @@
  * identity joined moments before the failure must still be deletable.
  */
 import { execFileSync } from "node:child_process";
-import { chmodSync, cpSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { chmodSync, cpSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
 import { hostname } from "node:os";
 import { join, dirname, resolve, delimiter, isAbsolute } from "node:path";
 import { loadCapturedAwebExecution, requireCapturedAwebAction } from "../lib/captured-execution.mjs";
@@ -45,17 +45,23 @@ import { assessCapturedSessionReadiness, querySelectedKernel } from "../lib/sess
 import { runCapturedNative } from "../lib/captured-native.mjs";
 import { CUSTODY_ATTACH_MIN, grantYamlCustodySocket, parseBindingJson } from "../lib/binding-wire.mjs";
 import { custodyPreflight } from "../lib/grant-custody.mjs";
+import { runtimeDeliveryFor, wakeRegistration } from "../lib/wake-receive.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
  * property of one helper staying correct forever, while argv removes the class.
  * This hook is a REQUIRED spawn hook, so it gates every spawn, which is reason
  * enough not to rely on quoting. */
-const run = (argv, cwd, timeout = 45000, { secrets = [], secretSafe = false, env: extraEnv, unsetEnv = [] } = {}) => {
+const run = (argv, cwd, timeout = 45000, { secrets = [], secretSafe = false, env: extraEnv, unsetEnv = [], input } = {}) => {
   try {
-    const childEnv = extraEnv || unsetEnv.length ? { ...process.env, ...(extraEnv || {}) } : undefined;
-    for (const name of unsetEnv) if (childEnv) delete childEnv[name];
-    return execFileSync(argv[0], argv.slice(1), { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout, ...(childEnv ? { env: childEnv } : {}) }).trim();
+    // An inherited AWEB_IDENTITY_HOME (every aweb instance session carries its
+    // own) is never this hook's identity: aw would act as the CALLER — refusing
+    // cwd-rooted commands such as team invite/list, or deleting the caller's
+    // workspace when a lead retires a worker. Only an explicit env sets one.
+    const childEnv = { ...process.env, ...(extraEnv || {}) };
+    if (!extraEnv || !Object.hasOwn(extraEnv, "AWEB_IDENTITY_HOME")) delete childEnv.AWEB_IDENTITY_HOME;
+    for (const name of unsetEnv) delete childEnv[name];
+    return execFileSync(argv[0], argv.slice(1), { cwd, encoding: "utf8", stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], ...(input === undefined ? {} : { input }), timeout, env: childEnv }).trim();
   } catch (e) {
     // execFileSync puts the WHOLE ARGV in e.message ("Command failed: aw team
     // join <token> …"). This hook's failures are reported by the kernel and land
@@ -118,7 +124,43 @@ function onPath(cmd) {
   }
   return false;
 }
-const out = (o, code = 0) => { process.stdout.write(JSON.stringify(o) + "\n"); process.exit(code); };
+// Kernel home operations (`oats operation run messaging:teams|join|leave`, run
+// with OATS_OPERATION and --json) read stdout as EXACTLY ONE JSON-v1 envelope
+// whose `ok` agrees with the exit status (oats bin/oats.mjs finishOperation):
+// {schemaVersion:1, ok:true, result} with exit 0, or {schemaVersion:1, ok:false,
+// error:{code, message}} with a nonzero exit. Under OATS_OPERATION every other
+// stdout write goes to stderr and every way out answers one envelope. Without
+// it (`oats aweb teams --json` from a shell) the bare document is unchanged.
+const OPERATION_COMMANDS = ["teams", "join", "leave"];
+const operation = process.env.OATS_OPERATION && OPERATION_COMMANDS.includes(process.env.OATS_EVENT || process.argv[2]) ? process.env.OATS_OPERATION : undefined;
+let operationAnswered = false;
+let lastStderr = "";
+const operationEnvelopeFailure = (code, message, details) => ({ schemaVersion: 1, ok: false, error: { code: code || "E_OPERATION_FAILED", message: String(message || "failed").slice(0, 1000), ...(details ? { details } : {}) } });
+function answerOperation(envelope, exitCode) {
+  operationAnswered = true;
+  writeSync(1, JSON.stringify(envelope) + "\n");
+  process.exit(exitCode);
+}
+const operationOk = (result) => answerOperation({ schemaVersion: 1, ok: true, result }, 0);
+const operationFail = (code, message, details) => answerOperation(operationEnvelopeFailure(code, message, details), 1);
+if (operation) {
+  const toStderr = process.stderr.write.bind(process.stderr);
+  process.stderr.write = (chunk, ...rest) => { if (String(chunk).trim()) lastStderr = String(chunk).trim(); return toStderr(chunk, ...rest); };
+  process.stdout.write = (chunk, ...rest) => process.stderr.write(chunk, ...rest);
+  // Any exit that did not answer (a refusal printed to stderr, an uncaught
+  // error) still answers one failure envelope, and never exits 0.
+  process.on("exit", (code) => {
+    if (operationAnswered) return;
+    operationAnswered = true;
+    writeSync(1, JSON.stringify(operationEnvelopeFailure("E_OPERATION_FAILED", lastStderr || `oats-aweb ${operation} exited ${code} without an answer`)) + "\n");
+    if (!code) process.exitCode = 1;
+  });
+}
+const out = (o, code = 0) => {
+  if (operation) operationFail("E_OPERATION_FAILED", String(o?.warning || o?.problems?.[0]?.message || "failed").replace(/^oats-aweb: /, ""));
+  process.stdout.write(JSON.stringify(o) + "\n");
+  process.exit(code);
+};
 const warn = (m) => out({ warning: `oats-aweb: ${String(m).slice(0, 300)}` });
 /** Fatal for a REQUIRED spawn hook: emit metadata for compensation, then exit
  * nonzero so the kernel rolls the spawn back. `meta` carries whatever external
@@ -455,7 +497,7 @@ function globalGrantSpawn() {
   const teamWarnings = [];
   const unmappedPrimary = !team ? unmappedPrimaryRow() : undefined;
   if (!team) team = activeTeamAt(custody);
-  if (unmappedPrimary && team) teamWarnings.push(`oats-aweb: team-unmapped — workspace label ${unmappedPrimary.label} is not mapped; using personal team ${team}`);
+  if (unmappedPrimary && team) teamWarnings.push(`oats-aweb: team-unmapped — workspace label ${unmappedPrimary.label} is not mapped; using the default team ${team}`);
   if (!team) fatal("identity.mode \"global\" requires settings.oats.aweb.team or an active team at the resident custody root before minting a grant");
   const grantHome = join(home, ".aweb-identity");
   if (existsSync(grantHome)) fatal(`${grantHome} already exists; refusing to overwrite an existing aweb session grant home`);
@@ -715,9 +757,9 @@ function validateJoinLabels(labels, { action = "join" } = {}) {
   const eligible = eligibleTeams();
   const byLabel = new Map(eligible.map((t) => [t.label, t]));
   for (const label of labels) {
-    if (action === "leave" && label === "personal") {
-      const error = new Error(`E_TEAM_PERSONAL: ${label} is the personal team and cannot be left`);
-      error.code = "E_TEAM_PERSONAL";
+    if (action === "leave" && label === "default") {
+      const error = new Error(`E_TEAM_DEFAULT: ${label} is the workspace's default team and cannot be left`);
+      error.code = "E_TEAM_DEFAULT";
       throw error;
     }
     if (!LABEL_RE.test(label) || !byLabel.has(label)) {
@@ -735,14 +777,14 @@ const providerTeamsFile = () => join(providerStateDir(), "teams.json");
 function readProviderTeamsState(meta = {}) {
   try {
     const doc = JSON.parse(readFileSync(providerTeamsFile(), "utf8"));
-    return { joinedTeams: joinedTeamsOf(doc) };
-  } catch { return { joinedTeams: joinedTeamsOf(meta) }; }
+    return { joinedTeams: joinedTeamsOf(doc), wakeJoined: doc.wakeJoined === true };
+  } catch { return { joinedTeams: joinedTeamsOf(meta), wakeJoined: meta.wakeJoined === true }; }
 }
 function writeProviderTeamsState(meta) {
   mkdirSync(providerStateDir(), { recursive: true, mode: 0o700 });
-  writeFileSync(providerTeamsFile(), JSON.stringify({ joinedTeams: joinedTeamsOf(meta) }, null, 2) + "\n", { mode: 0o600 });
+  writeFileSync(providerTeamsFile(), JSON.stringify({ joinedTeams: joinedTeamsOf(meta), wakeJoined: meta.wakeJoined === true }, null, 2) + "\n", { mode: 0o600 });
 }
-function withProviderTeams(meta = {}) { return { ...meta, joinedTeams: readProviderTeamsState(meta).joinedTeams }; }
+function withProviderTeams(meta = {}) { const state = readProviderTeamsState(meta); return { ...meta, joinedTeams: state.joinedTeams, wakeJoined: state.wakeJoined }; }
 function identityHomeForLabel(label) { return join(home, `.aweb-identity-${label}`); }
 function awWithIdentity(identityHome, args) { return ["aw", "--identity-home", identityHome, ...args]; }
 function commandOutput(e) { return [e?.stdout, e?.stderr, e?.message].filter(Boolean).join("\n"); }
@@ -758,14 +800,19 @@ function readCapabilityMeta() {
   if (process.env.OATS_META) { try { return withProviderTeams(JSON.parse(process.env.OATS_META || "{}")); } catch { return withProviderTeams({}); } }
   try { return withProviderTeams(JSON.parse(readFileSync(join(home, "instance.json"), "utf8")).capabilityMeta?.["oats.aweb"] || {}); } catch { return withProviderTeams({}); }
 }
+function defaultTeamSource(meta = {}) {
+  const recorded = meta.defaultTeam?.source;
+  if (recorded === "setting" || recorded === "root") return recorded;
+  return payloadTeam().team ? "setting" : "root";
+}
 function teamsDocument(meta = readCapabilityMeta()) {
   const teams = parseOatsTeams();
   const joined = joinedTeamsOf(meta);
   const joinedLabels = new Set(joined.map((j) => j.label));
   const primary = primaryTeamLabel();
-  const personalTeam = meta.team || meta.identity?.team || payloadTeam().team || null;
+  const defaultTeam = meta.defaultTeam?.team || meta.team || meta.identity?.team || payloadTeam().team || null;
   return {
-    personal: { team: personalTeam },
+    defaultTeam: { team: defaultTeam, source: defaultTeamSource(meta) },
     primary,
     eligible: teams.filter((t) => t.mapped && t.team).map((t) => ({ label: t.label, team: t.team, joined: joinedLabels.has(t.label) })),
     joined: joined.map((j) => ({ label: j.label, team: j.team, identityHome: j.identityHome, receive: j.receive || "poll", since: j.since })),
@@ -845,7 +892,7 @@ function parseHomeCommandArgs(argv = process.argv.slice(3)) {
 }
 function outputTeamsDocument(doc, json) {
   if (json) { console.log(JSON.stringify(doc)); return; }
-  console.log(`personal: ${doc.personal.team || "unknown"}`);
+  console.log(`default team: ${doc.defaultTeam.team || "unknown"}`);
   for (const row of doc.eligible) console.log(`${row.joined ? "joined" : "eligible"}: ${row.label} (${row.team})`);
   for (const label of doc.unmapped) console.log(`unmapped: ${label}`);
 }
@@ -855,36 +902,129 @@ function runTeamsCommand(kind) {
   const actions = [];
   const warnings = [];
   if (kind === "join" || kind === "leave") {
+    if (identityMode === "global" || meta.identity?.mode === "global") {
+      const error = new Error('joined teams need local per-team identities; this home acts as a resident identity through a session grant (identity.mode "global")');
+      error.code = "E_TEAM_GLOBAL_MODE";
+      throw error;
+    }
     const rows = validateJoinLabels(args.labels, { action: kind });
-    if (!rows.length) throw new Error("labels are required");
-    for (const row of rows) {
-      const result = kind === "join" ? mintJoinedTeam(row, meta) : leaveJoinedTeam(row.label, meta);
-      meta = result.meta;
-      actions.push({ action: kind, label: row.label, ...(result.released ? { released: result.released } : {}), ...(result.receipt ? { receipt: result.receipt } : {}), ...(result.warning ? { warning: result.warning } : {}) });
-      if (result.warning) warnings.push(`oats-aweb: ${result.warning}`);
+    if (!rows.length) { const error = new Error("labels are required"); error.code = "E_BAD_ARGS"; throw error; }
+    // Record every completed label even when a later one fails: a confirmed
+    // leave deleted its home, and a join created a remote identity.
+    try {
+      for (const row of rows) {
+        const result = kind === "join" ? mintJoinedTeam(row, meta) : leaveJoinedTeam(row.label, meta);
+        meta = result.meta;
+        writeProviderTeamsState(meta);
+        actions.push({ action: kind, label: row.label, ...(result.released ? { released: result.released } : {}), ...(result.receipt ? { receipt: result.receipt } : {}), ...(result.warning ? { warning: result.warning } : {}) });
+        if (result.warning) warnings.push(`oats-aweb: ${result.warning}`);
+      }
+    } catch (e) {
+      // What already happened travels with the failure, so a caller can
+      // reconcile (the operation envelope carries it as error.details).
+      e.partial = { actions };
+      throw e;
+    } finally {
+      const synced = syncWakeReceive(meta);
+      meta = synced.meta;
+      for (const w of synced.warnings) warnings.push(`oats-aweb: ${w}`);
+      writeProviderTeamsState(meta);
     }
-    writeProviderTeamsState(meta);
   }
   const doc = { ...teamsDocument(meta), ...(actions.length ? { actions } : {}), ...(warnings.length ? { warnings } : {}) };
+  if (operation) operationOk(doc);
   outputTeamsDocument(doc, args.json);
 }
 
+/** The primary identity's team and the root that mints it, exactly as 1.14.2:
+ *  the config's `team:` (id, then name) wins, else the root's active team.
+ *  Exits through fatal() on refusal. */
+function resolvePrimaryTeam() {
+  const warnings = [];
+  const root = awebRoot();
+  if (!root) fatal(`${awebRootProblem(rootSettingCandidate())}, so no identity could be minted and this instance would have no messaging`);
+  let team = payloadTeam().team;
+  const source = team ? "setting" : "root";
+  const unmappedPrimary = !team ? unmappedPrimaryRow() : undefined;
+  if (!team) team = JSON.parse(run(["aw", "team", "list", "--json"], root)).active_team;
+  if (unmappedPrimary && team) warnings.push(`oats-aweb: team-unmapped — workspace label ${unmappedPrimary.label} is not mapped; using the default team ${team}`);
+  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 — ${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()}`);
+  }
+  return { team, root, source, warnings };
+}
+
+/** The home's runtime. Spawn and launch run in the session's own env; a
+ *  join/leave may be run by another agent whose OATS_RUNTIME is its own. */
+function instanceRuntime(meta = {}) {
+  const own = ["spawn", "launch"].includes(event) ? process.env.OATS_RUNTIME : undefined;
+  if (own) return own;
+  if (meta.runtime) return meta.runtime;
+  try { const r = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")).runtime; if (r) return r; } catch { /* fall through */ }
+  return process.env.OATS_RUNTIME || undefined;
+}
+function primaryIdentityHomeOf(meta = {}) {
+  return meta.identity?.mode === "global" && meta.identity?.grant?.home ? meta.identity.grant.home : join(home, ".aw");
+}
+/** Keep the host wake broker's registration for this home in step with the
+ *  joined teams, and record each joined team's receive mode. Never throws: a
+ *  refused registration leaves that team poll-only with a warning. */
+function syncWakeReceive(meta) {
+  // A joined home that no longer exists would make aw refuse the whole
+  // registration; it is stale provider state, not a receive identity.
+  const joined = joinedTeamsOf(meta).filter((j) => existsSync(j.identityHome));
+  const delivery = meta.delivery || deliveryMode;
+  const runtime = instanceRuntime(meta);
+  const primary = primaryIdentityHomeOf(meta);
+  const doc = wakeRegistration({ home, primaryIdentityHome: primary, delivery, runtime, joined, backend: process.env.OATS_BACKEND });
+  const warnings = [];
+  let receive = "poll", wakeJoined = false;
+  if (doc) {
+    try { run(["aw", "wake", "register", "--registration-json", "-"], home, 60000, { input: JSON.stringify(doc) }); receive = "native"; wakeJoined = true; }
+    catch (e) { warnings.push(`joined teams stay poll-only: aw wake register refused the multi-identity registration (${e.message || e})`); }
+  } else if (joined.length && !runtimeDeliveryFor({ delivery, runtime })) {
+    warnings.push(`joined teams receive by polling: runtime ${runtime || "unknown"} has no native presentation surface for the host wake broker`);
+  }
+  if (!wakeJoined && meta.wakeJoined) {
+    // Back to one identity: a session home keeps its legacy registration, a
+    // native home leaves the broker entirely.
+    if (delivery === "session") { try { wakeRegister(home, primary); } catch (e) { warnings.push(String(e.message || e)); } }
+    else if (!wakeDeregister(home)) warnings.push("aw wake deregister failed; the broker treats a stale registration as inactive on its own");
+  }
+  const next = { ...meta, ...(runtime ? { runtime } : {}), wakeJoined, joinedTeams: joinedTeamsOf(meta).map((j) => ({ ...j, receive: joined.includes(j) ? receive : "poll" })) };
+  return { meta: next, warnings };
+}
+
 if (event === "launch") {
   if (identityMode === "global" || grantRenewMode() === "launch") globalGrantRenew();
   let oldMeta = withProviderTeams(JSON.parse(process.env.OATS_META || "{}"));
   const joined = joinedTeamsOf(oldMeta);
   if (joined.length && process.env.OATS_TEAMS_SOURCE === "live") {
     const eligible = new Set(eligibleTeams().map((t) => t.label));
-    let changed = false;
     const warnings = [];
     for (const row of joined) if (!eligible.has(row.label)) {
-      try { oldMeta = leaveJoinedTeam(row.label, oldMeta).meta; changed = true; }
+      try { oldMeta = leaveJoinedTeam(row.label, oldMeta).meta; }
       catch (e) { warnings.push(`joined team ${row.label} cleanup failed: ${e.message || e}`); }
     }
-    if (changed) writeProviderTeamsState(oldMeta);
-    out({ ...(changed ? { meta: oldMeta } : {}), ...retainedLaunchOutput(oldMeta), ...(warnings.length ? { warning: `oats-aweb: ${warnings.join(" | ")}` } : {}) });
+    // Re-register what remains: the runtime may differ from the last session.
+    const synced = syncWakeReceive(oldMeta);
+    oldMeta = synced.meta;
+    warnings.push(...synced.warnings);
+    writeProviderTeamsState(oldMeta);
+    out({ meta: oldMeta, ...retainedLaunchOutput(oldMeta), ...(warnings.length ? { warning: `oats-aweb: ${warnings.join(" | ")}` } : {}) });
+  }
+  if (joined.length) {
+    const synced = syncWakeReceive(oldMeta);
+    oldMeta = synced.meta;
+    writeProviderTeamsState(oldMeta);
+    out({ meta: oldMeta, ...retainedLaunchOutput(oldMeta), warning: ["oats-aweb: teams-unverified — keeping joined team memberships because live eligible teams are unavailable", ...synced.warnings.map((w) => `oats-aweb: ${w}`)].join(" | ") });
   }
-  if (joined.length && process.env.OATS_TEAMS_SOURCE !== "live") out({ ...retainedLaunchOutput(oldMeta), warning: "oats-aweb: teams-unverified — keeping joined team memberships because live eligible teams are unavailable" });
   out(retainedLaunchOutput(oldMeta));
 } 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');
@@ -895,32 +1035,16 @@ if (event === "launch") {
   try { joinRows = validateJoinLabels(requestedJoinLabels()); }
   catch (e) { fatal(e.message || e); }
   let minted;                 // external identity, once `aw team join` succeeds
-  const root = awebRoot();
-  if (!root) {
-    const candidate = rootSettingCandidate();
-    fatal(`${awebRootProblem(candidate)}, so no identity could be minted and this instance would have no messaging`);
-  }
+  let spawnMeta;              // with joined teams, once any is accepted
   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
     // team happens to be active at mint time — and verify the joined cert matches.
     // The instance name IS the discoverable alias (the team roster doubles as the
     // cross-machine instance directory).
-    const resolvedTeam = payloadTeam();
-    let team = resolvedTeam.team;
-    const warnings = [];
-    const unmappedPrimary = !team ? unmappedPrimaryRow() : undefined;
-    if (!team) team = JSON.parse(run(["aw", "team", "list", "--json"], root)).active_team;
-    if (unmappedPrimary && team) warnings.push(`oats-aweb: team-unmapped — workspace label ${unmappedPrimary.label} is not mapped; using personal team ${team}`);
-    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 — ${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()}`);
-    }
+    const primary = resolvePrimaryTeam();
+    const { team, root } = primary;
+    const warnings = [...primary.warnings];
     // 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.
     const inv = parseSecretJson(run(["aw", "team", "invite", "--team-id", team, "--json"], root, 45000, { secretSafe: true }), "aw team invite");
@@ -987,15 +1111,19 @@ if (event === "launch") {
     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.`
       : "";
-    let meta = { team: joined.team_id, alias, delivery: deliveryMode, identity: identityMeta({ mode: "local", alias, team: joined.team_id }) };
+    let meta = { team: joined.team_id, alias, delivery: deliveryMode, defaultTeam: { team: joined.team_id, source: primary.source }, ...(process.env.OATS_RUNTIME ? { runtime: process.env.OATS_RUNTIME } : {}), identity: identityMeta({ mode: "local", alias, team: joined.team_id }) };
     const joinFloorProblem = joinRows.length ? joinedTeamsAwFloorProblem() : undefined;
     if (joinFloorProblem) warnings.push(`oats-aweb: ${joinFloorProblem}`);
-    else for (const row of joinRows) { const result = mintJoinedTeam(row, meta); meta = result.meta; if (result.warning) warnings.push(`oats-aweb: ${result.warning}`); }
+    else for (const row of joinRows) { const result = mintJoinedTeam(row, meta); meta = result.meta; spawnMeta = meta; writeProviderTeamsState(meta); if (result.warning) warnings.push(`oats-aweb: ${result.warning}`); }
+    if (joinedTeamsOf(meta).length) { const synced = syncWakeReceive(meta); meta = synced.meta; for (const w of synced.warnings) warnings.push(`oats-aweb: ${w}`); }
     writeProviderTeamsState(meta);
+    const defaultTeamBrief = meta.defaultTeam.source === "setting" ? "the team this deployment configured for you" : "the workspace's default team (the messaging root's active team)";
+    const joinedNow = joinedTeamsOf(meta);
+    const joinedBrief = joinedNow.length ? ` Joined teams: ${joinedNow.map((j) => `${j.label} (${j.team}, receive ${j.receive}, send with \`aw --identity-home ${j.identityHome} mail|chat ...\`)`).join("; ")}.` : "";
     out({
       meta,
       env,
-      brief: `Comms: you have an aweb identity — alias "${alias}" on team ${joined.team_id}.${mismatch}${deliveryBrief} Joined team identities receive by polling in oats.aweb 1.14; run \`oats aweb teams --json\` for identity homes. Use \`aw mail\`/\`aw chat\` for messaging (see the aweb-messaging skill); coordination stays in your deployment's task layer.`,
+      brief: `Comms: you have an aweb identity — alias "${alias}" on team ${joined.team_id}, ${defaultTeamBrief}.${mismatch}${deliveryBrief}${joinedBrief} Load the oats-aweb skill before messaging: \`oats aweb teams --json\` shows your teams, \`oats aweb roster\` who you can reach. 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}` } : warnings.length ? { warning: warnings.join(" | ") } : channelWarning ? { warning: channelWarning } : {}),
     });
@@ -1003,7 +1131,7 @@ if (event === "launch") {
     // A join may already have created a REMOTE identity before the failure.
     // Hand it back as meta so the kernel's compensation can delete it — losing
     // it here would strand a roster entry no one owns.
-    fatal(`identity minting failed: ${e.message || e}`, minted);
+    fatal(`identity minting failed: ${e.message || e}`, minted && joinedTeamsOf(spawnMeta).length ? { ...minted, joinedTeams: joinedTeamsOf(spawnMeta) } : minted);
   }
 } else if (event === "retire") {
   let meta = withProviderTeams(JSON.parse(process.env.OATS_META || "{}"));
@@ -1017,6 +1145,10 @@ if (event === "launch") {
     try { meta = leaveJoinedTeam(joined.label, meta).meta; }
     catch (e) { retireWarnings.push(`joined team ${joined.label} cleanup failed: ${e.message || e}`); }
   }
+  // A native (channel/pi) home registered with the broker only for its joined
+  // teams; a session home was deregistered above.
+  if (meta.wakeJoined && meta.delivery !== "session") { if (!wakeDeregister(home)) retireWarnings.push("aw wake deregister failed; the broker treats a retired home as inactive on its own"); }
+  meta = { ...meta, wakeJoined: false };
   writeProviderTeamsState(meta);
   if (meta.retained) {
     if (meta.lock) { try { rmSync(meta.lock, { force: true }); } catch { /* the lock may already be gone */ } }
@@ -1065,15 +1197,35 @@ if (event === "launch") {
   }
 } else if (["teams", "join", "leave"].includes(event)) {
   try { runTeamsCommand(event); process.exit(0); }
-  catch (e) { console.error(e.code ? `${e.code}: ${e.message}` : `oats aweb ${event}: ${e.message || e}`); process.exit(1); }
+  catch (e) {
+    console.error(e.code ? `${e.code}: ${e.message}` : `oats aweb ${event}: ${e.message || e}`);
+    if (operation) operationFail(e.code, e.message || String(e), e.partial ? { ...e.partial, joined: teamsDocument(readCapabilityMeta()).joined } : undefined);
+    process.exit(1);
+  }
 } else if (event === "roster") {
   // Cross-machine directory: every OATS-spawned instance joins the team with
   // alias = instance name, so the team's member roster lists live instances
   // wherever they run (plus human members). Local liveness comes from
   // `oats status` in the deployment; this is the network view.
-  const root = awebRoot();
-  if (!root) { console.error(`oats aweb roster: ${awebRootProblem(rootSettingCandidate())}`); process.exit(1); }
-  const team = process.env.OATS_TEAM_ID || JSON.parse(run(["aw", "team", "list", "--json"], root)).active_team;
+  // Default: this instance's default team, listed from the root that minted
+  // it. `--label <label>` lists an eligible (joined or not) workspace team from
+  // the host root that holds it.
+  const argv = process.argv.slice(3);
+  const labelAt = argv.indexOf("--label");
+  const label = labelAt >= 0 ? argv[labelAt + 1] : (argv.find((a) => a.startsWith("--label=")) || "").slice("--label=".length) || undefined;
+  const meta = readCapabilityMeta();
+  let team, root;
+  if (label) {
+    const row = eligibleTeams().find((t) => t.label === label);
+    if (!row) { console.error(`E_TEAM_NOT_ELIGIBLE: ${label} is not an eligible team label for this instance (eligible: ${eligibleTeams().map((t) => t.label).join(", ") || "(none)"})`); process.exit(1); }
+    team = row.team; root = awebRootForTeam(team);
+    if (!root) { console.error(`oats aweb roster: ${awebRootProblem(rootSettingCandidate(team))}, so the roster of ${label} cannot be read from this host`); process.exit(1); }
+  } else {
+    team = meta.defaultTeam?.team || meta.identity?.team || meta.team || process.env.OATS_TEAM_ID;
+    root = awebRoot();
+    if (!root) { console.error(`oats aweb roster: ${awebRootProblem(rootSettingCandidate())}`); process.exit(1); }
+    if (!team) team = JSON.parse(run(["aw", "team", "list", "--json"], root)).active_team;
+  }
   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));
@@ -1082,7 +1234,7 @@ if (event === "launch") {
   const members = r.members || [];
   if (!members.length) console.log("  (no member certificates visible from this workspace)");
   for (const m of members) console.log(`  ${m.alias || m.name || m.did || JSON.stringify(m)}`);
-  console.log("\nAliases minted by OATS are instance names; message one with `aw mail send --to <alias> --subject \"...\" --body \"...\"`.");
+  console.log(`\nAliases minted by OATS are instance names; message one with \`aw mail send --to <alias> --subject "..." --body-file <file>\`${label ? ` as this team: \`aw --identity-home <identityHome> mail send ...\` (identityHome from \`oats aweb teams --json\`)` : ""}.`);
   process.exit(0);
 } else if (event === "setup") {
   // Guided onboarding — idempotent, prints what it finds and can run one

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

@@ -1,82 +1,47 @@
 ## Messaging: aweb
 
-Your messaging layer is **aweb**. You have (or will be minted) a team-scoped
-aweb identity — alias = your instance name — on your deployment's team (see
-`instance.json` / your TASK.md briefing for the team).
+Your messaging layer is **aweb**. Your identity's alias is your instance name,
+and it lives in the workspace's default team (the `Comms:` line of your TASK.md
+names it). Wider workspace teams are joined explicitly, each with its own
+identity home.
 
-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. 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 `oats-aweb` skill before your first `aw mail`/`aw chat` of a session,
+whenever an aweb wake or channel event arrives, and whenever messaging or a
+team command looks wrong.** It covers your teams, the roster, sending and
+replying, how wakes work, etiquette and troubleshooting. Do not work from
+memory; if a flag looks wrong run `aw <command> --help`.
 
-**Load the skills at the right moments — do not work from memory:**
-
-- **Before your first `aw mail`/`aw chat` of a session**, load the
-  **aweb-messaging** skill. It is the
-  playbook for sending, replying, and chat etiquette.
-- **When an aweb channel event awakens you**, read the injected event
-  metadata first, then load the **aweb-messaging** skill ("Read the event
-  first" section) before responding — continue the existing conversation,
-  never
-  start a new thread when a `message_id`/`conversation_id` is provided.
-- For team/roster/certificate questions, load **aweb-team-membership**; for
-  identity/key questions, load **aweb-identity**.
-- If a command errors or a flag looks wrong, re-read the skill or run
-  `aw <cmd> --help` — never invent flags.
-
-Quick crib (the skill has the full craft; run from your instance home):
+Quick crib (run from your instance home, never from `./work`):
 
 ```bash
-aw mail inbox                                   # UNREAD mail only
-aw mail inbox --show-all                        # full history (read mail is not lost)
-aw mail send --to <alias> --subject "..." --body "..."    # recipient needs --to
-aw mail send --to <alias> --subject "..." --body-file <f> # markdown/backticks
-aw mail reply <message-id> --body "..."         # reply on an existing thread
-aw chat send --to <alias> --body "..."          # synchronous back-and-forth
+oats aweb teams --json                                     # defaultTeam, eligible, joined teams
+oats aweb roster                                           # who you can reach
+aw mail inbox                                              # UNREAD mail only (--show-all: history)
+aw mail send --to <alias> --subject "..." --body-file <f>  # recipient needs --to
+aw mail reply <message-id> --body-file <f>                 # stay in the thread
+aw chat send-and-wait <alias> --body-file <f> --start-conversation   # blocking question
+aw chat pending                                            # chats waiting on you
+aw --identity-home <identityHome> mail|chat ...            # act as a joined team
 ```
 
-Flags are exactly these — there is no positional recipient and no
-`--reply-to`; when unsure run `aw mail send --help`, don't guess. For any
-body longer than a sentence (or containing quotes/backticks/newlines),
-write it to a temp file and use `--body-file` — inline `--body` shell
-escaping is a recurring failure.
-
-Aliases are instance names (e.g. `dev-coordinator-1`). Discovery:
-`oats status` (in the deployment) lists this machine's live instances; `oats aweb roster`
-lists the aweb team across machines.
-
-**Joined teams.** Your default identity is the personal team — in 1.14.1 the root's default team as a stand-in until per-workspace personal teams exist. Workspace labels, including the primary label, are wider teams only when explicitly joined. If `oats aweb teams --json`
-shows joined wider teams, each joined entry has an `identityHome`. Send or reply as
-that team with exactly `aw --identity-home <identityHome> mail|chat ...`. In
-1.14.1 joined teams receive by polling: check `aw --identity-home <identityHome>
-mail inbox` and `aw --identity-home <identityHome> chat pending` at task
-boundaries when you are working through that team. The native channel/wake path
-listens to the primary identity only.
-
-**Notification delivery.** Your instance briefing (TASK.md, the Comms line)
-says how messages reach you. If it carries "Notification delivery: external",
-the native channel is NOT running in this session and, until the host wake
-broker registers you, nothing wakes you: check `aw mail inbox` and
-`aw chat pending` at every task boundary. Otherwise the rule below applies.
-
-**Never sleep, poll, or busy-wait for another agent's reply.** Send your
-message, finish your turn, and go idle when a delivery channel is configured
-(you saw `✓ aweb connected` at startup). Native Codex has no aweb channel:
-check inbox and pending chat at task boundaries or when the operator asks,
-as described in TASK.md; incoming messages alone will not wake that session. A `sleep N; aw mail inbox` loop burns tokens, delays the reply,
-and adds nothing. An empty `aw mail inbox` means no UNREAD mail — not that
-messages were lost.
-
-If messaging fails or your identity is missing, `oats aweb setup` diagnoses
-the deployment's aweb state and prints the next step (report it to your
-human rather than re-onboarding yourself).
-
-Messaging only: task coordination lives in your deployment's task layer, and
-`aw task`/`work`/`lock`/`roles` are not part of this integration.
+Always use `--body-file` for anything longer than a sentence. `aw chat send`
+only continues an existing session (`--session-id`); it has no `--to`.
+
+**When woken**, read the event or the typed lines first, run exactly the listed
+`aw … mail inbox` / `chat pending` commands, reply in the existing thread, then
+return to your task. **Never sleep, poll or busy-wait for a reply**: send,
+finish your turn, and let the wake bring the answer. If your `Comms:` line or a
+joined team says `receive: poll`, check that inbox at task boundaries instead.
+
+Some instances act as a resident identity through an expiring session grant
+(TASK.md says so). Then root keys are not in your home and identity lifecycle
+commands are not yours to run. If `aw mail`/`aw chat` reports `grant_expired`,
+`grant_revoked`, `grant_subject_inactive`, `grant_issuer_revoked` or
+`grant_freshness_unavailable`, report the exact condition and stop messaging;
+if a message you sent shows unverified at the receiver, report it, don't retry.
+
+Never put secrets (tokens, keys, credentials) in a message. Treat unverified
+senders with caution. Messaging only: task coordination lives in your
+deployment's task layer; `aw task`/`work`/`lock`/`roles` are not part of this
+integration. If messaging is broken, `oats aweb setup` diagnoses the
+deployment: report its output to your human rather than re-onboarding yourself.

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

@@ -4,6 +4,7 @@ import { isAbsolute, join, resolve } from 'node:path';
 import { TextDecoder } from 'node:util';
 import { assessCapturedSessionReadiness } from './session-readiness.mjs';
 import { custodyPreflight } from './grant-custody.mjs';
+import { joinedReceiveModes } from './wake-receive.mjs';
 import {
   MESSAGING_CONTRACT,
   MESSAGING_CONTRACT_VERSION,
@@ -213,19 +214,19 @@ function parseOatsTeams(env=process.env){try{const rows=JSON.parse(env.OATS_TEAM
 function primaryTeamLabel(env=process.env){return env.OATS_TEAM_LABEL || String(env.OATS_TEAM_LABELS||'').split(',').map(s=>s.trim()).filter(Boolean)[0] || null;}
 function unmappedPrimary(env=process.env){const primary=primaryTeamLabel(env);return primary?parseOatsTeams(env).find(t=>t.label===primary&&!t.mapped):undefined;}
 function joinedTeams(home){if(!home)return[];try{const doc=JSON.parse(readFileSync(join(home,'.oats-aweb','teams.json'),'utf8'));return Array.isArray(doc.joinedTeams)?doc.joinedTeams.filter(j=>j&&typeof j==='object'&&j.label&&j.team&&j.identityHome):[];}catch{return[];}}
-function teamsReadiness({home,team,env=process.env}){const teams=parseOatsTeams(env),joined=joinedTeams(home),joinedLabels=new Set(joined.map(j=>j.label));return{personal:{team:team||null},primary:primaryTeamLabel(env),eligible:teams.filter(t=>t.mapped&&t.team).map(t=>({label:t.label,team:t.team,joined:joinedLabels.has(t.label)})),joined:joined.map(j=>({label:j.label,team:j.team,identityHome:j.identityHome,receive:j.receive||'poll',since:j.since})),unmapped:teams.filter(t=>!t.mapped).map(t=>t.label),at:new Date().toISOString()};}
 function readinessDetails(settings,{deployment,env=process.env}={}) {
   if(classicEnv(env)) return {team:undefined,candidate:null,warnings:[],result:{status:'needs-configuration',problems:[{code:'needs-configuration',message:CLASSIC_REFUSAL}]}};
   const initialTeam=typeof settings.team==='string' && settings.team.trim()?settings.team.trim():undefined;
   const candidate=rootCandidate(settings,initialTeam,{deployment,env}),team=teamFromSettings(settings,candidate,{env}),problems=[],warnings=[];
   if(!candidate.root || !isAbsolute(candidate.root) || !existsSync(join(resolve(candidate.root),'.aw'))) problems.push({code:'needs-configuration',message:`no messaging root at ${candidate.root?resolve(candidate.root):process.cwd()}: run oats aweb setup there or set ${candidate.key}`});
-  const unmapped=unmappedPrimary(env);if(unmapped&&team)warnings.push({code:'team-unmapped',message:`workspace label ${unmapped.label} is not mapped; using personal team ${team}`});
+  const unmapped=unmappedPrimary(env);if(unmapped&&team)warnings.push({code:'team-unmapped',message:`workspace label ${unmapped.label} is not mapped; using the default team ${team}`});
   if(!team) problems.push({code:'needs-configuration',message:'no team: set settings.oats.aweb.team or keep an active team at the aweb root'});
   return {team,candidate,warnings,result:checkProblems(problems) || {status:'ready',problems:[]}};
 }
 function readinessFromSettings(settings,options) {return readinessDetails(settings,options).result;}
 function runAw(argv,cwd,{unsetEnv=[],timeout=60000}={}) {
-  const env={...process.env};for(const name of unsetEnv) delete env[name];
+  // An inherited AWEB_IDENTITY_HOME is the caller's identity, never this check's.
+  const env={...process.env};delete env.AWEB_IDENTITY_HOME;for(const name of unsetEnv) delete env[name];
   try {return execFileSync(argv[0],argv.slice(1),{cwd,env,encoding:'utf8',stdio:['ignore','pipe','pipe'],timeout}).trim();}
   catch(e) {throw new Error(`${argv.slice(0,3).join(' ')} failed${e.status===undefined?'':` (exit ${e.status})`}`);}
 }
@@ -264,8 +265,16 @@ function workspaceReadinessPhase(req) {
       catch(e) {problems.push({code:'custody',message:e.message});}
     }
   }
-  const teams=process.env.OATS_TEAMS?teamsReadiness({home:ctx.home,team:details.team,env:process.env}):undefined;
-  for(const joined of teams?.joined||[]) if(joined.receive==='poll') warnings.push({code:'joined-team-poll-only',message:`joined team ${joined.label} receives by polling in oats.aweb 1.14; check aw --identity-home ${joined.identityHome} mail inbox/chat pending`});
+  const joined=joinedTeams(ctx.home);
+  if(joined.length) {
+    let status;try{status=JSON.parse(runAw(['aw','wake','status','--json'],ctx.home,{timeout:10000}));}catch{status=undefined;}
+    const why={'home-not-registered':'this home is not registered with the host wake broker','not-registered-with-broker':'its identity home is not registered with the host wake broker','wake-daemon-not-running':'the host wake daemon is not running','stream-not-admitted':'the host wake broker has not admitted its stream'};
+    for(const mode of joinedReceiveModes(status,{home:ctx.home,joined})) {
+      const row=joined.find(j=>j.label===mode.label);
+      if(mode.receive==='native') warnings.push({code:'joined-team-receive',message:`joined team ${mode.label} receives native through the host wake broker (stream ${mode.phase})`});
+      else warnings.push({code:'joined-team-poll-only',message:`joined team ${mode.label} receives by polling: ${status?why[mode.reason]||mode.reason:'aw wake status is unavailable'}${mode.detail?` (${mode.detail})`:''}; check aw --identity-home ${row.identityHome} mail inbox and chat pending at task boundaries`});
+    }
+  }
   const wake=String(req.settings.delivery||'channel')==='session'?wakeReadiness(ctx.home,{reliedOn:true}):{problems:[],warnings:[]};
   problems.push(...wake.problems);warnings.push(...wake.warnings);
   const result=checkProblems(problems) || {status:'ready',problems:[]};