@awebai/oats 0.27.0 → 0.27.1

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

@@ -17,7 +17,7 @@
  *   OATS_CONTEXT   resolution context dir (the soul's repo / agents root parent)
  *   OATS_WORKSPACE the agents root's parent — the team boundary
  *   OATS_SETTINGS  JSON of the provider's `settings:` block
- *   OATS_TEAM_NAME/OATS_TEAM_ID/OATS_TEAM_SCOPE  resolved config `team:` block (may be empty)
+ *   OATS_TEAM_ID/OATS_TEAM_LABEL/OATS_TEAM_LABELS/OATS_TEAMS  workspace team facts (may be empty)
  *   OATS_META      JSON persisted from this hook's previous spawn output (retire only)
  *
  * Output (spawn, stdout JSON):
@@ -74,6 +74,8 @@ const run = (argv, cwd, timeout = 45000, { secrets = [], secretSafe = false, env
     const why = secretSafe ? "" : (scrub(e.stderr).trim() || (e.status === undefined ? String(e.code || "failed") : ""));
     const err = new Error(`${where} failed${e.status === undefined ? "" : ` (exit ${e.status})`}${why ? `: ${why}` : ""}${secretSafe ? " (output withheld: this command handles credentials)" : ""}`);
     err.status = e.status;
+    err.stdout = scrub(e.stdout).trim();
+    err.stderr = scrub(e.stderr).trim();
     // A classification, never the text: the caller may name a KNOWN failure
     // class (an alias that still holds a certificate) without any output of a
     // credential-handling command reaching a log.
@@ -158,10 +160,13 @@ try {
 
 const event = process.env.OATS_EVENT || process.argv[2];
 const instance = process.env.OATS_INSTANCE;
-const home = process.env.OATS_HOME || process.cwd();
+let 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";
+const CLASSIC_REFUSAL = "oats.aweb 1.14 needs OATS 0.26.0 or newer (workspace model); on an older kernel pin oats.aweb v1.13.x";
+const hasWorkspaceV2Facts = () => !!(process.env.OATS_WORKSPACE_KEY || process.env.OATS_WORKSPACE_NAME || process.env.OATS_TEAM_LABEL);
+const isClassicEnvironment = () => !!process.env.OATS_TEAM_SCOPE && !hasWorkspaceV2Facts();
 // 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):
@@ -175,51 +180,18 @@ 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 (isClassicEnvironment() && ["spawn", "setup"].includes(event)) {
+  if (event === "setup") { console.error(CLASSIC_REFUSAL); process.exit(1); }
+  fatal(CLASSIC_REFUSAL);
+}
 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;
-  return { team: fromSettings || fromEnv, payload: fromSettings, env: fromEnv };
+  return { team: fromSettings, payload: fromSettings, env: process.env.OATS_TEAM_ID || undefined };
 };
 const identityMeta = ({ mode = "local", alias, team, address = null, resident = null, grant }) => ({ mode, alias, team, address: address || null, resident: resident || null, ...(grant ? { grant } : {}) });
-
-/**
- * The aweb root (minting authority). BOUNDED candidates — the deployment's team
- * scope (from config `team:`) is the natural home; we never walk past the
- * workspace to the laptop root (a `.aw` there would be a different team;
- * minting into it would be a silent cross-team leak):
- *   1. the declared team scope (OATS_TEAM_SCOPE)
- *   2. the instance home itself
- *   3. the git repo root containing the home (if any)
- *   4. the resolution context (the soul's target repo) and its git repo root
- *   5. the workspace root (OATS_WORKSPACE — e.g. ~/lfx)
- * First candidate with a `.aw` wins; none → no minting.
- */
-function gitRootOf(startDir) {
-  let d = resolve(startDir);
-  while (true) {
-    if (existsSync(join(d, ".git"))) return d;
-    const parent = dirname(d);
-    if (parent === d) return undefined;
-    d = parent;
-  }
-}
-function classicAwebRoot() {
-  const candidates = [];
-  const push = (p) => { if (p && !candidates.includes(resolve(p))) candidates.push(resolve(p)); };
-  push(process.env.OATS_TEAM_SCOPE);
-  push(home);
-  push(gitRootOf(home));
-  push(process.env.OATS_CONTEXT);
-  if (process.env.OATS_CONTEXT) push(gitRootOf(process.env.OATS_CONTEXT));
-  push(process.env.OATS_WORKSPACE);
-  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)" : ""}`;
+const teamConfigRemedy = () => "set settings.oats.aweb.team or keep an active team at the aweb root";
 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 };
@@ -229,7 +201,7 @@ function declaredRootCandidate(team = payloadTeam().team) {
 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();
+  const fallback = process.env.OATS_WORKSPACE || process.cwd();
   return fallback ? { root: fallback, key: "settings.oats.aweb.root", declared: false } : undefined;
 }
 function awebRootProblem(candidate) {
@@ -241,7 +213,6 @@ 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;
@@ -257,7 +228,7 @@ const teamMemberships = (listed) => listed?.memberships || listed?.teams || [];
 const teamIdsOf = (listed) => teamMemberships(listed).map((m) => m.team_id || m.id || m);
 
 const AW_INSTALL = "install the aw CLI first — see https://aweb.ai/docs (or `oats aweb setup` for guided onboarding)";
-const isCommand = ["roster", "setup"].includes(event);
+const isCommand = ["roster", "setup", "teams", "join", "leave"].includes(event);
 if (!onPath("aw")) {
   if (isCommand) { console.error(`oats aweb ${event}: aw CLI not on PATH — ${AW_INSTALL}`); process.exit(1); }
   if (event === "spawn") fatal(`aw CLI not on PATH, so no identity could be minted and this instance would have no messaging — ${AW_INSTALL}`);
@@ -477,10 +448,15 @@ function globalGrantRenew() {
   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");
+  const resolvedTeam = payloadTeam();
   const resident = String(identitySettings.resident || "");
   const custody = resolveResidentCustody(resident);
+  let team = resolvedTeam.team;
+  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 (!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`);
   const scopes = grantScopes();
@@ -528,8 +504,7 @@ function globalGrantSpawn() {
         catch (revokeError) { failAfterMint(`session delivery registration failed for minted grant ${grantId}: ${e.message || e}; revoke failed: ${revokeError.message || revokeError}`); }
       }
     }
-    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 warnings = [...teamWarnings, ...preflight.warnings];
     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.`
@@ -573,10 +548,32 @@ const workspaceAliasOf = (homeDir) => {
  *  signing key, a team certificate and a workspace binding. */
 const joinedLate = (homeDir) => existsSync(join(homeDir, ".aw", "signing.key")) && existsSync(join(homeDir, ".aw", "team-certs")) && !!workspaceAliasOf(homeDir);
 const JOIN_TIMEOUT_MS = Number(process.env.OATS_AWEB_JOIN_TIMEOUT_MS) > 0 ? Number(process.env.OATS_AWEB_JOIN_TIMEOUT_MS) : 120000;
+// The first aw whose joined-team external homes are fully operable: local
+// accept-invite under --identity-home, hosted workspace auto-connect, self-release
+// and joined-root E2E key publication.
+const JOINED_TEAMS_AW_MIN = "1.36.12";
+function joinedTeamsAwFloorProblem() {
+  if (/^\d+\.\d+\.\d+$/.test(JOINED_TEAMS_AW_MIN) && awAtLeast(JOINED_TEAMS_AW_MIN)) return undefined;
+  if (!/^\d+\.\d+\.\d+$/.test(JOINED_TEAMS_AW_MIN)) return `E_TEAM_AW_FLOOR: joined-team identities need an aw release that admits local accept-invite under --identity-home, auto-connects the joined workspace and publishes the joined-root E2E key; installed aw is ${awVersionLabel()}. join= and oats aweb join are gated until that aw release exists`;
+  return `E_TEAM_AW_FLOOR: joined-team identities require aw >= ${JOINED_TEAMS_AW_MIN}; installed aw is ${awVersionLabel()}. join= and oats aweb join are gated until aw admits local accept-invite under --identity-home, auto-connects the joined workspace and publishes the joined-root E2E key`;
+}
+function requireJoinedTeamsAwFloor() {
+  const problem = joinedTeamsAwFloorProblem();
+  if (!problem) return;
+  const error = new Error(problem.replace(/^E_TEAM_AW_FLOOR: /, ""));
+  error.code = "E_TEAM_AW_FLOOR";
+  throw error;
+}
 const yamlScalar = (text, key) => {
   const m = String(text).match(new RegExp(`^${key}:\\s*["']?([^"'\\n#]+)["']?\\s*$`, "m"));
   return m ? m[1].trim() : undefined;
 };
+function activeTeamAt(root) {
+  try {
+    const text = readFileSync(join(resolve(root), ".aw", "teams.yaml"), "utf8");
+    return yamlScalar(text, "active_team") || yamlScalar(text, "active");
+  } catch { return undefined; }
+}
 function retainedSeatSpawn(source, takeOver) {
   if (typeof source !== "string" || !source.startsWith("/")) fatal("identity.source must be the absolute path of the legacy .aw directory to retain");
   if (!existsSync(join(source, "signing.key"))) fatal(`identity.source ${source} holds no signing.key, so there is no identity to retain`);
@@ -699,19 +696,209 @@ function retainedSeatSpawn(source, takeOver) {
   }
 }
 
+const LABEL_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+function parseOatsTeams(env = process.env) {
+  try {
+    const rows = JSON.parse(env.OATS_TEAMS || "[]");
+    return Array.isArray(rows) ? rows.filter((r) => r && typeof r === "object").map((r) => ({ label: String(r.label || ""), team: typeof r.team === "string" ? r.team : null, mapped: r.mapped === true, payload: r.payload && typeof r.payload === "object" ? r.payload : {} })) : [];
+  } catch { return []; }
+}
+function eligibleTeams() { return parseOatsTeams().filter((t) => t.mapped && t.label && t.team); }
+function labelsCsv(text) { return String(text || "").split(",").map((s) => s.trim()).filter(Boolean); }
+function primaryTeamLabel() { return process.env.OATS_TEAM_LABEL || labelsCsv(process.env.OATS_TEAM_LABELS)[0] || null; }
+function requestedJoinLabels() { return labelsCsv(settings.join); }
+function unmappedPrimaryRow() {
+  const primary = primaryTeamLabel();
+  return primary ? parseOatsTeams().find((t) => t.label === primary && !t.mapped) : undefined;
+}
+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";
+      throw error;
+    }
+    if (!LABEL_RE.test(label) || !byLabel.has(label)) {
+      const choices = eligible.map((t) => t.label).join(", ") || "(none)";
+      const error = new Error(`E_TEAM_NOT_ELIGIBLE: ${label} is not an eligible team label for this instance (eligible: ${choices})`);
+      error.code = "E_TEAM_NOT_ELIGIBLE";
+      throw error;
+    }
+  }
+  return labels.map((label) => byLabel.get(label));
+}
+const joinedTeamsOf = (meta = {}) => Array.isArray(meta.joinedTeams) ? meta.joinedTeams.filter((j) => j && typeof j === "object" && j.label && j.team && j.identityHome) : [];
+const providerStateDir = () => join(home, ".oats-aweb");
+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) }; }
+}
+function writeProviderTeamsState(meta) {
+  mkdirSync(providerStateDir(), { recursive: true, mode: 0o700 });
+  writeFileSync(providerTeamsFile(), JSON.stringify({ joinedTeams: joinedTeamsOf(meta) }, null, 2) + "\n", { mode: 0o600 });
+}
+function withProviderTeams(meta = {}) { return { ...meta, joinedTeams: readProviderTeamsState(meta).joinedTeams }; }
+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"); }
+function workspaceConnectRecovery(text) {
+  const m = String(text || "").match(/aw\s+--identity-home\s+\S+\s+workspace\s+connect\s+--service\s+\S+(?:\s+--json)?|aw\s+workspace\s+connect\s+--service\s+\S+(?:\s+--json)?|workspace\s+connect\s+--service\s+\S+(?:\s+--json)?/i);
+  return m ? m[0].trim() : undefined;
+}
+function joinedWorkspacePresent(identityHome) { return existsSync(join(identityHome, "workspace.yaml")); }
+function releaseReceiptStatus(doc) {
+  return doc && typeof doc === "object" && doc.alias_released === true ? "released" : undefined;
+}
+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 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;
+  return {
+    personal: { team: personalTeam },
+    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 })),
+    unmapped: teams.filter((t) => !t.mapped).map((t) => t.label),
+    at: new Date().toISOString(),
+  };
+}
+function mintJoinedTeam(row, meta) {
+  const existing = joinedTeamsOf(meta).find((j) => j.label === row.label);
+  if (existing) return { meta, joined: existing, changed: false };
+  requireJoinedTeamsAwFloor();
+  const identityHome = identityHomeForLabel(row.label);
+  const root = awebRootForTeam(row.team);
+  if (!root) throw new Error(`${awebRootProblem(rootSettingCandidate(row.team))}, so team ${row.label} could not be joined`);
+  const inv = parseSecretJson(run(["aw", "team", "invite", "--team-id", row.team, "--json"], root, 45000, { secretSafe: true }), "aw team invite");
+  if (!inv?.token || typeof inv.token !== "string") throw new Error(`aw team invite returned no usable token for ${row.label}`);
+  let raw, acceptWarning;
+  try {
+    raw = parseSecretJson(run(awWithIdentity(identityHome, ["id", "team", "accept-invite", inv.token, "--name", instance || meta.alias, "--local", "--json"]), home, JOIN_TIMEOUT_MS, { secrets: [inv.token], secretSafe: true }), "aw id team accept-invite");
+  } catch (e) {
+    const output = commandOutput(e);
+    const recovery = workspaceConnectRecovery(output);
+    let accepted;
+    try { accepted = parseAwJson(e.stdout || "", "aw id team accept-invite"); } catch { accepted = undefined; }
+    if (!accepted?.team_id) throw new Error(`aw id team accept-invite failed for joined team ${row.label}${recovery ? `; recovery: ${recovery}` : ""}`);
+    raw = accepted;
+    acceptWarning = `joined team ${row.label} was accepted but workspace connect failed${recovery ? `; recovery: ${recovery}` : "; rerun the aw workspace connect recovery command printed by aw"}`;
+  }
+  const alias = typeof raw.alias === "string" && AWEB_ALIAS_RE.test(raw.alias) ? raw.alias : (instance || meta.alias);
+  const team = typeof raw.team_id === "string" && raw.team_id ? raw.team_id : row.team;
+  if (team !== row.team) throw new Error(`joined team ${team} differs from requested ${row.team}`);
+  const joined = { label: row.label, team, identityHome, receive: "poll", since: new Date().toISOString(), alias };
+  const next = { ...meta, joinedTeams: [...joinedTeamsOf(meta), joined] };
+  if (!joinedWorkspacePresent(identityHome)) {
+    const recovery = workspaceConnectRecovery(JSON.stringify(raw)) || raw.recovery_command || raw.recoveryCommand;
+    return { meta: next, joined, changed: true, warning: acceptWarning || `joined team ${row.label} was accepted but no workspace connection was written under ${identityHome}${recovery ? `; recovery: ${recovery}` : "; rerun the aw workspace connect recovery command printed by aw"}` };
+  }
+  return { meta: next, joined, changed: true, ...(acceptWarning ? { warning: acceptWarning } : {}) };
+}
+function leaveJoinedTeam(label, meta) {
+  const joined = joinedTeamsOf(meta);
+  const entry = joined.find((j) => j.label === label);
+  if (!entry) return { meta, changed: false };
+  let receipt, released;
+  try {
+    receipt = parseAwJson(run(awWithIdentity(entry.identityHome, ["workspace", "delete", entry.alias || meta.alias || instance, "--json"]), home, 60000), "aw workspace delete");
+    released = releaseReceiptStatus(receipt);
+  } catch (e) {
+    throw new Error(`failed to leave team ${label}; kept ${entry.identityHome} so cleanup can be retried: ${String(commandOutput(e)).slice(0, 300)}`);
+  }
+  if (!released) throw new Error(`failed to leave team ${label}; workspace delete did not report alias_released: true; kept ${entry.identityHome} so cleanup can be retried: ${JSON.stringify(receipt)}`);
+  try { rmSync(entry.identityHome, { recursive: true, force: true }); } catch { /* best effort */ }
+  return { meta: { ...meta, joinedTeams: joined.filter((j) => j.label !== label) }, changed: true, released, receipt };
+}
+function awebRootForTeam(team) {
+  const declared = declaredRootCandidate(team);
+  if (declared && isAbsolute(declared.root) && existsSync(join(resolve(declared.root), ".aw"))) return resolve(declared.root);
+  if (declared?.declared) return undefined;
+  const candidate = rootSettingCandidate(team);
+  if (candidate && isAbsolute(candidate.root) && existsSync(join(resolve(candidate.root), ".aw"))) return resolve(candidate.root);
+  return undefined;
+}
+function parseHomeCommandArgs(argv = process.argv.slice(3)) {
+  const rest = [];
+  let json = false, labels;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") { json = true; continue; }
+    if (arg === "--home" && argv[i + 1]) { home = resolve(argv[++i]); process.env.OATS_HOME = home; continue; }
+    if (arg.startsWith("--home=")) { home = resolve(arg.slice("--home=".length)); process.env.OATS_HOME = home; continue; }
+    if (arg === "--labels" && argv[i + 1]) { labels = argv[++i]; continue; }
+    if (arg.startsWith("--labels=")) { labels = arg.slice("--labels=".length); continue; }
+    rest.push(arg);
+  }
+  if (!labels && rest[0]) labels = rest[0];
+  return { json, labels: labelsCsv(labels) };
+}
+function outputTeamsDocument(doc, json) {
+  if (json) { console.log(JSON.stringify(doc)); return; }
+  console.log(`personal: ${doc.personal.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}`);
+}
+function runTeamsCommand(kind) {
+  const args = parseHomeCommandArgs();
+  let meta = readCapabilityMeta();
+  const actions = [];
+  const warnings = [];
+  if (kind === "join" || kind === "leave") {
+    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}`);
+    }
+    writeProviderTeamsState(meta);
+  }
+  const doc = { ...teamsDocument(meta), ...(actions.length ? { actions } : {}), ...(warnings.length ? { warnings } : {}) };
+  outputTeamsDocument(doc, args.json);
+}
+
 if (event === "launch") {
   if (identityMode === "global" || grantRenewMode() === "launch") globalGrantRenew();
-  out(retainedLaunchOutput(JSON.parse(process.env.OATS_META || "{}")));
+  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; }
+      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(" | ")}` } : {}) });
+  }
+  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');
+  if (identityMode === "global" && requestedJoinLabels().length) fatal('settings.oats.aweb.join is supported only with local per-team identities; identity.mode "global" is explicit resident-grant mode');
   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 joinRows;
