@awebai/oats 0.24.0 → 0.24.2

package/bin/oats.mjs

@@ -13,7 +13,7 @@
  * The kernel resolves per-key closest-wins from wherever agents actually run,
  * so binding at a level scopes the capability to everything under it.
  */
-import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, readSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
 import { homedir, tmpdir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
@@ -23,13 +23,13 @@ import { enableTmuxMouse, tmuxConfigPath, tmuxMouseEnabled } from "../lib/tmux-c
 import {
   LAYERS, WORK_MODES, LEGACY_HOME_CAPABILITIES_DIR, OATS_LOCK_FILE, OATS_VERSION, OAS_SCOPE_REMEDY, RETIRED_CAPABILITIES, detectOasScopes, retiredCapabilityReason, configChain, configCapabilityEntries, manifestOperations,
   acquireCapability, restoreCapabilities, marketplaceCapabilities,
-  capabilityManifests, capabilityManifest, capabilityMissingRequires, capabilityIntegrity, capabilityTrust, capabilityExecutablePath, activateCapturedScaffold, loadCapturedDispatch, prepareCapturedComposition, resolveCapturedHelper, capturedNativeSessionAvailability, scaffoldCapturedInstance, startCapturedInstanceSession, withCapturedBindingFile, withCapturedInvocationContextFile,
+  capabilityManifests, capabilityManifest, capabilityMissingRequires, capabilityIntegrity, capabilityTrust, capabilityExecutablePath, activateCapturedScaffold, loadCapturedDispatch, inspectPortableOnboarding, prepareCapturedComposition, resolveCapturedHelper, capturedNativeSessionAvailability, scaffoldCapturedInstance, startCapturedInstanceSession, withCapturedBindingFile, withCapturedInvocationContextFile,
   readCapabilityLocks, writeCapabilityLock, admitCapturedAction, beginCapturedIntent, settleCapturedIntent,
   parsePackageSource, inspectGitSourceRoot, acquirePackage, restorePackages, listInstalledPackages, readPackageLocks, readLockedConfigTemplates,
-  officialCapabilityPackage, officialPackageCatalog,
+  officialCapabilityPackage, officialPackageCatalog, DEFAULT_PACKAGE_PATH,
   approveCapability, approveAvailableCapability, updatePackage, removePackage, migrateLegacyLock, applyLegacyLockMigration,
   packageIntegrity, capabilityArtifactIntegrity, verifyCapabilityInstallation, installedCapabilityDir, installedCapabilitiesDir, ownedCapabilitiesDir, loadPackageManifestAt,
-  resolveOatsConfig, resolveWorkMode, composeInstanceAgentsMd, parseYamlNested, assertSafeConfigValue, assertSafeConfigWriteKey, stripInternalAnnotations, withConfigFile, packagedInject, teamAgentRoots,
+  resolveOatsConfig, resolveWorkMode, composeInstanceAgentsMd, planInstanceResources, parseYamlNested, assertSafeConfigValue, assertSafeConfigWriteKey, stripInternalAnnotations, withConfigFile, packagedInject, teamAgentRoots,
   findTeamAgent, findTeamInstance, findCapabilityAgent, findInstanceHome, listCapabilityAgents, workspaceOf,
   ensureRoot, findRoot, findAgent, listAgents, listInstances, listAgentDefs, createAgent as coreCreateAgent,
   spawnInstance, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upsertLocalAgent, defaultRepo, RELATIONS, validateLaunchConfig, resolveLaunchSelection, resolveLaunchExecutable, checkLaunchExecutable, missingLaunchEnvRefs, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_RUNTIMES, LAUNCH_RECIPE_VERSION, parseLaunchCommand, resolveYolo, planLaunch, redactLaunchCommand, restartInstanceSession,
@@ -53,11 +53,13 @@ import { readPortablePreparationRequest } from "../lib/portable-onboarding-reque
 import { portableScope } from "../lib/portable-state.mjs";
 import { CAPTURED_OPERATION_TIMEOUT_MS, runCapturedOperationProcess } from "../lib/captured-operation-process.mjs";
 import { approveCapturedCapability } from "../lib/artifact-approvals.mjs";
+import { loadSetupExpertEdition, SETUP_EXPERT, SETUP_CAPABILITIES } from "../lib/setup-expert-source.mjs";
+import { parsePortableSource } from "../lib/source-spec.mjs";
 
 const args = process.argv.slice(2);
 let cmd = args[0];
 const HELP_WORDS = new Set(["help", "--help", "-h"]);
-const KERNEL_COMMANDS = new Set(["prepare", "capture", "config", "create", "doctor", "inspect", "operation", "soul", "launch-config", "experimental", "init", "inject", "install", "list", "migrate", "pane", "recall", "remove", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "trust", "type", "update", "use", "version"]);
+const KERNEL_COMMANDS = new Set(["prepare", "capture", "config", "create", "doctor", "inspect", "operation", "soul", "launch-config", "experimental", "onboard", "init", "inject", "install", "list", "migrate", "pane", "recall", "remove", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "trust", "type", "update", "use", "version"]);
 const flag = (name) => {
   const i = args.indexOf(`--${name}`);
   return i >= 0 ? (args[i + 1] && !args[i + 1].startsWith("--") ? args[i + 1] : true) : undefined;
@@ -95,6 +97,21 @@ const CLI_BIN = realpathSync(fileURLToPath(import.meta.url));
 const jsonFail = (code, message, details) => { console.log(JSON.stringify({ schemaVersion: 1, ok: false, error: { code, message: String(message), ...(details !== undefined ? { details } : {}) } })); process.exit(1); };
 const jsonOk = (result) => { console.log(JSON.stringify({ schemaVersion: 1, ok: true, result })); };
 
+function inspectOnboardingCmd() {
+  const fail = (code, message) => JSON_MODE ? jsonFail(code, message) : die(message);
+  let file;
+  for (let index = 1; index < args.length; index++) {
+    if (args[index] === "--json") continue;
+    if (args[index] !== "--request" || file !== undefined || !args[index + 1] || args[index + 1].startsWith("--")) fail("E_BAD_ARGS", "source inspection accepts one --request <absolute-json> and --json only");
+    file = args[++index];
+  }
+  try {
+    const input = readPortablePreparationRequest({ file });
+    const result = inspectPortableOnboarding(input);
+    if (JSON_MODE) jsonOk(result); else console.log(JSON.stringify(result, null, 2));
+  } catch (error) { fail(error.code || "E_INSPECT_FAILED", error.message); }
+}
+
 function prepareCmd() {
   const fail = (code, message, details) => JSON_MODE ? jsonFail(code, message, details) : die(message);
   const values = new Map(), allowed = new Set(["request", "dir", "source", "revision", "export", "alias", "workspace", "workspace-revision", "work"]);
@@ -370,6 +387,9 @@ function capturedCommand(selector) {
       const selected = helperSelection?.executionBinding ?? target;
       const loaded = loadCapturedDispatch({ deployment: selected.deployment, resolution: selected.resolution, action: { kind: args.includes("--composition") ? "compose" : "inspect" } });
       const result = { resolution: loaded.resolution, capture: loaded.record.capture, nativeSession: capturedNativeSessionAvailability(),
+        launchSelection: loaded.record.dispatch.launch === null ? null : {
+          runtime: loaded.record.dispatch.launch.runtime, model: loaded.record.dispatch.launch.model,
+        },
         ...(helperSelection ? { helperSelection } : {}),
         capabilities: [...loaded.capabilities.values()].map(({ id, manifest }) => ({ id, version: manifest.version,
           approval: loaded.approvals.find((entry) => entry.artifact.capability === id).status })),
@@ -490,6 +510,10 @@ function resolveForDoctor(ctx, soulName, { json } = {}) {
     die(`${e.message}`);
   }
 }
+function operationalKnowledgeNote(composition, soulName) {
+  return composition && !composition.oatsCoreDeclared
+    ? `soul ${soulName} has no oats.core capability; kernel-shipped operational skills are deprecated` : null;
+}
 function doctorComposition(ctx, soulName) {
   if (!soulName) return undefined;
   const root = findRoot(ctx);
@@ -1244,7 +1268,8 @@ function doctorJson(dir) {
       hooks: Object.keys(r.layers[l].hooks || {}), missingRequires: r.layers[l].missingRequires,
       provenance: r.provenance[l],
     } : { provenance: r.provenance[l] || null }])),
-    kernelInjection: r.kernelInjection,
+    kernelInjection: composition?.resolved.kernelInjection ?? r.kernelInjection,
+    information: operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : [],
     injects: r.injects,
     capabilities: r.capabilities.map((c) => ({ id: c.id, layer: c.layer, command: c.command, origin: c.origin, provenance: c.provenance, settings: c.settings, skills: c.skills, inject: c.inject, hooks: Object.keys(c.hooks || {}), trust: c.trust })),
     acquired: Object.fromEntries(Object.entries(mans).map(([n, m]) => [n, { layer: m.layer, command: m.command, version: m.version, dir: m._dir, origin: m._origin, description: m.description }])),
@@ -1273,6 +1298,7 @@ function doctor(dir) {
   const soulName = flag("soul");
   const chain = configChain(ctx);
   const r = resolveForDoctor(ctx, soulName);
+  const composition = doctorComposition(ctx, soulName);
   console.log(`oats doctor — resolved from ${shortPath(ctx)}\n`);
 
   // Kernel/bridge version skew (published in lockstep from one tag).
@@ -1317,7 +1343,8 @@ function doctor(dir) {
   }
 
   console.log("\nKernel injection:");
-  console.log(`  oats: ${r.kernelInjection?.inject ? shortPath(r.kernelInjection.inject) : "none"}  [${r.kernelInjection?.provenance || "default"}]`);
+  const kernelInjection = composition?.resolved.kernelInjection ?? r.kernelInjection;
+  console.log(`  oats: ${kernelInjection?.inject ? shortPath(kernelInjection.inject) : "none"}  [${kernelInjection?.provenance || "default"}]`);
 
   console.log("\nUnconditional injections (outermost→innermost):");
   if (r.injects.length === 0) console.log("  (none)");
@@ -1425,7 +1452,8 @@ function doctor(dir) {
   }
 
   if (soulName) {
-    const composition = doctorComposition(ctx, soulName);
+    const information = operationalKnowledgeNote(composition, soulName);
+    if (information) console.log(`\nINFO: ${information}`);
     console.log(`\nFinal composed AGENTS.md for ${soulName}:\n\n${composition.text}`);
   } else console.log("\nPass --soul <name> to inspect final composed AGENTS.md.");
 }
@@ -3913,16 +3941,17 @@ function spawnCmd() {
     if (!agent && !instrFile && !defFile) {
       const def = listAgentDefs(process.cwd()).find((d) => d.name === name);
       if (!def) bail("E_UNKNOWN_AGENT", `unknown agent "${name}" (known: ${listAgents(root).map((a) => a.name).join(", ") || "none"}; importable defs: ${listAgentDefs(process.cwd()).map((d) => d.name).join(", ") || "none"}) — pass --instructions-file or --def-file to create a local agent`);
-      agent = upsertLocalAgent(root, { name: def.name, file: def.path, repo: flag("repo"), work: flag("work"), runtime: flag("runtime"), model: flag("model") });
+      agent = upsertLocalAgent(root, { name: def.name, file: def.path, repo: flag("repo"), work: flag("work"), runtime: flag("runtime"), model: flag("model"), oatsCore: !args.includes("--no-oats-core") });
     } else if (!agent || agent.kind === "local") {
       agent = upsertLocalAgent(root, {
-        name, file: defFile, instructions: instrFile ? readFileSync(instrFile, "utf8") : undefined,
+        name, file: defFile, instructions: instrFile ? readFileSync(instrFile, "utf8") : undefined, oatsCore: !args.includes("--no-oats-core"),
         repo: flag("repo"), work: flag("work"), runtime: flag("runtime"), model: flag("model"), yolo: yoloFlag(),
       });
     } else {
       bail("E_BAD_ARGS", `"${name}" is a persistent agent — spawn it without --instructions-file/--def-file`);
     }
   }
+  for (const information of agent.notes || []) note(`[${information.code}] ${information.message}`);
   // Lineage is explicit: --relation child|sibling|parent|unrelated anchors the new
   // instance to --relative-to <instance>. --parent X is sugar for
   // --relative-to X --relation child (agents spawning sub-agents pass their own
@@ -4206,10 +4235,134 @@ async function paneCmd() {
   die("`oats pane` has been retired — the OATS Desktop app (packages/desktop) is the control panel now.");
 }
 
+function onboardCmd() {
+  const fail = (code, message, details) => JSON_MODE ? jsonFail(code, message, details) : die(message);
+  const values = new Map();
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (["--json", "--force-existing"].includes(arg)) { values.set(arg.slice(2), true); continue; }
+    if (!["--dir", "--workspace"].includes(arg) || values.has(arg.slice(2)) || !args[i + 1] || args[i + 1].startsWith("--")) {
+      fail("E_BAD_ARGS", "usage: oats onboard [--dir <deployment>] [--workspace <git:source[@revision]>] [--force-existing] [--json]");
+    }
+    values.set(arg.slice(2), args[++i]);
+  }
+  dropAmbientRoot();
+  let deployment, root, acquired, created, configFile, configBefore, configWritten;
+  try {
+    // Like create: an existing enclosing roster wins, otherwise bootstrap at
+    // the enclosing Git root or explicit directory. Canonicalize existing parents.
+    const requested = resolve(values.get("dir") || process.cwd()), missing = [];
+    let parent = requested;
+    while (!existsSync(parent)) { missing.unshift(basename(parent)); parent = dirname(parent); }
+    const start = join(realpathSync(parent), ...missing);
+    root = findRoot(start) || join(defaultRepo(start) || start, "agents");
+    deployment = dirname(root);
+    assertNoSymlinkedParents(deployment, root, "onboard agents root");
+    assertNoSymlinkedParents(deployment, join(deployment, "local-agents", SETUP_EXPERT), "local setup soul");
+    const assertSetupAbsent = () => {
+      for (const candidate of [join(deployment, "local-agents", SETUP_EXPERT), join(root, SETUP_EXPERT), join(root, "local-agents", SETUP_EXPERT), join(root, "tmp-agents", SETUP_EXPERT)]) {
+        let present = false;
+        try { lstatSync(candidate); present = true; } catch (error) { if (error.code !== "ENOENT") throw error; }
+        if (present) throw Object.assign(new Error(`existing or incomplete setup expert is preserved at ${candidate}; it will not be overwritten`), { code: "E_AGENT_EXISTS" });
+      }
+    };
+    assertSetupAbsent();
+    const agents = listAgents(root);
+    if (agents.length && !values.get("force-existing")) throw Object.assign(new Error("deployment already has agents; use --force-existing to add the setup expert without replacing them"), { code: "E_DEPLOYMENT_NOT_EMPTY" });
+    if (findAgent(root, SETUP_EXPERT)) throw Object.assign(new Error("oats-setup-expert already exists; it will not be overwritten"), { code: "E_AGENT_EXISTS" });
+    const edition = loadSetupExpertEdition(values.get("workspace"));
+    for (const key of ["description", "runtime", "model"]) if (edition.declaration[key] !== undefined) assertSafeConfigValue(edition.declaration[key], `setup edition ${key}`);
+    const catalog = officialPackageCatalog(), entry = catalog["oats.framework"];
+    if (!Object.hasOwn(catalog, "oats.framework") || !entry?.url || !entry.ref
+        || SETUP_CAPABILITIES.some(id => { const m = officialCapabilityPackage(id); return !m.available || m.package !== "oats.framework" || m.migratedCapability !== id; })) {
+      throw Object.assign(new Error("official oats.framework with core/setup aliases and a published revision is required"), { code: "needs-configuration" });
+    }
+    const catalogSource = parsePortableSource(`git:${entry.url}@${entry.ref}#${entry.path ?? DEFAULT_PACKAGE_PATH}`);
+    const file = join(deployment, "oats-config.yaml");
+    if (existsSync(file) && !lstatSync(file).isFile()) throw Object.assign(new Error("onboard will not replace a non-regular deployment configuration"), { code: "E_CONFIG_BROKEN" });
+    const before = existsSync(file) ? readFileSync(file, "utf8") : null;
+    configFile = file; configBefore = before;
+    const caps = readCapabilitiesModel(file), previous = resolveOatsConfig(deployment, SETUP_EXPERT);
+    // Exclusions are for the NEW soul only. Never turn off an existing root's
+    // global provider/layer just to make bootstrap work under --force-existing.
+    for (const cap of previous.capabilities) {
+      if (SETUP_CAPABILITIES.includes(cap.id)) continue;
+      let target;
+      if (cap.layer) {
+        const existing = caps.layers[cap.layer];
+        if (existing && (existing === "none" || existing.capability !== cap.id)) throw Object.assign(new Error(`cannot safely exclude ${cap.id} for the setup soul at this level; choose a fresh deployment`), { code: "needs-configuration" });
+        target = caps.layers[cap.layer] ||= { capability: cap.id };
+      } else target = caps.additive[cap.id] ||= {};
+      target.souls = { ...target.souls, [SETUP_EXPERT]: false };
+    }
+    if (before === null && !agents.length) for (const layer of LAYERS) caps.layers[layer] ??= "none";
+    for (const id of SETUP_CAPABILITIES) {
+      const target = caps.additive[id] ||= {};
+      if (target.from && target.from !== "installed") throw Object.assign(new Error(`${id} already selects another provenance; choose a fresh deployment`), { code: "needs-configuration" });
+      target.from = "installed"; target.souls = { ...target.souls, [SETUP_EXPERT]: true };
+    }
+    const text = replaceCapabilitiesBlock(before ?? `name: ${scaffoldConfigName(deployment)}\n`, caps);
+    mkdirSync(deployment, { recursive: true });
+    acquired = acquirePackage(deployment, "oats.framework", { expectPackage: "oats.framework",
+      catalog(id, selector) { const selected = Object.hasOwn(catalog, id) ? catalog[id] : null; return selected?.url ? { url: selected.url, ref: selector || selected.ref, path: selected.path } : undefined; },
+      assertCommittable(plan) {
+      const pkg = plan.packages.find(p => p.package === "oats.framework");
+      if (edition.packageIntegrity && pkg?.integrity !== edition.packageIntegrity) throw Object.assign(new Error("selected edition's same-repository package differs from the official acquisition; align the reviewed source and catalog explicitly"), { code: "integrity-drift" });
+      for (const id of SETUP_CAPABILITIES) {
+        const cap = plan.capabilities.find(c => c.capability === id);
+        if (!cap || cap.package !== "oats.framework" || cap.layer || Object.values(cap.executableSurface || {}).some(value => Array.isArray(value) && value.length)) {
+          throw Object.assign(new Error(`setup bootstrap needs resources-only ${id}; executable surfaces require a separate explicit approval path`), { code: "approval-required" });
+        }
+      }
+    } });
+    if ((existsSync(file) ? readFileSync(file, "utf8") : null) !== before) throw Object.assign(new Error("deployment configuration changed during acquisition; nothing was activated"), { code: "E_CONFIG_CHANGED" });
+    writeFileAtomic(file, text); configWritten = text;
+    const selected = resolveOatsConfig(deployment, SETUP_EXPERT);
+    if (selected.capabilities.length !== 2 || SETUP_CAPABILITIES.some(id => !selected.capabilities.some(c => c.id === id))) {
+      throw Object.assign(new Error("setup expert's effective configuration contains other capabilities; no soul or hook was created"), { code: "needs-configuration" });
+    }
+    // Required capabilities were checked resources-only before acquisition: no
+    // unrelated or executable soul-scaffold hooks can run during local creation.
+    assertNoSymlinkedParents(deployment, root, "onboard agents root");
+    assertNoSymlinkedParents(deployment, join(deployment, "local-agents", SETUP_EXPERT), "local setup soul");
+    assertSetupAbsent();
+    mkdirSync(root, { recursive: true });
+    created = coreCreateAgent(root, { name: SETUP_EXPERT, local: true, oatsCore: false, repo: deployment, work: "directory",
+      runtime: edition.declaration.runtime, model: edition.declaration.model, yolo: false,
+      description: edition.declaration.description, instructions: edition.instructions });
+    const pkg = acquired.installed.find(p => p.package === "oats.framework");
+    const source = parsePortableSource(`git:${catalogSource.url}@${pkg.commit}#${pkg.path}`);
+    const requires = { capabilities: Object.fromEntries(SETUP_CAPABILITIES.map(id => [id, { source: `${source.source}#${source.path}` }])) };
+    const soulFile = join(created.soul, "soul.yaml");
+    writeFileAtomic(soulFile, readFileSync(soulFile, "utf8") + `requires: ${JSON.stringify(requires)}\ndefaults: ${JSON.stringify(edition.declaration.defaults)}\n`);
+    const agent = findAgent(root, SETUP_EXPERT), composition = composeInstanceAgentsMd(created.soul, deployment, SETUP_EXPERT, "directory", "local");
+    planInstanceResources({ resolved: composition.resolved, soulDir: created.soul, agent, contextDir: deployment, composition });
+    const argv = [process.execPath, CLI_BIN, "spawn", SETUP_EXPERT, "--dir", deployment, "--no-yolo", "--task", "Help me configure this deployment and adopt my workspace with explicit approvals."];
+    const result = { mode: "classic", captured: false, deployment, agentsRoot: root, ...created, source: edition.source,
+      package: { id: pkg.package, version: pkg.version, commit: pkg.commit, path: pkg.path }, lockFile: acquired.lockFile,
+      capabilities: [...SETUP_CAPABILITIES], launched: false, next: { argv, command: argv.map(shellQuote).join(" ") } };
+    if (JSON_MODE) jsonOk(result);
+    else { console.log(`Created local ${SETUP_EXPERT} in ${deployment} (classic bootstrap, not captured preparation).`); console.log(`No model was launched. Next:\n${result.next.command}`); }
+  } catch (error) {
+    // Roll back only configuration bytes still exactly owned by this attempt.
+    // Acquired artifacts/locks and any incomplete new soul remain visible evidence.
+    let configRestored = false;
+    if (configWritten !== undefined) {
+      try {
+        if (lstatSync(configFile).isFile() && readFileSync(configFile, "utf8") === configWritten) {
+          if (configBefore === null) rmSync(configFile); else writeFileAtomic(configFile, configBefore);
+          configRestored = true;
+        }
+      } catch { /* never erase another writer's change or hide a failed rollback */ }
+    }
+    fail(error.code || "E_ONBOARD_FAILED", error.message, { deployment, agentsRoot: root, packageAcquired: !!acquired, soul: created?.soul, configRestored, launched: false });
+  }
+}
+
 function createCmd() {
   const yolo = yoloFlag();
   const name = args[1];
-  if (!name || name.startsWith("--")) die("usage: oats create <name> [--local] [--description <d>] [--type <agent-type>] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--runtime pi|claude|codex] [--model <m>] [--yolo|--no-yolo] [--instructions-file <f>]");
+  if (!name || name.startsWith("--")) die("usage: oats create <name> [--local] [--no-oats-core] [--description <d>] [--type <agent-type>] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--runtime pi|claude|codex] [--model <m>] [--yolo|--no-yolo] [--instructions-file <f>]");
   const local = args.includes("--local");
   const startDir = dirFlag();
   // `create` BOOTSTRAPS a deployment: with no agents/ or local-agents/ yet,
@@ -4228,11 +4381,12 @@ function createCmd() {
   }
   const instrFile = flag("instructions-file");
   const r = coreCreateAgent(root, {
-    name, local, description: flag("description"), type: flag("type"), repo: flag("repo") || (flag("work") === "directory" ? undefined : defaultRepo(process.cwd())),
+    name, local, oatsCore: !args.includes("--no-oats-core"), description: flag("description"), type: flag("type"), repo: flag("repo") || (flag("work") === "directory" ? undefined : defaultRepo(process.cwd())),
     work: flag("work"), runtime: flag("runtime"), model: flag("model"), yolo,
     instructions: instrFile ? readFileSync(instrFile, "utf8") : undefined,
   });
   if (args.includes("--json")) { console.log(JSON.stringify({ ...r, ...(bootstrapped ? { agentsRoot: root } : {}) }, null, 2)); return; }
+  for (const information of r.notes || []) console.error(`[${information.code}] ${information.message}`);
   if (bootstrapped) console.log(`Created deployment root ${shortPath(root)} (this scope had no agents/ yet)`);
   console.log(`Created ${r.kind === "local" ? "LOCAL agent (uncommitted — soul lives in local-agents/, gitignored)" : "agent"} "${r.agent}" — soul at ${shortPath(r.soul)}`);
   console.log(`Edit ${shortPath(join(r.soul, "AGENTS.md"))} to define its role, then: oats spawn ${r.agent} --task "..."`);
@@ -4867,6 +5021,16 @@ catch (error) {
   if (JSON_MODE) jsonFail(error.code || "E_BAD_ARGS", error.message);
   die(error.message);
 }
+const sourceInspection = (cmd === "inspect" || captured?.args[0] === "inspect")
+  && args.some(arg => arg === "--request" || arg.startsWith("--request="));
+if (sourceInspection) {
+  if (captured) {
+    if (JSON_MODE) jsonFail("E_BAD_ARGS", "source inspection is explicit new work and cannot use captured selectors");
+    die("source inspection is explicit new work and cannot use captured selectors");
+  }
+  if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
+  inspectOnboardingCmd(); process.exit(0);
+}
 if (cmd === "prepare" || captured?.args[0] === "prepare") {
   if (captured) {
     if (JSON_MODE) jsonFail("E_BAD_ARGS", "prepare is explicit new work and cannot use captured selectors");
@@ -4875,6 +5039,14 @@ if (cmd === "prepare" || captured?.args[0] === "prepare") {
   if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
   prepareCmd(); process.exit(0);
 }
+if (cmd === "onboard" || captured?.args[0] === "onboard") {
+  if (captured) {
+    if (JSON_MODE) jsonFail("E_BAD_ARGS", "onboard is explicit classic bootstrap and cannot use captured selectors");
+    die("onboard is explicit classic bootstrap and cannot use captured selectors");
+  }
+  if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
+  onboardCmd(); process.exit(0);
+}
 // Other commands retain their existing explicit/inherited selection rules.
 try { captured ??= capturedSelector(args); }
 catch (error) {
@@ -5003,7 +5175,10 @@ Usage:
       --instance <name> | --home <abs>       attachments over its saved route (bytes stream on
       --file <path> [--json]                 ssh stdin; sha256 verified); the server must
                                             advertise session-upload (oats 0.22.13 or later)
-  oats create <name> [--local]               create an agent soul; --local = full
+  oats onboard [--dir <deployment>]          bootstrap a LOCAL setup expert from official
+      [--workspace <git:source[@revision]>]   capabilities; classic path, not captured prepare;
+      [--force-existing] [--json]            prints the next spawn command, never launches
+  oats create <name> [--local] [--no-oats-core] create an agent soul; --local = full
       [--description <d>] [--repo <r>]      soul under local-agents/ (uncommitted,
       [--work <mode>] [--runtime pi|claude|codex] gitignored; same memory + lifecycle)
       [--model <m>] [--yolo|--no-yolo] [--instructions-file <f>]
@@ -5033,6 +5208,7 @@ Usage:
   oats spawn <agent> [--task <text>]         spawn an instance (tmux/Herdr; --no-launch
       [--purpose <slug>] [--repo <r>]       = scaffold only); --instructions-file/
       [--parent <instance>]                 --def-file creates a local agent;
+      [--no-oats-core]                      omit the default only on NEW local souls;
       [--relation child|sibling|parent|unrelated]    --relation + --relative-to anchor the
       [--relative-to <instance>]            new instance to an existing one; --parent X
       [--relative-root <agents-root>]       disambiguates same-named team anchors
@@ -5184,6 +5360,9 @@ The turn record (core — every conversation captured, searchable, replicated):
                                             design, repo checkout only; see
                                             packages/experimental/README.md
 
+  oats inspect --request <absolute-json-file> [--json]
+                                            read-only fresh source/workspace/member metadata;
+                                            no current config, provider execution or preparation authority
   oats prepare --request <absolute-json-file> [--json]
                                             complete public preparation input; no mixed flags,
                                             inherited binding, implicit setup or launch authority

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

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { runBindingWire } from '../lib/binding-wire.mjs';
+
+const args=process.argv.slice(2);
+if(args.includes('--help') || args.includes('-h')) {
+  process.stdout.write('oats aweb provider binding phase (manifest-owned JSON stdin/stdout)\n');
+} else {
+  const phase=args[0];
+  if(args.length!==1) await runBindingWire(phase,[],process.stdout);
+  else await runBindingWire(phase);
+}

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

@@ -40,6 +40,10 @@ import { execFileSync } from "node:child_process";
 import { chmodSync, cpSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { hostname } from "node:os";
 import { join, dirname, resolve, delimiter } from "node:path";
+import { loadCapturedAwebExecution, requireCapturedAwebAction } from "../lib/captured-execution.mjs";
+import { assessCapturedSessionReadiness, querySelectedKernel } from "../lib/session-readiness.mjs";
+import { runCapturedNative } from "../lib/captured-native.mjs";
+import { parseBindingJson } from "../lib/binding-wire.mjs";
 
 /** 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
@@ -110,6 +114,28 @@ const warn = (m) => out({ warning: `oats-aweb: ${String(m).slice(0, 300)}` });
  * state already exists (e.g. a joined identity) so retire can undo it. */
 const fatal = (m, meta) => out({ ...(meta ? { meta } : {}), warning: `oats-aweb: ${String(m).slice(0, 300)}` }, 1);
 
+// Any selected snapshot enters the captured consumer BEFORE legacy settings,
+// root discovery or identity handling. Invalid-present never falls back.
+try {
+  const loaded = loadCapturedAwebExecution();
+  if (loaded.kind === "captured") {
+    const event = process.argv[2] || process.env.OATS_EVENT;
+    if ((process.env.OATS_EVENT && process.env.OATS_EVENT !== event) || process.argv.slice(3).some(arg => arg !== "--json")) throw new Error("captured entrypoint arguments differ from the selected action");
+    const manifest = JSON.parse(readFileSync(new URL("../oats.json", import.meta.url), "utf8"));
+    const selected = requireCapturedAwebAction(loaded, event, manifest);
+    const settings = parseBindingJson(Buffer.from(process.env.OATS_SETTINGS || "{}"));
+    if (!settings || typeof settings !== "object" || Array.isArray(settings) || Object.keys(settings).some(k => k !== "delivery")) throw new Error("captured settings support delivery only; no identity copying or ambient fallback");
+    const checked = assessCapturedSessionReadiness({ binding: selected.binding, invocation: selected.context, settings }, {
+      query(args, options) { selected.assertCurrent(); const result = querySelectedKernel(args, options); selected.assertCurrent(); return result; },
+    });
+    if (checked.status !== "ready") out({ ...checked, warning: `oats-aweb: ${checked.problems[0].message}` }, 1);
+    const result = runCapturedNative({ selected, event, settings, run });
+    out(result.output, result.exitCode);
+  }
+} catch (error) {
+  out({ status: "needs-configuration", problems: [{ code: "invalid-binding", message: "invalid or changed captured aweb execution input" }], warning: "oats-aweb: invalid or changed captured aweb execution input; no legacy fallback was used" }, 1);
+}
+
 const event = process.env.OATS_EVENT || process.argv[2];
 const instance = process.env.OATS_INSTANCE;
 const home = process.env.OATS_HOME || process.cwd();

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

@@ -0,0 +1,214 @@
+import { TextDecoder } from 'node:util';
+import { assessCapturedSessionReadiness } from './session-readiness.mjs';
+import {
+  MESSAGING_CONTRACT,
+  MESSAGING_CONTRACT_VERSION,
+  bindMessagingDomain,
+  normalizeMessagingDeclarations,
+  validateAwebBinding,
+  validateAwebInvocationContext,
+} from './portable-binding.mjs';
+
+export const BINDING_WIRE_LIMITS=Object.freeze({bytes:1024*1024,depth:32,entries:16384});
+const CAPABILITY='oats.aweb',SLOT='messaging';
+const phases=new Set(['normalize','bind','check']);
+const declarationKinds=new Set(['soul','workspace','adoption','operator']);
+const errorCodes=new Set(['needs-configuration','requirement-conflict','invalid-binding','authorization-required','host-requirement-missing','provider-unavailable','provider-not-qualified']);
+const obj=value=>value!==null && typeof value==='object' && !Array.isArray(value);
+const wireError=code=>{throw Object.assign(new Error(code),{wireCode:code});};
+const canonical=value=>value===null || typeof value!=='object'?JSON.stringify(value):Array.isArray(value)?`[${value.map(canonical).join(',')}]`:`{${Object.keys(value).sort().map(key=>`${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+const same=(a,b)=>canonical(a)===canonical(b);
+function keys(value,allowed,required) {
+  if(!obj(value)) wireError('invalid-binding');
+  for(const key of Object.keys(value)) if(!allowed.includes(key)) wireError('invalid-binding');
+  for(const key of required) if(!Object.hasOwn(value,key)) wireError('invalid-binding');
+  return value;
+}
+function pointer(value) {return typeof value==='string' && /^(?:\/(?:[^~]|~[01])*)+$/.test(value);}
+function bindingKey(value) {return pointer(value) && value.startsWith('/bindings/messaging/') && value.length>'/bindings/messaging/'.length;}
+
+class StrictJsonParser {
+  constructor(text,{depth,entries}) {this.text=text;this.maxDepth=depth;this.maxEntries=entries;this.at=0;this.entries=0;}
+  whitespace() {while(/[\u0009\u000a\u000d\u0020]/.test(this.text[this.at] || '')) this.at++;}
+  count() {if(++this.entries>this.maxEntries) wireError('invalid-binding');}
+  string() {
+    if(this.text[this.at]!=='"') wireError('invalid-binding');
+    const start=this.at++;
+    while(this.at<this.text.length) {
+      const code=this.text.charCodeAt(this.at++);
+      if(code===0x22) {try{return JSON.parse(this.text.slice(start,this.at));}catch{wireError('invalid-binding');}}
+      if(code<0x20) wireError('invalid-binding');
+      if(code===0x5c) {
+        const escaped=this.text[this.at++];
+        if(escaped==='u') {if(!/^[0-9a-fA-F]{4}$/.test(this.text.slice(this.at,this.at+4))) wireError('invalid-binding');this.at+=4;}
+        else if(!'"\\/bfnrt'.includes(escaped || '')) wireError('invalid-binding');
+      }
+    }
+    wireError('invalid-binding');
+  }
+  value(depth=1) {
+    this.whitespace();const char=this.text[this.at];
+    if(char==='"') return this.string();
+    if(char==='{') {
+      if(depth>this.maxDepth) wireError('invalid-binding');this.at++;this.whitespace();
+      const result=Object.create(null),seen=new Set();if(this.text[this.at]==='}') {this.at++;return result;}
+      while(true) {
+        this.whitespace();const key=this.string();if(seen.has(key)) wireError('invalid-binding');seen.add(key);this.count();
+        this.whitespace();if(this.text[this.at++]!==':') wireError('invalid-binding');result[key]=this.value(depth+1);this.whitespace();
+        const next=this.text[this.at++];if(next==='}') return result;if(next!==',') wireError('invalid-binding');
+      }
+    }
+    if(char==='[') {
+      if(depth>this.maxDepth) wireError('invalid-binding');this.at++;this.whitespace();
+      const result=[];if(this.text[this.at]===']') {this.at++;return result;}
+      while(true) {this.count();result.push(this.value(depth+1));this.whitespace();const next=this.text[this.at++];if(next===']') return result;if(next!==',') wireError('invalid-binding');}
+    }
+    for(const [token,value] of [['true',true],['false',false],['null',null]]) if(this.text.startsWith(token,this.at)) {this.at+=token.length;return value;}
+    const match=/^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(this.text.slice(this.at));
+    if(!match) wireError('invalid-binding');this.at+=match[0].length;const number=Number(match[0]);if(!Number.isFinite(number)) wireError('invalid-binding');return number;
+  }
+  parse() {this.whitespace();const value=this.value();this.whitespace();if(this.at!==this.text.length) wireError('invalid-binding');return value;}
+}
+
+export function parseBindingJson(bytes,limits=BINDING_WIRE_LIMITS) {
+  if(!Buffer.isBuffer(bytes)) bytes=Buffer.from(bytes);
+  if(bytes.length>limits.bytes) wireError('invalid-binding');
+  let text;try{text=new TextDecoder('utf-8',{fatal:true}).decode(bytes);}catch{wireError('invalid-binding');}
+  return new StrictJsonParser(text,limits).parse();
+}
+function settings(value) {
+  if(!obj(value)) wireError('invalid-binding');
+  if(Object.hasOwn(value,'identity')) wireError('provider-not-qualified');
+  keys(value,['delivery'],[]);
+  if(value.delivery!==undefined && !['channel','session'].includes(value.delivery)) wireError('needs-configuration');
+  return value;
+}
+function request(value,phase) {
+  keys(value,['schemaVersion','phase','slot','capability','settings','input'],['schemaVersion','phase','slot','capability','settings','input']);
+  if(value.schemaVersion!==1 || value.phase!==phase || value.slot!==SLOT || value.capability!==CAPABILITY) wireError('invalid-binding');
+  settings(value.settings);return value;
+}
+function declaration(value) {
+  keys(value,['kind','value','origin','origins'],['kind','value','origin','origins']);
+  if(!declarationKinds.has(value.kind) || !obj(value.value) || !obj(value.origin) || !obj(value.origins)) wireError('invalid-binding');
+  return value;
+}
+function context(value,{request=false}={}) {
+  if(value?.kind==='workspace') {
+    keys(value,request?['kind','identity','observation']:['kind','identity'],request?['kind','identity','observation']:['kind','identity']);
+    if(!obj(value.identity) || (request && !obj(value.observation))) wireError('invalid-binding');
+    return {kind:'workspace',identity:value.identity};
+  }
+  if(value?.kind==='standalone') {
+    keys(value,['kind','key'],['kind','key']);
+    if(value.key!==null && (typeof value.key!=='string' || !value.key.trim())) wireError('invalid-binding');
+    return {kind:'standalone',key:value.key};
+  }
+  wireError('invalid-binding');
+}
+function normalizePhase(req) {
+  keys(req.input,['declarations','context'],['declarations','context']);
+  if(!Array.isArray(req.input.declarations)) wireError('invalid-binding');
+  const declarations=req.input.declarations.map(declaration);context(req.input.context,{request:true});
+  return normalizeMessagingDeclarations({declarations,context:req.input.context});
+}
+function choiceMap(value,model) {
+  if(!obj(value)) wireError('invalid-binding');
+  const allowed=new Set(['/bindings/messaging/responsibleHuman','/bindings/messaging/privateTeam','/bindings/messaging/wider',...Object.values(model.teams)]);
+  for(const [key,choice] of Object.entries(value)) {
+    if(!bindingKey(key) || !allowed.has(key)) wireError('invalid-binding');
+    keys(choice,['value','selectedBy','constraints','considered'],['value','selectedBy','constraints','considered']);
+    if(!Array.isArray(choice.constraints) || !Array.isArray(choice.considered) || (choice.selectedBy!==null && !obj(choice.selectedBy))) wireError('invalid-binding');
+  }
+  return value;
+}
+function model(value) {
+  keys(value,['contract','version','context','contextOrigin','requested','requestedOrigins','aliases','aliasOrigins','teams','privatePolicy','privatePolicyOrigin'],['contract','version','context','contextOrigin','requested','requestedOrigins','aliases','aliasOrigins','teams','privatePolicy','privatePolicyOrigin']);
+  if(value.contract!==MESSAGING_CONTRACT || value.version!==MESSAGING_CONTRACT_VERSION || !Array.isArray(value.requested) || !obj(value.requestedOrigins) || !obj(value.aliases) || !obj(value.aliasOrigins) || !obj(value.teams) || typeof value.privatePolicy!=='boolean') wireError('invalid-binding');
+  context(value.context);if(value.contextOrigin!==null && !obj(value.contextOrigin)) wireError('invalid-binding');if(value.privatePolicyOrigin!==null && !obj(value.privatePolicyOrigin)) wireError('invalid-binding');
+  for(const key of Object.values(value.teams)) if(!bindingKey(key)) wireError('invalid-binding');
+  return value;
+}
+function bindPhase(req) {
+  keys(req.input,['model','choices','context'],['model','choices','context']);
+  const normalized=model(req.input.model),selectedContext=context(req.input.context,{request:true});
+  if(!same(selectedContext,normalized.context) || (selectedContext.kind==='workspace' && !same(req.input.context.observation,normalized.contextOrigin))) wireError('invalid-binding');
+  return bindMessagingDomain({model:normalized,choices:choiceMap(req.input.choices,normalized)});
+}
+function binding(value) {
+  keys(value,['schemaVersion','capability','payloadContract','payloadVersion','payload','credentialRefs','provenance'],['schemaVersion','capability','payloadContract','payloadVersion','payload','credentialRefs','provenance']);
+  if(value.schemaVersion!==1 || value.capability!==CAPABILITY || value.payloadContract!==MESSAGING_CONTRACT || value.payloadVersion!==MESSAGING_CONTRACT_VERSION || !obj(value.payload) || !obj(value.credentialRefs) || Object.keys(value.credentialRefs).length || !Array.isArray(value.provenance)) wireError('invalid-binding');
+  for(const origin of value.provenance) if(!obj(origin)) wireError('invalid-binding');
+  return value;
+}
+function checkResult(message) {return {status:'needs-configuration',problems:[{code:'needs-configuration',message}]};}
+function checkPhase(req) {
+  keys(req.input,['binding','context','action','invocation'],['binding','context','action']);
+  if(!obj(req.input.action) || typeof req.input.action.kind!=='string') wireError('invalid-binding');
+  const current=validateAwebBinding(binding(req.input.binding)),selectedContext=context(req.input.context,{request:true});
+  if(!same(selectedContext,current.payload.context)) wireError('invalid-binding');
+  const invocation=Object.hasOwn(req.input,'invocation')?validateAwebInvocationContext(req.input.invocation,current,{context:req.input.context,action:req.input.action}):null;
+  if(['command','hook','operation'].includes(req.input.action.kind) && (!invocation || invocation.instance===null || invocation.intent===null)) return checkResult('an admitted captured instance intent is required for execution');
+  if(current.payload.privateTeam===null) return checkResult('an explicit private-team binding is required');
+  // Read-only public kernel observations, not an account/grant attestation.
+  // Native setup is performed only by the separately admitted execution path.
+  return assessCapturedSessionReadiness({binding:current,invocation,settings:req.settings});
+}
+
+export function handleBindingRequest(phase,value) {
+  if(!phases.has(phase)) wireError('invalid-binding');
+  const req=request(value,phase);
+  if(phase==='normalize') return normalizePhase(req);
+  if(phase==='bind') return bindPhase(req);
+  return checkPhase(req);
+}
+function response(phase,body) {return {schemaVersion:1,phase,slot:SLOT,capability:CAPABILITY,...body};}
+function errorCode(error) {if(errorCodes.has(error?.wireCode)) return error.wireCode;if(errorCodes.has(error?.code)) return error.code;return 'invalid-binding';}
+// Only these literal domain diagnostics may cross the wire. Never reflect a
+// caught exception's dynamic alias/key/path, native stderr or credential text.
+const safeReasons=new Map([
+  ['needs-configuration',[
+    'messaging-enabled standalone preparation needs an explicit context key',
+    'messaging binding needs one soul declaration',
+    'messaging workspace must declare private: per-human',
+    'an explicit responsible-human binding is required',
+    'an explicit wider-membership consent list is required',
+    'a selected wider-team binding is required',
+    'a selected wider alias needs an explicit workspace team mapping',
+  ]],
+  ['requirement-conflict',['multiple soul messaging declarations','adoption team aliases have conflicting mappings']],
+]);
+const fallbackReasons=Object.freeze({
+  'needs-configuration':'messaging settings and explicit binding selections are required',
+  'requirement-conflict':'messaging declarations contain incompatible requirements',
+  'invalid-binding':'messaging input must match the supported binding contract',
+  'authorization-required':'explicit native messaging authorization is required',
+  'host-requirement-missing':'a required native messaging host resource is unavailable',
+  'provider-unavailable':'the selected messaging provider is unavailable',
+  'provider-not-qualified':'the requested messaging configuration is not qualified',
+});
+function errorProblem(error) {
+  const code=errorCode(error),message=safeReasons.get(code)?.find(literal=>literal===error?.message)??fallbackReasons[code];
+  return {code,message};
+}
+function enforceOutputLimits(value,depth=1,state={entries:0}) {
+  if(depth>BINDING_WIRE_LIMITS.depth) wireError('provider-not-qualified');
+  if(value===null || typeof value!=='object') return;
+  for(const child of Array.isArray(value)?value:Object.values(value)) {
+    if(++state.entries>BINDING_WIRE_LIMITS.entries) wireError('provider-not-qualified');
+    enforceOutputLimits(child,depth+1,state);
+  }
+}
+export async function runBindingWire(phase,input=process.stdin,output=process.stdout) {
+  let answer;
+  try {
+    const chunks=[];let length=0;
+    for await(const chunk of input) {const bytes=Buffer.from(chunk);length+=bytes.length;if(length>BINDING_WIRE_LIMITS.bytes) wireError('invalid-binding');chunks.push(bytes);}
+    const result=handleBindingRequest(phase,parseBindingJson(Buffer.concat(chunks,length)));
+    answer=response(phase,{ok:true,result});
+  } catch(error) {answer=response(phases.has(phase)?phase:'check',{ok:false,error:errorProblem(error)});}
+  let bytes;
+  try {enforceOutputLimits(answer);bytes=Buffer.from(JSON.stringify(answer)+'\n');if(bytes.length>BINDING_WIRE_LIMITS.bytes) wireError('provider-not-qualified');}
+  catch {bytes=Buffer.from(JSON.stringify(response(phases.has(phase)?phase:'check',{ok:false,error:{code:'provider-not-qualified',message:'messaging response exceeds the supported wire limits'}}))+'\n');}
+  output.write(bytes);return answer.ok;
+}