+  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();
-    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}`);
+    fatal(`${awebRootProblem(candidate)}, so no identity could be minted and this instance would have no messaging`);
   }
   try {
     // Team correctness: the config's `team:` block wins (id, then name), else the
@@ -721,9 +908,10 @@ if (event === "launch") {
     // cross-machine instance directory).
     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()}`);
+    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(":")) {
@@ -779,7 +967,7 @@ if (event === "launch") {
     run(["aw", "init", "--do-not-touch-agents-md"], home);
     const alias = joined.alias;
     const mismatch = joined.team_id !== team
-      ? ` [WARNING: joined ${joined.team_id}, expected ${team}]` : teamPayloadMismatch ? ` [WARNING: settings team ${resolvedTeam.payload} differs from OATS team ${resolvedTeam.env}; using payload team]` : "";
+      ? ` [WARNING: joined ${joined.team_id}, expected ${team}]` : "";
     // Runtime integration: for Claude Code sessions the aweb-channel plugin
     // carries real-time push events. This hook does NOT install it. The plugin
     // is a DECLARED runtime requirement (oats.json), consented once at
@@ -799,12 +987,17 @@ 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 }) };
+    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}`); }
+    writeProviderTeamsState(meta);
     out({
-      meta: { team: joined.team_id, alias, delivery: deliveryMode, identity: identityMeta({ mode: "local", alias, team: joined.team_id }) },
+      meta,
       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.`,
+      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.`,
       ...(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 } : {}),
+      ...(joined.team_id !== team ? { warning: `oats-aweb: team mismatch — joined ${joined.team_id}, expected ${team}` } : warnings.length ? { warning: warnings.join(" | ") } : channelWarning ? { warning: channelWarning } : {}),
     });
   } catch (e) {
     // A join may already have created a REMOTE identity before the failure.
@@ -813,16 +1006,23 @@ if (event === "launch") {
     fatal(`identity minting failed: ${e.message || e}`, minted);
   }
 } else if (event === "retire") {
-  let meta = JSON.parse(process.env.OATS_META || "{}");
+  let meta = withProviderTeams(JSON.parse(process.env.OATS_META || "{}"));
+  const retireWarnings = [];
   // 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" && (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.identity?.mode === "global" && !meta.retained) globalGrantRetire(meta);
+  for (const joined of joinedTeamsOf(meta)) {
+    try { meta = leaveJoinedTeam(joined.label, meta).meta; }
+    catch (e) { retireWarnings.push(`joined team ${joined.label} cleanup failed: ${e.message || e}`); }
+  }
+  writeProviderTeamsState(meta);
   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}` : ""}` });
+    const retainedWarning = `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}` : ""}`;
+    out({ meta: { retired: true, retained: true, identityReleased: true, joinedTeams: joinedTeamsOf(meta), ...(meta.tookOverFrom ? { tookOverFrom: meta.tookOverFrom } : {}) }, warning: `oats-aweb: ${[...retireWarnings, retainedWarning].join(" | ")}` });
   }
-  if (meta.identity?.mode === "global") globalGrantRetire(meta);
   // No alias means the spawn hook never reported an identity: nothing exists to
   // undo, which is completion. An alias WITH no local `.aw` is the opposite —
   // the remote record exists and its key is gone, so the self-delete cannot be
@@ -849,28 +1049,31 @@ if (event === "launch") {
       // 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 different --name (kernels 0.26.0+) or a different --purpose until it is` }) });
+      out({ meta: { retired: true, aliasReusable: released, aliasReason: reason, joinedTeams: joinedTeamsOf(meta) }, ...(retireWarnings.length ? { warning: `oats-aweb: ${retireWarnings.join(" | ")}` } : 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 different --name (kernels 0.26.0+) or a different --purpose` });
+    out({ meta: { retired: true, aliasReusable: false, joinedTeams: joinedTeamsOf(meta) }, warning: `oats-aweb: ${[...retireWarnings, `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`].join(" | ")}` });
   } 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
     // rolled back while a remote identity still exists.
     out({ meta: { retired: false, reason: "self-delete-failed" }, warning: `oats-aweb: self-delete failed (the remote record will linger until stale): ${e.message || e}` }, 1);
   }
+} 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); }
 } 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 --team`; this is the network view.
+  // `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 || process.env.OATS_TEAM_NAME || JSON.parse(run(["aw", "team", "list", "--json"], root)).active_team;
+  const team = process.env.OATS_TEAM_ID || 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));
@@ -904,11 +1107,8 @@ if (event === "launch") {
   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`);
+  const scope = candidate?.root ? resolve(candidate.root) : process.cwd();
+  console.log(`aweb onboarding — 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);
@@ -928,7 +1128,7 @@ if (event === "launch") {
       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`");
+      console.log("  Roster: `oats aweb roster`  ·  local: `oats status` (in the deployment)");
       return;
     }
     console.log(`readiness: needs-configuration`);
@@ -940,7 +1140,7 @@ if (event === "launch") {
       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.`);
+    if (defaultTeamForUsername) console.log(`  New hosted users create ${defaultTeamForUsername}; set 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).");
@@ -949,7 +1149,7 @@ if (event === "launch") {
   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"}).`);
+      console.log(`No aweb workspace at the 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");

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

@@ -49,9 +49,17 @@ 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 --team` lists this machine's live instances; `oats aweb roster`
+`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

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

@@ -83,10 +83,11 @@ export function parseBindingJson(bytes,limits=BINDING_WIRE_LIMITS) {
 function settings(value,{phase}={}) {
   if(!obj(value)) wireError('invalid-binding');
   if(phase!=='check' && Object.hasOwn(value,'identity')) wireError('provider-not-qualified');
-  keys(value,phase==='check'?['delivery','team','root','roots','identity','residents']:['delivery','team','root','roots'],[]);
+  keys(value,phase==='check'?['delivery','team','root','roots','identity','residents','join']:['delivery','team','root','roots','join'],[]);
   if(value.delivery!==undefined && !['channel','session'].includes(value.delivery)) wireError('needs-configuration');
   if(value.team!==undefined && (typeof value.team!=='string' || !value.team.trim())) wireError('needs-configuration');
   if(value.root!==undefined && (typeof value.root!=='string' || !value.root.trim())) wireError('needs-configuration');
+  if(value.join!==undefined && typeof value.join!=='string') wireError('needs-configuration');
   if(value.roots!==undefined && !obj(value.roots)) wireError('needs-configuration');
   if(obj(value.roots)) for(const [team,root] of Object.entries(value.roots)) if(!team || typeof root!=='string' || !root.trim()) wireError('needs-configuration');
   if(value.identity!==undefined && !obj(value.identity)) wireError('needs-configuration');
@@ -164,6 +165,9 @@ function workspaceReadinessContext(value) {
 }
 function yamlScalar(text,key){const m=String(text).match(new RegExp(`^${key}:\\s*["']?([^"'\\n#]+)["']?\\s*$`,'m'));return m?m[1].trim():undefined;}
 export const CUSTODY_ATTACH_MIN = '1.36.3';
+export const WAKE_STREAM_MIN = '1.36.5';
+const CLASSIC_REFUSAL = 'oats.aweb 1.14 needs OATS 0.26.0 or newer (workspace model); on an older kernel pin oats.aweb v1.13.x';
+function classicEnv(env=process.env) {return !!env.OATS_TEAM_SCOPE && !(env.OATS_WORKSPACE_KEY || env.OATS_WORKSPACE_NAME || env.OATS_TEAM_LABEL);}
 export function grantYamlCustodySocket(text) {
   const lines=String(text??'').split(/\r?\n/);let inCustody=false,baseIndent=0;
   for(const line of lines) {
@@ -189,27 +193,35 @@ function grantAttachmentProblem(home) {
   const id=yamlScalar(text,'grant_id')||'<unknown>';
   return {code:'custody',message:`grant ${id} is not attached to custody; retire and respawn on aw >= ${CUSTODY_ATTACH_MIN}`};
 }
-function activeTeamAt(root){try{return yamlScalar(readFileSync(join(resolve(root),'.aw','teams.yaml'),'utf8'),'active_team')||yamlScalar(readFileSync(join(resolve(root),'.aw','teams.yaml'),'utf8'),'active');}catch{return undefined;}}
+function activeTeamAt(root){try{const text=readFileSync(join(resolve(root),'.aw','teams.yaml'),'utf8');return yamlScalar(text,'active_team')||yamlScalar(text,'active');}catch{return undefined;}}
+function residentCustodyRoot(settings){const identity=obj(settings.identity)?settings.identity:{},residents=obj(settings.residents)?settings.residents:{};const name=typeof identity.resident==='string'?identity.resident:'';const root=name&&typeof residents[name]==='string'?residents[name]:undefined;return identity.mode==='global'&&root&&isAbsolute(root)?root:undefined;}
 function teamFromSettings(settings,candidate,{env=process.env}={}) {
-  const configured=typeof settings.team==='string' && settings.team.trim()?settings.team.trim():(env.OATS_TEAM_ID || env.OATS_TEAM_NAME || undefined);
-  if(configured || env.OATS_TEAM_LABEL) return configured;
+  const configured=typeof settings.team==='string' && settings.team.trim()?settings.team.trim():undefined;
+  if(configured) return configured;
+  const custody=residentCustodyRoot(settings);if(custody)return activeTeamAt(custody);
   return candidate?.root && isAbsolute(candidate.root) ? activeTeamAt(candidate.root) : undefined;
 }
-function classicEnv(env=process.env) {return !!env.OATS_TEAM_SCOPE && !(env.OATS_WORKSPACE_KEY || env.OATS_WORKSPACE_NAME || env.OATS_TEAM_LABEL);}
 function rootCandidate(settings,team,{deployment,env=process.env}={}) {
   const roots=obj(settings.roots)?settings.roots:{};
   if(team && typeof roots[team]==='string' && roots[team].trim()) return {root:roots[team].trim(),key:`settings.oats.aweb.roots[${JSON.stringify(team)}]`,declared:true};
   if(typeof settings.root==='string' && settings.root.trim()) return {root:settings.root.trim(),key:'settings.oats.aweb.root',declared:true};
-  const candidates=classicEnv(env)?[env.OATS_TEAM_SCOPE,env.OATS_WORKSPACE].filter(Boolean):[env.OATS_WORKSPACE || deployment || env.OATS_TEAM_SCOPE || process.cwd()];
+  const candidates=[env.OATS_WORKSPACE || deployment || process.cwd()];
   for(const root of candidates) if(isAbsolute(root) && existsSync(join(resolve(root),'.aw'))) return {root,key:'settings.oats.aweb.root',declared:false};
   return {root:candidates[0] || process.cwd(),key:'settings.oats.aweb.root',declared:false};
 }
+function parseOatsTeams(env=process.env){try{const rows=JSON.parse(env.OATS_TEAMS||'[]');return Array.isArray(rows)?rows.filter(r=>r&&typeof r==='object').map(r=>({label:String(r.label||''),team:typeof r.team==='string'?r.team:null,mapped:r.mapped===true,payload:obj(r.payload)?r.payload:{}})):[];}catch{return [];}}
+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}={}) {
-  const initialTeam=typeof settings.team==='string' && settings.team.trim()?settings.team.trim():(env.OATS_TEAM_ID || env.OATS_TEAM_NAME || undefined);
-  const candidate=rootCandidate(settings,initialTeam,{deployment,env}),team=teamFromSettings(settings,candidate,{env}),problems=[];
+  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}`});
-  if(!team) problems.push({code:'needs-configuration',message:'no team: set messaging.byTeam.<label>.team in the workspace file or settings.oats.aweb.team'});
-  return {team,candidate,result:checkProblems(problems) || {status:'ready',problems:[]}};
+  const unmapped=unmappedPrimary(env);if(unmapped&&team)warnings.push({code:'team-unmapped',message:`workspace label ${unmapped.label} is not mapped; using personal 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}={}) {
@@ -217,10 +229,25 @@ function runAw(argv,cwd,{unsetEnv=[],timeout=60000}={}) {
   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})`}`);}
 }
+function semverLt(a,b) {const A=String(a||'0.0.0').split('.').map(n=>Number(n)||0),B=String(b).split('.').map(n=>Number(n)||0);for(let i=0;i<3;i++){if((A[i]||0)!==(B[i]||0)) return (A[i]||0)<(B[i]||0);}return false;}
+function wakeReadiness(home,{reliedOn=false}={}) {
+  if(!home || !reliedOn) return {problems:[],warnings:[]};
+  try {
+    const doc=JSON.parse(runAw(['aw','wake','status','--json'],home,{timeout:10000}));
+    const state=doc.daemon_version_state || (doc.daemon_running===false?'not_running':doc.daemon_version?'reported':'unknown');
+    if(state==='reported') {
+      const running=String(doc.daemon_version||'unknown');
+      if(semverLt(running,WAKE_STREAM_MIN)) return {problems:[{code:'wake-daemon-outdated',message:`host wake daemon is running ${running}; required ${WAKE_STREAM_MIN}; upgrade aw, then restart the host wake daemon`}],warnings:[]};
+      return {problems:[],warnings:[]};
+    }
+    if(state==='not_running') return {problems:[{code:'wake-daemon-not-running',message:'host wake daemon is not running; session delivery relies on it'}],warnings:[]};
+    return {problems:[],warnings:[{code:'wake-daemon-version-unknown',message:`host wake daemon version is unknown; compatibility unproven; required ${WAKE_STREAM_MIN}; upgrade aw, then restart the host wake daemon`}]};
+  } catch {return {problems:[],warnings:[{code:'wake-daemon-version-unknown',message:`host wake daemon version is unknown; compatibility unproven; required ${WAKE_STREAM_MIN}; upgrade aw, then restart the host wake daemon`}]};}
+}
 function workspaceReadinessPhase(req) {
   const ctx=workspaceReadinessContext(req.input.context);
   if(!obj(req.input.action) || req.input.action.kind!=='readiness') wireError('invalid-binding');
-  const details=readinessDetails(req.settings,{deployment:ctx.deployment}),problems=[...details.result.problems],warnings=[];
+  const details=readinessDetails(req.settings,{deployment:ctx.deployment}),problems=[...details.result.problems],warnings=[...details.warnings];
   const identity=obj(req.settings.identity)?req.settings.identity:{},mode=identity.mode===undefined || identity.mode===null || identity.mode===''?'local':String(identity.mode);
   if(mode==='global') {
     const grantProblem=grantAttachmentProblem(ctx.home);if(grantProblem) problems.push(grantProblem);
@@ -237,6 +264,10 @@ 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 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:[]};
   return {...result,warnings};
 }

package/capabilities/oats-aweb/oats.json

@@ -1,9 +1,9 @@
 {
   "capability": "oats.aweb",
   "command": "aweb",
-  "version": "1.13.1",
+  "version": "1.14.2",
   "compatibility": {
-    "oats": ">=0.25.6"
+    "oats": ">=0.26.0"
   },
   "layer": "messaging",
   "description": "Messaging layer via aweb: per-instance team identities + native aw mail/chat skills + cross-machine team roster.",
@@ -71,7 +71,10 @@
     "setup": "bin/oats-aweb.mjs setup",
     "binding-normalize": "bin/oats-aweb-binding.mjs normalize",
     "binding-bind": "bin/oats-aweb-binding.mjs bind",
-    "binding-check": "bin/oats-aweb-binding.mjs check"
+    "binding-check": "bin/oats-aweb-binding.mjs check",
+    "teams": "bin/oats-aweb.mjs teams",
+    "join": "bin/oats-aweb.mjs join",
+    "leave": "bin/oats-aweb.mjs leave"
   },
   "binding": {
     "version": 1,
@@ -138,7 +141,7 @@
       "description": "channel: the native aweb channel packages wake the instance (default). session: delivery is external (AWEB_DELIVERY=session), no channel flag; the host wake broker registers the instance once it exists."
     },
     "team": {
-      "description": "Target aweb team id for identity lifecycle. In workspace v2 spawns this payload value wins over OATS_TEAM_ID/OATS_TEAM_NAME; if both are set and differ the hook warns and uses this setting."
+      "description": "Target aweb team id for the primary personal identity lifecycle. In workspace v2 spawns this payload value wins over OATS_TEAM_ID; if both are set and differ the hook warns and uses this setting."
     },
     "root": {
       "hostOnly": true,
@@ -157,9 +160,48 @@
     "residents": {
       "hostOnly": true,
       "description": "Host-owned map for global mode: resident name to absolute custody directory whose .aw holds the resident root keys and team certificate. Put this only in oats-local.yaml settings.oats.aweb.residents; committed workspace or soul files must never carry custody paths."
+    },
+    "join": {
+      "description": "comma-separated eligible team labels to join at spawn; values are workspace-defined labels and the default is absent"
     }
   },
   "environmentNamespaces": [
     "AWEB_"
-  ]
+  ],
+  "operations": {
+    "teams": {
+      "kind": "action",
+      "command": "teams",
+      "context": "home",
+      "description": "Read-only structured JSON summary of eligible and joined aweb teams for this home."
+    },
+    "join": {
+      "kind": "action",
+      "command": "join",
+      "context": "home",
+      "description": "Join comma-separated eligible aweb team labels for this home.",
+      "args": [
+        {
+          "name": "labels",
+          "flag": "--labels",
+          "required": true,
+          "description": "Comma-separated eligible team labels to join."
+        }
+      ]
+    },
+    "leave": {
+      "kind": "action",
+      "command": "leave",
+      "context": "home",
+      "description": "Leave comma-separated joined aweb team labels for this home.",
+      "args": [
+        {
+          "name": "labels",
+          "flag": "--labels",
+          "required": true,
+          "description": "Comma-separated joined team labels to leave."
+        }
+      ]
+    }
+  }
 }

package/capabilities/oats-aweb/skills/aweb-team-membership/SKILL.md

@@ -1,328 +1,106 @@
 ---
 name: aweb-team-membership
-description: This skill should be used when joining or being added to an aweb team, picking the correct invite/add-member path for the team's authority model (hosted vs BYOT), accepting invites, fetching team certificates, switching the active team across multiple memberships, distinguishing hosted from Bring Your Own Team (BYOT) authority, running the fresh BYOT setup into aweb cloud, or diagnosing team-certificate and active-team failures. Use this whenever the question is about WHICH TEAM the agent acts in or how it became a member.
-allowed-tools: "Bash(aw *)"
+description: This skill should be used when reasoning about which aweb/OATS teams an agent belongs to, checking team certificates and active-team diagnostics, or using the OATS provider's team operations (`oats aweb teams|join|leave`). Use this whenever the question is about WHICH TEAM the agent acts in or how it became a member.
+allowed-tools: "Bash(aw workspace status), Bash(aw team list), Bash(aw id cert show), Bash(oats aweb *)"
 ---
 
-# aweb Team Membership
+# aweb Team Membership for OATS agents
 
-Use this skill when the question is about teams — joining, leaving, switching between, or troubleshooting team certificates. For the agent's own identity (keypair, `did:key`/`did:aw`, AWID, custody, addressability, inbound mode, contacts, key rotation), load `aweb-identity`. For day-to-day work coordination, load `aweb-coordination`. For mail/chat policy, load `aweb-messaging`. For creating a new team from a template, load `aweb-bootstrap`.
+Use this skill when the question is about teams: current membership, eligible
+workspace teams, joined wider teams, team certificates, or why a message/command
+is landing in the wrong team. For identity keys, `did:key`/`did:aw`, custody,
+addressability, inbound mode, contacts, or key rotation, load `aweb-identity`.
+For mail/chat policy, load `aweb-messaging`.
 
-## Foundations
+## OATS owns agent team changes
 
-This skill builds on the identity vocabulary in `aweb-identity` (keypair, `did:key`, `did:aw`, AWID, custodial vs self-custodial). Read that section first if any of those terms are unfamiliar. Team-specific additions:
+For an OATS-managed instance, do **not** manually run native `aw team` mutation
+commands to join, switch, invite, or leave teams. The `oats.aweb` provider owns
+those lifecycle effects so it can keep per-team identity homes, provider state,
+retire cleanup, readiness, and Desktop operations consistent.
 
-- **Team controller** — a keypair separate from member identities. Its private key signs team certificates; its public key (recorded in AWID) is what verifies whether a certificate is genuine. Team controllers authorize membership; they do not decrypt member conversations and must not substitute a member's E2E encryption key.
-- **Team certificate** — a signed statement that a specific `did:key` is a member of a specific team, with an alias and metadata. Public; replicated in AWID. Stored locally in `.aw/team-certs/*.pem`. A certificate proves team membership; it is not a message-decryption key.
-- **Team id** — canonical form is `<name>:<namespace>` (e.g. `personal:acme.com`, `aweb:juan.aweb.ai`). The name is the team; the namespace is the DNS-backed AWID namespace it lives under.
-- **Hosted vs BYOT team authority** — *hosted* means aweb holds the team controller signing key (for `*.aweb.ai` namespaces). *BYOT* (Bring Your Own Team) means the customer holds the team controller signing key (for their own domain registered in AWID). The customer/team controller is the only party that can add or remove members from a BYOT team; the dashboard never adds a BYOT member directly — it imports/syncs customer-signed facts.
-
-## Team-related files in `.aw/`
-
-For identity files (`signing.key`, `workspace.yaml` server URL), see `aweb-identity`. Team-specific files:
-
-- `teams.yaml` — local index of teams this identity is a member of. Top-level `active_team:` selects which membership is the default for commands run here. `aw team list` reads this; `aw team switch <team-id>` updates it.
-- `team-certs/*.pem` — public team certificates this identity has been issued (one `.pem` per team membership). `teams.yaml` and `workspace.yaml` reference these by `cert_path`.
-
-## Custody × Authority matrix
-
-Identity custody (where the private key lives) and team authority (who holds the team controller key) are independent axes. Use the matrix to pick the right joining path:
-
-| Team authority | Identity custody | Meaning |
-| --- | --- | --- |
-| Hosted | Custodial | aweb manages team authority AND holds hosted identity signing key material (browser/MCP). Messaging in this mode is server-readable hosted messaging, not E2E. |
-| Hosted | Self-custodial | aweb manages team authority; the terminal agent holds its own `.aw/signing.key`. |
-| BYOT | Self-custodial | the customer controls team authority; the agent holds its own key. |
-| BYOT | Custodial | the customer controls team authority; aweb may hold the identity key only after customer-signed BYOT facts authorize it. |
-
-A custodial identity has **no BYOT team authority** until the customer-signed team certificate and address facts match. Do not infer team authority from identity custody.
-
-For E2E messaging, custody and team membership are still not enough by themselves: the recipient's encryption public key must be identity-authorized as described in `docs/e2e-messaging-contract.md`. Team/namespace authority may distribute that assertion, but it must not replace the member's key. If an encryption-key check fails, do not suggest a team-controller workaround or plaintext fallback; stop and route the user to the approved identity/key setup or recovery flow.
-
-## Readiness checks (membership level)
-
-Start with:
-
-```bash
-aw workspace status
-aw team list
-aw id cert show
-```
-
-Interpret failures by what's missing (for self-custodial CLI workspaces; custodial browser/MCP identities live entirely in the hosted account):
-
-- **`.aw/teams.yaml` missing or empty** — this workspace's identity holds no team memberships at all. Join one (see paths below) before attempting team coordination.
-- **No `.aw/team-certs/<team>.pem` for `teams.yaml`'s active team** — identity exists but holds no cert for the active team. Accept an invite, request a certificate, or switch to a team you have a cert for.
-- **Active team mismatch** — `teams.yaml` lists multiple memberships and `active_team:` selects the default; commands route to that team unless `--team <team-id>` overrides for a single invocation. If commands appear to land in the wrong team, fix `active_team:` (run `aw team switch <team-id>`).
-- **Workspace not bound to a server** — `workspace.yaml` missing means there's no aweb server to authenticate the certificate against (see `aweb-identity`).
-
-## Joining a team — match the path to team authority
-
-The right joining path depends entirely on **who holds the team controller signing key**. Pick by authority, not by the word "invite" alone.
-
-### Hosted teams (aweb holds the team controller key)
-
-Three distinct paths exist; they are NOT interchangeable.
-
-**Path 1 — Fresh identity at init time.** A new agent without any prior identity arrives at a hosted team via OAuth (browser/MCP) or team API-key (CLI):
-
-```bash
-AWEB_API_KEY=<team-api-key> aw init
-```
-
-The hosted service provisions the identity and a team certificate together. Browser/MCP harnesses do this through OAuth without a CLI. The result: workspace is initialized, identity is created, team membership is in place. Verify with `aw workspace status` and `aw team list`.
-
-**Path 2 — Existing global identity → "Add existing identity" in the dashboard.** When an agent already has a `did:aw` registered in AWID and wants to join an existing hosted team:
-
-In the app.aweb.ai dashboard, an owner/admin clicks "Add existing identity" on the team, supplies the global identity's address or `did:aw`, and the backend mints a team certificate with the cloud-held team controller key, registers it in AWID, and prints commands like:
-
-```bash
-aw id team fetch-cert --namespace <namespace> --team <team> --cert-id <cert-id>
-aw team switch <team>:<namespace>
-aw init   # if the joining directory still needs server binding
-```
-
-No token round-trip. Direct controller-mint. Available only for hosted teams because BYOT controller keys aren't held by aweb.
-
-**Path 3 — CLI invite-token, for hosted self-custodial local or global identities.** Hosted CLI invite tokens are redeemed through the cloud, but the accepting directory keeps its own signing key. Use the default form when the owner wants to invite a new local-workspace identity by token:
-
-```bash
-# Owner side (in a workspace with the necessary authority):
-aw team invite                 # local-workspace member token
-
-# share the printed <token>
-
-# Joiner side (in a clean target directory):
-aw team join <token> --name <name>
-aw init                        # finish wiring the new workspace if instructed
-```
-
-`accept-invite` refuses to overwrite an existing `.aw/` identity and generates a fresh local self-custodial identity in the target directory before requesting the certificate. For a hosted global identity, accept the hosted token with `--address <domain>/<name>`:
-
-```bash
-aw team join <token> --address <domain>/<name>
-aw init                        # finish wiring the new workspace if instructed
-```
-
-In the hosted `--address` case, the CLI creates a fresh self-custodial global identity for the address, registers it through the hosted service, and installs the hosted team certificate. The hosted service signs the team certificate; it does not receive the accepting directory's private signing key. If the user already has a global identity and only needs a certificate for an existing hosted team, Path 2 (dashboard Add existing identity + `fetch-cert`) remains valid.
-
-This is **not** the cross-machine BYOT path. Do not present it as the normal way to join a BYOT team from another machine.
-
-**Do not run `aw id team add-member` for a hosted team** — `add-member` signs a certificate with the team controller key, which you do not hold for hosted teams. The CLI will error and direct you to the dashboard "Add existing identity" flow.
-
-### BYOT teams (customer holds the team controller key)
-
-The dashboard cannot add BYOT members directly. The customer's team controller must sign. Three cases:
-
-**Case 1 — Self-custodial identity, cross-machine join.** The joining machine doesn't hold the team controller key:
-
-```bash
-# Joining identity machine
-aw id team request --team <team>:<namespace> --name <name>
-
-# Controller machine — runs the exact command the request printed:
-aw id team add-member ...
-
-# Back on the joining identity machine
-aw id team fetch-cert --namespace <namespace> --team <team> --cert-id <id>
-aw team switch <team>:<namespace>
-aw init   # if needed
-```
-
-The team controller private key never leaves the controller machine.
-
-**Case 2 — Custodial browser identity into a BYOT team.** Start from the dashboard's "Create custodial request" action. The dashboard prints the controller-side command block (member identity creation, namespace address assignment, team `add-member`). The team controller runs that block on their machine, then syncs the signed team state into aweb cloud:
-
-```bash
-aw id team import-request --team <team> --namespace <namespace> --cloud-team-id <cloud-team-id> --apply
-```
-
-aweb cloud projects the customer-signed facts; it does not mint anything itself. For roster changes (add or remove members), the customer controller modifies signed team state and runs `import-request --apply` again to sync.
-
-**Case 3 — Same-machine local-controller invite-token convenience.** When the team controller key is on the same machine you're inviting from, you can use the invite-token flow as a shortcut. Two variants:
-
-```bash
-# Owner side, same machine, local-controller key present:
-aw team invite                 # local-workspace member (default)
-aw team invite --global        # global-member token (requires existing global identity in the accepting directory)
-
-# Joiner side (still same machine, different directory):
-
-# For a local invite:
-aw team join <token> --name <name>
-
-# For a global invite, the accepting directory must already have a global identity:
-aw id create --domain <domain> --name <name>
-aw team join <token> --address <namespace>/<name>
-```
-
-For the `--global` case, `accept-invite` does NOT create the global identity — it errors with `no identity found; run aw id create first, or use --local invite` if no identity is present. `--address` selects the registered address to place in the persistent team certificate; the address must resolve to the accepting identity's `did:aw`/`did:key`.
-
-This is the local-controller convenience case only. For cross-machine BYOT joins, use Case 1.
-
-### Not a membership path: human dashboard invites
-
-`/api/v1/teams/.../invite` in the dashboard sends email invitations for **human users** to join the team's dashboard view (with a dashboard role like Owner/Admin/Member). That is independent of AWID agent membership certificates. Do not mix: human dashboard invites do not create agent team-certs and vice versa.
-
-## Accepting an invite vs fetching a certificate
-
-Two distinct local actions install a membership:
-
-- **`aw team join <token>`** (human-facing alias for `aw id team accept-invite <token>`) — redeems a CLI invite token. For hosted invites (Path 3), generates a fresh self-custodial identity in the current directory (refusing to overwrite) and installs the certificate; default is local, while `--address <domain>/<name>` creates/registers a fresh global identity through the hosted service before certificate install. For local-controller same-machine invites (BYOT Case 3), local-member behaves the same way as hosted local; global accepts require an existing global identity (from `aw id create`) and attach a team certificate to it via `--address <namespace>/<name>`.
-- **`aw id team fetch-cert --namespace <namespace> --team <team> --cert-id <id>`** — installs a certificate that has already been minted server-side (by hosted "Add existing identity") or signed by a controller (BYOT `add-member`). Used for hosted Path 2 and BYOT Case 1.
-
-If you have a token, use `aw team join` (or the underlying primitive `aw id team accept-invite`). If you have a `cert-id` printed by the dashboard or controller, use `fetch-cert`.
-
-## Multiple team memberships
-
-One identity can hold multiple team certificates simultaneously — one per team — all stored in `.aw/team-certs/`. Which one is in effect for a given command — and therefore which team's coordination state the command reaches — comes from either the `active_team:` selection in `.aw/teams.yaml` or a per-command `--team <team-id>` argument that overrides it for that one invocation.
-
-```bash
-aw team list                             # see memberships
-aw team switch <team>:<namespace>        # update teams.yaml's active_team
-aw <verb> --team <team>:<namespace> ...  # one-off override for team-scoped commands
-aw team leave <team>:<namespace>         # remove a local membership
-```
-
-Acting in the wrong active team can send messages, claims, or locks to the wrong coordination boundary. Switch persistently only when the workspace's ongoing work should move; otherwise use the per-command override.
-
-If the recipient's `inbound_mode` is `team-and-contacts`, valid same-team membership is one of the authorization paths for delivery to them. The full inbound-mode model is in `aweb-identity`.
-
-## Fresh BYOT setup into aweb cloud
-
-Use this flow when the user controls DNS for a domain and wants to create a customer-controlled AWID team, add agents, and import/sync it into app.aweb.ai.
-
-Vocabulary:
-
-- The namespace is the domain, e.g. `juanreyero.com`.
-- The team is named inside that namespace, e.g. `personal`; its AWID team id is `personal:juanreyero.com`.
-- Agents have addresses under the namespace, e.g. `juanreyero.com/alpha`.
-- Do not call `personal:juanreyero.com` an agent; it is the team id.
-
-Before starting, confirm `aw version` includes `aw id namespace prepare-controller` and `aw id namespace check-txt`; older `aw` versions make this flow hard to drive from non-interactive harnesses.
-
-**Use `aw id create`, NOT `aw init --byod --global`, for the identity-prep commands in this section.** `aw init --byod --global` is workspace onboarding: it bootstraps the directory and connects it to the `default:<domain>` team on app.aweb.ai (the team created during BYOD onboarding), writing `workspace.yaml`, joining that team, and minting a team certificate. That short-circuits the controller-signed team-state import this section is about. `aw id create` only mints the identity in AWID and writes `.aw/identity.yaml` + `.aw/signing.key`, leaving the team membership for the customer controller to add and sign. If a user already ran the wrong command and needs to recover, see the matching diagnostic bullet in `aweb-identity`'s readiness checks.
-
-Namespace controller setup (does not create an identity or team):
-
-```bash
-aw id namespace prepare-controller --domain <domain>
-```
-
-Pause and have the human add the printed `_awid.<domain>` TXT record. Do not invent DNS values. Tell the human to back up `~/.awid` now; it contains the namespace controller key. After DNS propagates, verify it:
-
-```bash
-aw id namespace check-txt --domain <domain>
-```
-
-Then create the BYOT team with the namespace controller key:
-
-```bash
-aw id team create --namespace <domain> --name <team> --display-name "<display name>"
-```
-
-After team creation, tell the human to back up `~/.awid` again; it now also contains the team controller key under `~/.awid/team-keys/<domain>/<team>.key`.
-
-Add initial global agents:
-
-```bash
-aw id create --domain <domain> --name alpha
-aw id team add-member --team <team> --namespace <domain> --did <alpha_did_key> --name alpha --global --did-aw <alpha_did_aw>
-
-aw id create --domain <domain> --name beta
-aw id team add-member --team <team> --namespace <domain> --did <beta_did_key> --name beta --global --did-aw <beta_did_aw>
-```
-
-Use the actual `did`/`did_aw` values printed by `aw id create`. Do not guess them.
-
-Register with aweb cloud without using the dashboard:
-
-```bash
-aw id team register --service https://app.aweb.ai --team <team>:<domain>
-```
-
-This signs a service-registration request with the team controller key. It creates or syncs an aweb projection of the AWID team, but it does not upload controller private keys, create identities, or initialize any agent workspace. Read the returned next steps and run the required workspace connection command from each already-certified agent directory:
-
-```bash
-aw workspace connect --service https://app.aweb.ai --team <team>:<domain>
-# equivalent service-oriented primitive: aw service init --service https://app.aweb.ai --team <team>:<domain>
-```
-
-`aw workspace connect` / `aw service init` requires the local `.aw/signing.key`, `.aw/teams.yaml`, and `.aw/team-certs/*.pem` for that agent. If the certificate is not installed yet, fetch it first with the certificate id returned by `aw id team add-member`:
+Use the provider commands from the instance home (or with `--home <path>`):
 
 ```bash
-aw id team fetch-cert --namespace <domain> --team <team> --cert-id <cert-id>
+oats aweb teams --json                  # personal, eligible, joined, unmapped
+oats aweb join --labels <label>[,<label>]   # join eligible workspace labels
+oats aweb leave --labels <label>[,<label>]  # leave joined wider-team labels
 ```
 
-After at least one workspace is initialized, the service may suggest a human-claim command such as:
+- The personal team cannot be left; attempting it is `E_TEAM_PERSONAL`.
+- A label that is not eligible for this soul/workspace is `E_TEAM_NOT_ELIGIBLE`.
+- Joined wider teams use a local identity home such as
+  `<home>/.aweb-identity-<label>` and receive by polling in oats.aweb 1.14. Joined teams require aw >= 1.36.12. The provider creates joined homes with `aw id team accept-invite` under `--identity-home`, verifies the root auto-connected, and does not run `aw init` inside the per-team home.
+- Send as a joined team with exactly:
 
 ```bash
-aw claim-human --email you@example.com
+aw --identity-home <identityHome> mail|chat ...
 ```
 
-`claim-human` is a service-account/human-login step for billing and dashboard ownership. It is not AWID team-controller authority and it does not add members to the BYOT team.
+`oats aweb teams --json` prints each joined entry's `identityHome` and
+`receive` mode.
 
-Import into an existing aweb organization:
+## Readiness checks
 
-1. In app.aweb.ai, create or select the owner organization that should contain the imported team.
-2. Open the BYOT import flow. Prefer the command shown by the dashboard because it contains the correct `--organization-id`.
-3. First preview:
+Start with read-only diagnostics:
 
 ```bash
-aw id team import-request --team <team> --namespace <domain> --organization-id <org-id>
-```
-
-Paste the signed output and use Preview.
-
-4. If the preview is correct, regenerate an apply request:
-
-```bash
-aw id team import-request --team <team> --namespace <domain> --organization-id <org-id> --apply
-```
-
-Paste it and use Import / sync.
-
-Sync later changes:
-
-- After the team exists in aweb cloud, use `--cloud-team-id <cloud-team-id>` instead of `--organization-id`.
-- The dashboard Connect / Sync page should show the exact command. Prefer that command.
-
-```bash
-aw id team import-request --team <team> --namespace <domain> --cloud-team-id <cloud-team-id> --apply
+aw workspace status
+oats aweb teams --json
+aw team list
+aw id cert show
 ```
 
-## Diagnostic recipes
-
-### "I am in two teams; what does that entail?"
-
-Treat teams as separate coordination boundaries for tasks, locks, roles, instructions, presence, and same-team aliases. Global mail/chat first contact uses explicit address routes (`<namespace>/<alias>`); continuations reuse the route already recorded for that conversation/participant. Confirm `active_team:` in `teams.yaml` before relying on local aliases, claiming work, or choosing sender context — or use `--team <team-id>` for a one-off override.
-
-### "Team cert or active team mismatch"
-
-Inspect `.aw/teams.yaml` and `.aw/team-certs/`. Confirm:
-- a `.pem` file exists for each team you expect to be a member of;
-- `teams.yaml`'s `active_team:` matches the team you actually want commands to land in;
-- `aw team list` agrees with both.
-
-Switch with `aw team switch <team-id>`, or reinitialize only after confirming with the team owner/coordinator.
-
-### "X says they cannot reach me"
-
-First check the route + inbound mode on the recipient side — full model in `aweb-identity`. Then, for `team-and-contacts` recipients, check shared team membership:
-
-1. `aw team list` on both sides — do you have a certificate in a common team?
-2. `.aw/team-certs/` — is the certificate present for that team?
-3. Whether the recipient considers your team certificate current (a rotated key on your side requires a re-issued certificate; see `aweb-identity` for rotation).
-
-### "I joined a team but commands hit the wrong one"
-
-The new membership added a `.pem` to `team-certs/` and a row in `teams.yaml`, but `active_team:` may not have updated. Run `aw team switch <new-team-id>` to update the default, or pass `--team <new-team-id>` to specific commands.
+Interpret common states:
+
+- `teams.personal.team` is the primary personal team identity wired to the
+  harness.
+- `eligible[]` are labels this soul/workspace may explicitly join; the primary
+  label may appear here and is joinable/leavable like any other wider team.
+- `joined[]` are provider-created wider-team memberships; each has an
+  `identityHome`, `since`, and `receive` (`poll` in 1.14).
+- `unmapped[]` labels are present on the soul but not mapped by the workspace.
+  An unmapped primary falls back to the personal/root active team with a
+  `team-unmapped` warning; it is not a spawn blocker.
+- `teams-unverified` on launch means the kernel supplied recorded/unknown team
+  data, so the provider kept memberships instead of leaving anything.
+
+## Team vocabulary
+
+- **Team id**: canonical form `<name>:<namespace>` (for example
+  `default:oats.aweb.ai`).
+- **Team certificate**: a signed membership statement for an identity; stored in
+  `.aw/team-certs/` for native identities.
+- **Personal team**: the default team for the instance's primary identity. In
+  1.14.1, until per-workspace personal teams are available, this may be the
+  person's default team as a stand-in.
+- **Joined team**: an explicit wider team joined through `oats aweb join`, with a
+  separate local identity home in this release.
+
+## Hosted vs BYOT authority (diagnostic context)
+
+Hosted teams are signed by aweb-held team authority; BYOT teams are signed by a
+customer-held controller. This matters when diagnosing why a human or provider
+cannot mint a certificate, but ordinary OATS agents should still use
+`oats aweb join|leave` rather than native membership mutation commands. If a
+join reports authorization failure, ask the team's owner/admin for the needed
+invite or mapping; do not invent a native workaround.
+
+## Wrong team symptoms
+
+If commands appear to use the wrong team:
+
+1. Run `oats aweb teams --json` and confirm which identity home should send.
+2. For the primary identity, run `aw workspace status` and `aw team list`.
+3. For a joined team, run `aw --identity-home <identityHome> mail inbox` or
+   `aw --identity-home <identityHome> chat pending` and send with the same
+   `--identity-home`.
+4. If the provider state and native files disagree, report the exact output to a
+   coordinator; do not hand-edit `.aw` or `.oats-aweb/teams.json`.
 
 ## References
 
-Read these only when deeper context is needed:
+Read only when deeper context is needed:
 
-- `references/team-membership-reference.md`: detailed hosted/BYOT and diagnostic notes.
 - <https://aweb.ai/docs/teams/>: team model.
-- <https://github.com/awebai/aweb/blob/main/docs/byot-onboarding-contract.md>: fully hosted vs BYOT contract.
-- <https://aweb.ai/docs/agent-guide/>: full agent guide.
+- <https://aweb.ai/docs/agent-guide/>: agent messaging guide.

package/docs/packages.md

@@ -74,7 +74,7 @@ members:
 packages:
   oats.framework: v1.1.3
   oats.okf: v2.1.5
-  oats.aweb: v1.13.1
+  oats.aweb: v1.14.2
 teams:
   global: { description: Org-wide }
   engineering: { description: Platform }

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

@@ -0,0 +1,29 @@
+# OATS 0.27.1
+
+## Changed
+
+- **oats.aweb 1.14.2 is bundled and pinned** (was 1.13.1): **joining teams
+  beyond the personal one now works.** An instance joins the eligible teams it
+  is given at spawn (`--provider oats.aweb join=<labels>`) or later with
+  `oats aweb join <labels>` / the Desktop's Teams controls, and leaves with
+  `oats aweb leave <labels>`. Each joined team gets its own identity under the
+  instance home. Joined teams **poll** (their mail is read between tasks); live
+  receive for joined teams is planned for oats.aweb 1.15. Joining needs
+  **aw 1.36.12 or later** (older aw answers `E_TEAM_AW_FLOOR`; the primary
+  identity still mints). A leave removes the local identity only after aweb
+  confirms the membership is released, so a failed leave can be retried.
+  Retire leaves every joined team before releasing the primary identity.
+- The framework workspace (`oats-workspace.yaml`) pins oats.aweb v1.14.2.
+- Skip oats.aweb 1.14.0 and 1.14.1 (tagged, never pinned by an OATS release): their binding check answered a `teams` key that OATS rejects, so `oats readiness` showed messaging unknown; 1.14.2 fixes it, and 1.14.0's joins were refused by aw.
+
+## Known limitations
+
+- The bundled oats.okf is still 2.1.5: its harvest worker spawns with `--runtime`, so each harvest answers one `deprecated-runtime-name` warning on 0.27.x. It's harmless; oats.okf 2.1.6 passes `--harness`.
+
+- A per-workspace personal team still needs oats.aweb 1.15 (the aweb service
+  and CLI already carry personal enrollment); until then "personal" is the
+  person's active aweb team.
+
+## Upgrading from 0.27.0
+
+- To join teams: upgrade aw to 1.36.12 or later (and restart the host's wake daemon), then `oats sync` so the deployment's lock takes oats.aweb 1.14.2. Existing instances keep their primary identity; they join teams with `oats aweb join <labels>`.

package/package-catalog.json

@@ -8,7 +8,7 @@
     },
     "oats.aweb": {
       "url": "https://github.com/awebai/oats-aweb.git",
-      "ref": "v1.13.1",
+      "ref": "v1.14.2",
       "path": "oats-package"
     },
     "oats.jira": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@awebai/oats",
-  "version": "0.27.0",
+  "version": "0.27.1",
   "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
   "keywords": [
     "agents",