@awebai/oats 0.28.0 → 0.29.1

package/lib/core.mjs

@@ -517,7 +517,7 @@ const LAUNCH_CONFIG_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** Environment the kernel sets for every launch (identity, home, roots) and
  *  its reference aliases: a configuration may not name them. */
-export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "OATS_AGENT", "OATS_SOUL", "OATS_SOUL_ID", "OATS_ROOT", "OATS_CONTEXT", "OATS_WORKSPACE", "OATS_EVENT", "OATS_SETTINGS", "OATS_CLI_BIN", "PI_AGENT_INSTANCE", "PI_AGENT_HOME", "PI_AGENTS_ROOT"]);
+export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME", "OATS_HOME", "OATS_AGENT", "OATS_SOUL", "OATS_SOUL_ID", "OATS_ROOT", "OATS_CONTEXT", "OATS_WORKSPACE", "OATS_EVENT", "OATS_SETTINGS", "OATS_SETTINGS_ORIGINS", "OATS_CLI_BIN", "PI_AGENT_INSTANCE", "PI_AGENT_HOME", "PI_AGENTS_ROOT"]);
 export const LAUNCH_REF_PREFIX = "OATS_LAUNCH_REF_";
 const reservedLaunchEnv = (n) => RESERVED_LAUNCH_ENV.has(n) || n.startsWith(LAUNCH_REF_PREFIX);
 export function validateLaunchConfig(name, entry, where) {
@@ -680,7 +680,9 @@ function loadManifestAt(idir, origin, { strict = false } = {}) {
   if (targetFields.length) throw new Error(`capability ${id} manifest cannot declare config-owned targets: ${targetFields.join(", ")}`);
   if (m.layer && !LAYERS.includes(m.layer)) throw new Error(`capability ${id} declares unknown layer "${m.layer}"`);
   if (m.command && !/^[a-z0-9][a-z0-9-]*$/.test(m.command)) throw new Error(`capability ${id} has invalid command namespace "${m.command}"`);
-  if (m.agents !== undefined && (!Array.isArray(m.agents) || m.agents.some((a) => typeof a !== "string"))) throw new Error(`capability ${id} "agents" must be an array of package-relative soul directories`);
+  // `agents:` (capability-defined agents) was removed in 0.29.0: resolution refuses a module that
+  // declares it (E_CAPABILITY_AGENTS_REMOVED). A copy already recorded in a home still loads here,
+  // so that home launches and retires; nothing reads the key.
   validateManifestOperations(m, id);
   validateBindingInterface(m);
   return { ...m, _dir: idir, _origin: origin };
@@ -917,33 +919,6 @@ function manifestPath(manifest, rel) {
 }
 /** Resolve an executable declared by a manifest through the same artifact boundary as hooks. */
 export function capabilityExecutablePath(manifest, rel) { return manifestPath(manifest, rel); }
-function assertCapabilityTreeContained(manifest, tree, resource = "skill") {
-  const artifact = realpathSync(manifest._dir);
-  const visited = new Set();
-  const assertInside = (target, path) => {
-    const fromArtifact = relative(artifact, target);
-    if (fromArtifact === ".." || fromArtifact.startsWith(`..${sep}`) || isAbsolute(fromArtifact)) {
-      throw new Error(`capability ${manifest.capability} ${resource} path escapes its integrity boundary: ${relative(manifest._dir, path)}`);
-    }
-  };
-  const walk = (dir) => {
-    const realDir = realpathSync(dir);
-    assertInside(realDir, dir);
-    if (visited.has(realDir)) return;
-    visited.add(realDir);
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      const path = join(dir, entry.name);
-      const target = realpathSync(path); // also rejects broken symlinks
-      assertInside(target, path);
-      if (entry.isSymbolicLink()) {
-        // Recurse through contained directory links: descendants may carry a
-        // second symlink that escapes the package boundary.
-        if (lstatSync(target).isDirectory()) walk(target);
-      } else if (entry.isDirectory()) walk(path);
-    }
-  };
-  walk(tree);
-}
 /** Packaged default injection for a capability or work mode (undefined if none shipped). */
 export function packagedInject(name, startDir) {
   const m = capabilityManifest(name, startDir);
@@ -1014,7 +989,6 @@ export function composeInstanceAgentsMd(soulDir, contextDir, soulName, workMode,
   const workModeInject = packagedInject(`work-${workMode || "checkout"}`);
   if (workModeInject && existsSync(workModeInject)) wanted.push([`work-mode:${workMode || "checkout"}`, workModeInject]);
   for (const cap of resolved.capabilities) {
-    if (kind === "capability" && cap.layer === "knowledge") continue; // ephemeral: no memory protocol
     if (cap.inject && existsSync(cap.inject)) wanted.push([`capability:${cap.id}`, cap.inject]);
   }
   const blocks = wanted.map(([source, file]) => ({ source, file, content: readFileSync(file, "utf8").trim() }));
@@ -1136,20 +1110,12 @@ export function planInstanceResources({ resolved, soulDir, agent, contextDir, co
         if (typeof declared !== "string" || !declared) continue;
         expected.push({ type: "skill-tree", source: cap.id, declared, path: undefined, entries: [], deferred: "materialize", origin: cap.origin, module: cap.id });
       }
-      const intentionallyDroppedPlanned = agent?.kind === "capability" && cap.layer === "knowledge";
-      if (cap.injectDeclared && !intentionallyDroppedPlanned) expected.push({ type: "injection", source: cap.id, declared: cap.injectDeclared, path: undefined, deferred: "materialize", origin: cap.origin, module: cap.id });
+      if (cap.injectDeclared) expected.push({ type: "injection", source: cap.id, declared: cap.injectDeclared, path: undefined, deferred: "materialize", origin: cap.origin, module: cap.id });
       continue;
     }
     for (const s of cap.skillsDeclared || []) {
       add({ type: "skill-tree", source: cap.id, declared: s.declared, path: s.path, origin: cap.origin, level: cap.level });
     }
-    // Capability agents are ephemeral and deliberately get no memory protocol,
-    // so composeInstanceAgentsMd drops knowledge-layer injections for them.
-    // The expected set MUST apply the same rule or it reports an intentional
-    // omission as an incomplete composition. (Coupled to the matching `continue`
-    // in composeInstanceAgentsMd — change both together.)
-    const intentionallyDropped = agent?.kind === "capability" && cap.layer === "knowledge";
-    if (intentionallyDropped) continue;
     // A capability that declares `inject:` must produce it.
     if (cap.injectDeclared && cap.inject === undefined) {
       add({ type: "injection", source: cap.id, declared: cap.injectDeclared, path: undefined, origin: cap.origin, level: cap.level });
@@ -1589,6 +1555,10 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, s
           // a caller's extraEnv: those may point at a different executable.
           OATS_CLI_BIN: realpathSync(join(PKG_ROOT, "bin", "oats.mjs")),
           OATS_SETTINGS: JSON.stringify(cap.settings || {}),
+          // Where each leaf of OATS_SETTINGS came from (JSON pointer → { kind, at }; kind is
+          // manifest-default | workspace | soul | host | spawn | anchor), so a provider can tell a
+          // soul-set value from a host-set one. {} when the home recorded none (spawned before 0.29).
+          OATS_SETTINGS_ORIGINS: JSON.stringify(cap.settingsOrigins || {}),
           OATS_META: JSON.stringify(priorMeta[cap.id] || {}),
         },
       }).trim();
@@ -1605,7 +1575,7 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, s
       // A launch hook's run is recorded even when its answer is empty: an
       // empty answer replaces what the provider contributed before.
       if (event === "launch" || (o.launch && typeof o.launch === "object" && Object.keys(o.launch).length) || (o.env && typeof o.env === "object" && Object.keys(o.env).length)) {
-        results.contributions.push({ capability: cap.id, layer: cap.layer || null, level: cap.level || null, settings: { ...(cap.settings || {}) }, trust: { trusted: !!cap.trust?.trusted, integrity: cap.trust?.integrity || null }, launch: o.launch && typeof o.launch === "object" ? { ...o.launch } : {}, env: o.env && typeof o.env === "object" ? Object.keys(o.env).sort() : [] });
+        results.contributions.push({ capability: cap.id, layer: cap.layer || null, level: cap.level || null, settings: { ...(cap.settings || {}) }, settingsOrigins: { ...(cap.settingsOrigins || {}) }, trust: { trusted: !!cap.trust?.trusted, integrity: cap.trust?.integrity || null }, launch: o.launch && typeof o.launch === "object" ? { ...o.launch } : {}, env: o.env && typeof o.env === "object" ? Object.keys(o.env).sort() : [] });
       }
       if (o.env !== undefined) {
         if (event !== "spawn" && event !== "launch") throw new HookEnvironmentContractError(`${cap.id} hook env is supported only for spawn and launch, not ${event}`);
@@ -1694,91 +1664,6 @@ export function findAgentAt(root, name, soulDir) {
   return agent;
 }
 
-/** Canonical capability-defined agents: a manifest's `agents: ["agents/reviewer"]`
- * entries are package-relative soul directories (soul.yaml + AGENTS.md directly
- * inside). They resolve when the capability is ACTIVE in the
- * context; the soul stays read-only in the package (fresh identity every spawn —
- * no long-term memory), while instances home under <root>/<name>/instances/ (the
- * agent dir holds only instances/). */
-function capabilityAgentMetadata(manifest, rel) {
-  const soulDir = manifestPath(manifest, rel);
-  const soulFile = manifestPath(manifest, join(rel, "soul.yaml"));
-  if (!soulDir || !soulFile) return undefined;
-  // Read only contained identity metadata to decide whether this provider owns
-  // the requested name. Full tree containment + trust happen after a match.
-  const soul = soulHarnessField(stripInternalAnnotations(withConfigFile(soulFile, () => parseYamlFlat(readFileSync(soulFile, "utf8")))), soulFile);
-  return { soulDir, soul, name: soul.name || basename(soulDir) };
-}
-/**
- * Workspace model: a capability-defined agent (a package's `agents:` soul, e.g.
- * OKF's memory-harvest worker) resolves from a MATERIALIZED module — the copy the
- * requesting instance already carries under <home>/.oats/modules/<cap>/. Looks in
- * `anchorHome` first (the --parent / --relative-to instance), then every instance
- * home under `root`; the first module declaring an agent of that name wins.
- * → the same shape findCapabilityAgent returns, plus `_manifestSource` (the home
- * whose modules supplied it) so skill/inject lookups read that copy.
- */
-export function findModuleCapabilityAgent(root, name, { anchorHome = null } = {}) {
-  if (typeof name !== "string" || !name) return undefined;
-  const homes = [];
-  if (anchorHome) homes.push(anchorHome);
-  if (root && existsSync(root)) {
-    for (const a of readdirSync(root, { withFileTypes: true })) {
-      if (!a.isDirectory() || a.name.startsWith(".")) continue;
-      const inst = join(root, a.name, "instances");
-      if (!existsSync(inst)) continue;
-      for (const i of readdirSync(inst, { withFileTypes: true })) if (i.isDirectory() && !i.name.startsWith(".")) homes.push(join(inst, i.name));
-    }
-  }
-  const seen = new Set();
-  const failures = [];
-  for (const home of homes) {
-    const real = (() => { try { return realpathSync(home); } catch { return null; } })();
-    if (!real || seen.has(real)) continue;
-    seen.add(real);
-    const modules = instanceModulesRoot(real);
-    if (!modules) continue;
-    for (const [id, manifest] of Object.entries(capabilityManifests(real))) {
-      for (const rel of manifest?.agents || []) {
-        let meta;
-        try { meta = capabilityAgentMetadata(manifest, rel); } catch { continue; }
-        if (!meta || meta.name !== name) continue;
-        try {
-          assertCapabilityTreeContained(manifest, meta.soulDir, "agent");
-          return {
-            ...meta.soul, name,
-            kind: "capability", capability: id,
-            _dir: join(root, name),
-            _soulDir: meta.soulDir,
-            _manifestSource: real,
-            _module: manifest._module,
-          };
-        } catch (e) { failures.push(e); }
-      }
-    }
-  }
-  if (failures.length) throw failures[0];
-  return undefined;
-}
-/**
- * A capability-defined agent from ONE capability directory (a package tree the
- * workspace resolver fetched into the deployment's module store). The manifest is
- * read from `dir`, trusted by construction (the workspace declares the package; the lock pins it), and
- * the agent record points its skill/inject lookups at that store entry.
- */
-export function capabilityAgentFromDir(dir, name, root, { module = null } = {}) {
-  const manifest = loadManifestAt(dir, `module:${dir}`);
-  if (!manifest) return undefined;
-  manifest._module = module;
-  for (const rel of manifest.agents || []) {
-    let meta;
-    try { meta = capabilityAgentMetadata(manifest, rel); } catch { continue; }
-    if (!meta || meta.name !== name) continue;
-    assertCapabilityTreeContained(manifest, meta.soulDir, "agent");
-    return { ...meta.soul, name, kind: "capability", capability: manifest.capability, _dir: join(root, name), _soulDir: meta.soulDir, _manifestSource: dir, _manifest: manifest, _module: module };
-  }
-  return undefined;
-}
 export function listAgents(root) {
   const agents = [];
   const scan = (base, kind) => {
@@ -1906,11 +1791,20 @@ const nameTooLong = (name, remedy) => oatsError("E_INSTANCE_NAME_INVALID", `inst
  *  final name, suffix included, is capped at MAX_INSTANCE_NAME. */
 function nextInstanceName(root, agent, purpose, prepared) {
   const n = deriveInstanceName(root, agent, purpose, prepared);
-  if (n.length > MAX_INSTANCE_NAME) throw nameTooLong(n, purpose ? `shorten the purpose (${JSON.stringify(slug(purpose))})` : `the soul name "${agent.name}" is too long to derive an instance name from; pass a shorter --name`);
-  return n;
-}
+  if (n.length <= MAX_INSTANCE_NAME) return n;
+  if (!purpose) throw nameTooLong(n, `the soul name "${agent.name}" is too long to derive an instance name from; pass a shorter --name`);
+  // Say the budget: the name is <agent name>-<purpose>[-<n>], and a package soul's agent name
+  // carries its package id (oats-okf-knowledge-maintainer-…), so its purposes are short.
+  const p = slug(purpose), prefix = `${slug(agent.name)}-`, suffix = n.length - prefix.length - p.length;
+  const budget = Math.max(0, MAX_INSTANCE_NAME - prefix.length - suffix);
+  throw Object.assign(nameTooLong(n, `the purpose ${JSON.stringify(p)} is ${p.length} characters; ${agent.name}'s instances are named ${prefix}<purpose>${suffix > 0 ? "-<n>" : ""}, which leaves at most ${budget} for the purpose — shorten it, or pass --name`), { details: { prefix, purpose: p, maxPurpose: budget } });
+}
+// The stem is the agent name AS A SLUG: a package soul's agent name holds `--`
+// (acme-pkg--keeper) and its instances are acme-pkg-keeper-<purpose>, so the name
+// that is length-checked and de-duplicated here is the one the home gets.
 function deriveInstanceName(root, agent, purpose, prepared) {
-  const base = purpose ? `${agent.name}-${slug(purpose)}` : undefined;
+  const stem = slug(agent.name);
+  const base = purpose ? `${stem}-${slug(purpose)}` : undefined;
   const instancesDir = join(agent._dir, "instances");
   const own = existsSync(instancesDir) ? readdirSync(instancesDir) : [];
   const instances = deploymentInstanceHomes(root), souls = deploymentSoulNames(root, prepared);
@@ -1921,7 +1815,7 @@ function deriveInstanceName(root, agent, purpose, prepared) {
     return n;
   }
   let i = own.length + 1, n;
-  do { n = `${agent.name}-${i++}`; } while (taken(n));
+  do { n = `${stem}-${i++}`; } while (taken(n));
   return n;
 }
 
@@ -1981,6 +1875,19 @@ export function resolveClaudeBinary(contextDir) {
  * claude takes aliases/bare claude-* ids only; nothing usable → "" (claude default).
  * codex: translate openai/openai-codex entries to native ids, otherwise use its default.
  * Probe failures: first entry wins (pi errors loudly at launch). */
+/** instance.json `modelFrom` (feature desktop-facts): where the model a home runs came from — "soul" (the
+ *  soul's preference), "spawn" / "start" (an explicit --model then), "launch-config", "harness-default" (the
+ *  harness's native model). A recorded model keeps `prior`. From resolveLaunchSelection's `modelSource`. */
+export function modelFromOf(modelSource, { at = "spawn", prior = null } = {}) {
+  if (typeof modelSource !== "string") return prior ?? null;
+  if (modelSource === "explicit") return at;
+  if (modelSource === "soul default") return "soul";
+  if (modelSource.startsWith("launch-config ")) return "launch-config";
+  if (modelSource === "recorded") return prior ?? null;
+  if (modelSource.startsWith("native default")) return "harness-default";
+  return prior ?? null;
+}
+
 export function resolveModelPreference(model, harness = "pi") {
   const prefs = String(model || "").split(",").map((s) => s.trim()).filter(Boolean);
   if (harness === "codex") {
@@ -2553,7 +2460,7 @@ function* spawnBody(root, agent, o = {}) {
   if (o.name !== undefined) instance = explicitInstanceName(o.name);
   else {
     instance = o.instance || nextInstanceName(root, agent, o.purpose, o.prepared);
-    if (!instance.startsWith(agent.name)) instance = `${agent.name}-${slug(instance)}`;
+    if (!instance.startsWith(agent.name) && !instance.startsWith(slug(agent.name))) instance = `${agent.name}-${slug(instance)}`;
     instance = slug(instance);
     if (instance.length > MAX_INSTANCE_NAME) throw nameTooLong(instance, "pass a shorter instance name");
   }
@@ -2815,7 +2722,9 @@ function* spawnBody(root, agent, o = {}) {
   }
 
   const home = join(agent._dir, "instances", instance);
-  if (existsSync(home)) throw new Error(`instance already exists: ${home}`);
+  // A home that exists already is the same refusal as losing the exclusive mkdir below (a
+  // concurrent apply that got there first, or anything else): E_PLACEMENT_TAKEN, nothing created.
+  if (existsSync(home)) throw Object.assign(oatsError("E_PLACEMENT_TAKEN", `${instance} already exists at ${home}; nothing was created by this call`), { instance, home });
   // AUTHORITATIVE placement check, on the DESTINATION rather than on lexical
   // paths, immediately before the first side effect. The earlier root/agent-dir
   // checks are lexical and can be walked around by a symlink anywhere along the
@@ -2857,7 +2766,7 @@ function* spawnBody(root, agent, o = {}) {
   // reads the soul, config chain and capability content), so resolving it here
   // lets every "declared but missing" failure happen with zero side effects to
   // roll back — no home, no worktree, no identity, no tmux window.
-  // Capability-defined agents carry _soulDir (read-only soul inside the package).
+  // A workspace soul carries _soulDir (its per-commit soul cache: findAgentAt).
   const soulDir = agent._soulDir || soulOf(agent._dir);
   const composition = composeInstanceAgentsMd(soulDir, repoAbs, agent.name, work, agent.kind, o.prepared);
   const resolvedCfg = composition.resolved;
@@ -3041,13 +2950,7 @@ function* spawnBody(root, agent, o = {}) {
       materializeOutcome = yield () => (o.materialize ?? materializePreparedDefault)({ ...o.prepared, soulAgentsMd: composition.text, soulDir }, home);
       const rows = (typeof o.prepared.toCapabilityRows === "function" ? o.prepared.toCapabilityRows : toCapabilityRows)(o.prepared.resolution, home);
       if (!Array.isArray(rows)) throw new Error("toCapabilityRows returned no rows");
-      // A capability agent runs no provider hook — not even its providing module's
-      // (lead decision c3 Q1: a harvester never registers as a knowledge source or
-      // gets a messaging identity). Its rows keep everything else.
-      for (const row of rows) {
-        if (agent.kind === "capability") { row.hooks = {}; row.requiredHooks = []; }
-        else row.hooks = materializedHookCommands(row, home);
-      }
+      for (const row of rows) row.hooks = materializedHookCommands(row, home);
       resolvedCfg.capabilities = rows;
       // S1: the capability blocks materialize appended are part of the composed
       // instructions. Read the markers back from the AGENTS.md that was WRITTEN
@@ -3523,7 +3426,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     const moduleSkills = (materializeOutcome?.skills || []).map((row) => ({ name: row.name, source: `module:${row.module}`, from: join(home, row.from) }));
     const meta = {
       agent: agent.name, kind: agent.kind || "persistent", instance, home, soulDir: homeSoulTarget,
-      repo: repoAbs, work, branch, harness, model: model || undefined,
+      repo: repoAbs, work, branch, harness, model: model || undefined, modelFrom: modelFromOf(launchSelection.modelSource, { at: "spawn" }) ?? undefined,
       ...(yolo !== undefined ? { yolo } : {}),
       parentInstance: parentInstance && parentInstance !== instance ? parentInstance : undefined,
       siblingInstance: siblingInstance && siblingInstance !== instance ? siblingInstance : undefined,
@@ -3541,7 +3444,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       capabilityMeta: Object.keys(hookRes.meta).length ? hookRes.meta : undefined,
       capabilities: resolvedCfg.capabilities.map((cap) => ({
         id: cap.id, layer: cap.layer, command: cap.command, origin: cap.origin, level: cap.level,
-        settings: cap.settings, provenance: cap.provenance, skills: cap.skills || [],
+        settings: cap.settings, settingsOrigins: cap.settingsOrigins ?? {}, provenance: cap.provenance, skills: cap.skills || [],
         hooks: Object.keys(cap.hooks || {}), trusted: !!cap.trust?.trusted,
         ...(cap.environment?.length ? { environment: [...cap.environment] } : {}),
         ...(cap.environmentNamespaces?.length ? { environmentNamespaces: [...cap.environmentNamespaces] } : {}),
@@ -3586,7 +3489,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
         },
       },
       capabilityRuntime: resolvedCfg.capabilities.map((cap) => ({
-        id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings,
+        id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings, settingsOrigins: cap.settingsOrigins ?? {},
         hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment, environmentNamespaces: cap.environmentNamespaces,
         missingRequires: cap.missingRequires, trust: cap.trust,
         executable: cap.executable,
@@ -3748,6 +3651,12 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
           catch (error) { liveness = { running: null, runtimeState: "unreachable", runtimeError: error.message }; }
         }
         const identity = servedIdentityOf(meta);
+        // Feature desktop-facts: `startedAt` — the last session start or restart (the receipt's restarts[]),
+        // else the spawn's own launch (createdAt), else null (never launched); `identityAddress` — the
+        // messaging identity's address (or alias) its capability recorded, null otherwise; `modelFrom` — null
+        // for a home spawned before it was recorded.
+        const lastStart = Array.isArray(meta.restarts) && meta.restarts.length ? meta.restarts[meta.restarts.length - 1]?.startedAt ?? null : null;
+        const facts = { startedAt: lastStart ?? (meta.launched ? meta.createdAt ?? null : null), identityAddress: identity ? identity.address ?? identity.alias ?? null : null, modelFrom: meta.modelFrom ?? null };
         // The home IS the directory enumerated here, and the instance its name:
         // a file inside it cannot relocate or rename itself in the roster (every
         // consumer acting on `home` — retire, inspect --home, the Desktop's file
@@ -3757,7 +3666,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION) {
           ...(meta.home !== undefined && meta.home !== home ? { recordedHome: meta.home } : {}),
           ...(meta.instance !== undefined && meta.instance !== e.name ? { recordedInstance: meta.instance } : {}),
         };
-        return { ...meta, ...claims, home, instance: e.name, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
+        return { ...meta, ...claims, home, instance: e.name, ...facts, ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(retirePending ? { retirePending } : {}) };
 
       });
   };
@@ -3944,7 +3853,7 @@ function quarantineInstanceHome({ home, instance, agent, soulDir, soulId, incomp
         ...(sessionTarget ? { sessionTarget } : {}),
         outstanding: { hooks: [...outstandingHooks], git: [...outstandingGit], ...(directoryPreservation ? { directory: true } : {}) },
         capabilityRuntime: (resolvedCfg.capabilities || []).map((cap) => ({
-          id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings,
+          id: cap.id, layer: cap.layer, level: cap.level, settings: cap.settings, settingsOrigins: cap.settingsOrigins ?? {},
           hooks: cap.hooks, requiredHooks: cap.requiredHooks, environment: cap.environment, environmentNamespaces: cap.environmentNamespaces,
           missingRequires: cap.missingRequires,
           trust: cap.trust, executable: cap.executable,
@@ -4541,7 +4450,9 @@ export function capturedProviders(meta, frozen) {
   return ids.map((id) => {
     const contribution = contributions.find((c) => c.capability === id) || null;
     const binding = bindings.find((b) => b.id === id) || null;
-    return { id, contribution, binding, settings: contribution?.settings ?? binding?.settings ?? {} };
+    // The origins travel with the settings they describe (the contribution's, else the binding's).
+    const settingsOrigins = (contribution?.settings ? contribution.settingsOrigins : binding?.settingsOrigins) ?? {};
+    return { id, contribution, binding, settings: contribution?.settings ?? binding?.settings ?? {}, settingsOrigins };
   });
 }
 /** Capability contributions for a start of an existing home: the recorded
@@ -4569,7 +4480,7 @@ export function prepareLaunchHooks({ frozen, harness, resolvedCfg, home, meta, c
     const trust = capabilityTrust(manifest);
     if (!trust.trusted) throw oatsError("E_LAUNCH_PREPARATION", `${p.id} was part of this home's launch at spawn but is no longer trusted in the scope (${trust.reason || "not trusted"}); respawn the instance; nothing was stopped`);
     const hooks = manifestHookCommands(manifest);
-    if (hooks.launch) withLaunchHook.push({ id: p.id, capability: p.id, manifest, layer: p.contribution?.layer ?? p.binding?.layer ?? manifest.layer ?? null, level: p.contribution?.level ?? p.binding?.level ?? null, settings: p.settings, hooks, trust, environment: [...(manifest.environment || [])], environmentNamespaces: [...(manifest.environmentNamespaces || [])], missingRequires: [] });
+    if (hooks.launch) withLaunchHook.push({ id: p.id, capability: p.id, manifest, layer: p.contribution?.layer ?? p.binding?.layer ?? manifest.layer ?? null, level: p.contribution?.level ?? p.binding?.level ?? null, settings: p.settings, settingsOrigins: p.settingsOrigins, hooks, trust, environment: [...(manifest.environment || [])], environmentNamespaces: [...(manifest.environmentNamespaces || [])], missingRequires: [] });
   }
   if (withLaunchHook.length) {
     const res = runLifecycleHooks("launch", { assertRoots, home, instance: meta.instance, agentName: meta.agent, soulDir: instanceSoulDir(home, meta), contextDir: ctx, rootDir: dirname(dirname(dirname(home))), resolved: { ...(resolvedCfg || {}), capabilities: withLaunchHook }, priorMeta: meta.capabilityMeta || {}, extraEnv: { OATS_HARNESS: harness, OATS_PREVIOUS_HARNESS: frozen.harness || "", OATS_RUNTIME: harness, OATS_PREVIOUS_RUNTIME: frozen.harness || "", ...extraEnv } });
@@ -4671,7 +4582,7 @@ export function startInstanceSession(home, o = {}) {
   // The independent receipt first (retire and session consult it), then the
   // mutable metadata; both tmp+rename. A failure between them is what the
   // pending receipt exists for.
-  const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, harness: newHarness, yolo: newYolo, stop, nativeRecordId, hookMeta }, clearPending = true) => {
+  const record = (meta, { id, backend, target, model, command, startedAt, reused, launch, harness: newHarness, yolo: newYolo, stop, nativeRecordId, hookMeta, modelFrom }, clearPending = true) => {
     checkRoots();
     const baselinePath = retirementBaselinePath(realHome);
     let baseline;
@@ -4685,7 +4596,7 @@ export function startInstanceSession(home, o = {}) {
     const recorded = meta.startId === id;
     const restarts = (Array.isArray(meta.restarts) ? meta.restarts : []).slice(recorded ? -20 : -19);
     if (!recorded) restarts.push({ startedAt, model: model ?? null, reused });
-    const next = { ...meta, model, command, launched: true, startId: id, restarts, restartCount: (meta.restartCount || 0) + (recorded ? 0 : 1),
+    const next = { ...meta, model, command, launched: true, startId: id, restarts, restartCount: (meta.restartCount || 0) + (recorded ? 0 : 1), ...(modelFrom ? { modelFrom } : {}),
       ...(launch ? { launch } : {}), ...(newHarness ? { harness: newHarness } : {}), ...(newYolo !== undefined ? { yolo: newYolo } : {}),
       // Launch-hook meta lands per capability over the spawn's record; a hook
       // that answered without meta keeps its previous entry (retire reads it).
@@ -4770,7 +4681,7 @@ export function startInstanceSession(home, o = {}) {
     // preflight happens here, before anything is observed or stopped.
     const selected = o.launchConfig !== undefined || o.harness !== undefined || o.yolo !== undefined;
     const hasRecipe = meta.launch && typeof meta.launch === "object";
-    let launchPlan = null;
+    let launchPlan = null, explicitModelFrom = null;
     if (selected || hasRecipe) {
       // Every start of a home with a recipe (ordinary, model-only, or under a
       // selection) goes through the one planner: recipe shape, the recorded
@@ -4783,13 +4694,13 @@ export function startInstanceSession(home, o = {}) {
       const resolvedCfg = resolvedFromHome(realHome, meta, { teams: o.teams, teamsSource: o.teamsSource });
       let agent; try { agent = findAgent(dirname(dirname(dirname(realHome))), meta.agent); } catch { agent = undefined; }
       const plan = planLaunch({ home: realHome, instance: meta.instance, meta, contextDir: context, agentLike: agent || { harness: meta.harness, model: meta.model, yolo: meta.yolo }, selection: { launchConfig: o.launchConfig, harness: o.harness, model: o.model, yolo: o.yolo }, resolvedCfg, env: o.env || process.env, assertRoots: checkRoots });
-      launchPlan = { recipe: plan.recipe, command: plan.command, harness: plan.harness, model: plan.model, yolo: plan.yolo, ...(plan.hookMeta ? { hookMeta: plan.hookMeta } : {}) };
+      launchPlan = { recipe: plan.recipe, command: plan.command, harness: plan.harness, model: plan.model, yolo: plan.yolo, modelFrom: modelFromOf(plan.modelSource, { at: "start", prior: meta.modelFrom ?? null }), ...(plan.hookMeta ? { hookMeta: plan.hookMeta } : {}) };
       command = launchPlan.command; model = launchPlan.model;
     } else if (o.model !== undefined && o.model !== null && String(o.model).trim() !== "") {
       const resolved = resolveModelPreference(String(o.model), harness);
       if (!resolved) throw oatsError("E_MODEL_UNKNOWN", `model preference ${JSON.stringify(o.model)} has no entry usable by harness ${harness}; give a ${harness} model id`);
       command = withLaunchModel(command, resolved);
-      model = resolved;
+      model = resolved; explicitModelFrom = "start";
     } else parseLaunchCommand(command);
     // References recorded for this home must resolve on this host on every
     // start path, and the source variables go to the pane, not the command.
@@ -4799,8 +4710,8 @@ export function startInstanceSession(home, o = {}) {
     const paneEnvFlags = paneEnv.flatMap((r) => ["-e", `${r.name}=${r.value}`]);
     const paneEnvExports = paneEnv.map((r) => `export ${r.name}=${shq(r.value)}; `).join("");
     checkRoots(); // launch hooks/preparation have run; no backend has been observed
-    const planExtra = launchPlan ? { launch: launchPlan.recipe, harness: launchPlan.harness, yolo: launchPlan.yolo,
-      ...(launchPlan.hookMeta ? { hookMeta: launchPlan.hookMeta } : {}) } : {};
+    const planExtra = launchPlan ? { launch: launchPlan.recipe, harness: launchPlan.harness, yolo: launchPlan.yolo, ...(launchPlan.modelFrom ? { modelFrom: launchPlan.modelFrom } : {}),
+      ...(launchPlan.hookMeta ? { hookMeta: launchPlan.hookMeta } : {}) } : (explicitModelFrom ? { modelFrom: explicitModelFrom } : {});
     let target = receipt.target;
     let state = { present: false, state: "not-launched" };
     let serverGone = false;

package/lib/instance-git.mjs

@@ -138,6 +138,33 @@ function remoteOf(work, branch) {
   if (!url) return null;
   return { name, url, ...parseRemoteUrl(url), source: configured && configured !== "." ? "branch-upstream" : "origin" };
 }
+/** Per-file line counts (0.29.1), from ONE `git diff <captured HEAD> --numstat -z -M`: the working tree
+ *  against the observed commit, staged and unstaged combined. That is the same baseline as the status letters
+ *  and `oats instance diff`. An unborn tree counts against the empty tree (`hash-object` without -w writes nothing).
+ *  → Map path → { additions, deletions, binary }, keyed by the NEW path for a rename; null when git failed.
+ *  -z records: "A\tD\tpath\0", or "A\tD\t\0old\0new\0" for a rename; "-\t-" is a binary file. */
+function lineCounts(work, headOid) {
+  const against = headOid ?? trim(git(work, ["hash-object", "-t", "tree", "/dev/null"], { allowFail: true }));
+  if (!against) return null;
+  const raw = git(work, ["diff", against, "--numstat", "-z", "-M", "--"], { allowFail: true });
+  if (raw === null) return null;
+  const counts = new Map(), recs = raw.split("\0");
+  for (let i = 0; i < recs.length;) {
+    const m = /^(-|\d+)\t(-|\d+)\t([\s\S]*)$/.exec(recs[i++]);
+    if (!m) continue;
+    let path = m[3];
+    if (path === "") { i++; path = recs[i++]; } // a rename: skip the old path, key the new one
+    if (typeof path !== "string" || !path) continue;
+    counts.set(path, m[1] === "-" ? { additions: null, deletions: null, binary: true } : { additions: Number(m[1]), deletions: Number(m[2]), binary: false });
+  }
+  return counts;
+}
+/** An entry's counts: untracked (no baseline; contents are not read) and submodules have none (all null). */
+function countsOf(counts, entry) {
+  if (entry.kind === "untracked" || entry.submodule) return { additions: null, deletions: null, binary: null };
+  return counts?.get(entry.path) ?? { additions: null, deletions: null, binary: null };
+}
+
 function fileId(revision, indexOid, entry) {
   return createHash("sha256").update(`${revision}\0${indexOid}\0${entry.kind}\0${entry.path}\0${entry.origPath ?? ""}`).digest("hex").slice(0, 24);
 }
@@ -164,7 +191,8 @@ export function observeInstanceGit(home) {
     const counts = mergeBase ? countRange(work, `${base.ref}...HEAD`) : null;
     baseComparison = { ref: base.ref, source: base.source, mergeBase, ahead: counts ? counts.right : null, behind: counts ? counts.left : null };
   }
-  const files = entries.filter((e) => e.kind !== "ignored").map((e) => ({ id: fileId(revision, indexOid, e), ...e }));
+  const counts = lineCounts(work, headOid);
+  const files = entries.filter((e) => e.kind !== "ignored").map((e) => ({ id: fileId(revision, indexOid, e), ...e, ...countsOf(counts, e) }));
   const summary = { changed: 0, renamed: 0, copied: 0, unmerged: 0, untracked: 0 };
   for (const f of files) summary[f.kind]++;
   return {
@@ -178,6 +206,7 @@ export function observeInstanceGit(home) {
     notes: [
       ...(upstream.ref === null ? ["no upstream configured: upstream ahead/behind are unknown, not zero"] : []),
       ...(baseComparison.ref === null ? ["no default branch found (origin/HEAD, origin/main, origin/master, main, master): base comparison unknown"] : []),
+      ...(counts === null ? ["line counts unavailable (git diff --numstat failed): additions/deletions are unknown, not zero"] : []),
     ],
   };
 }

package/lib/instance-inspect.mjs

@@ -120,7 +120,9 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
     soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, team: ws.soul?.team ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems] },
     workspace: { key: ws.key ?? null, name: typeof ws.name === "string" ? ws.name : discovery?.workspace?.name ?? null, deployment, commit: ws.commit ?? null, standalone: ws.standalone === true },
     modules: Object.keys(modules).sort().map((name) => ({ name, from: modules[name]?.from ?? null, manifest: manifests[name] ?? null, dir: join(realHome, ".oats", "modules", name) })),
-    payloads: obj(meta.providers) ? meta.providers : {}, slots, slotsFrom: Object.fromEntries(LAYERS.map((l) => [l, obj(ws.layers?.[l]) ? ws.layers[l].from ?? null : null])), discovery, discoveryError, resolutionError: null,
+    payloads: obj(meta.providers) ? meta.providers : {},
+    payloadOrigins: Object.fromEntries((Array.isArray(meta.capabilities) ? meta.capabilities : []).filter((c) => c && typeof c.id === "string").map((c) => [c.id, obj(c.settingsOrigins) ? c.settingsOrigins : {}])),
+    slots, slotsFrom: Object.fromEntries(LAYERS.map((l) => [l, obj(ws.layers?.[l]) ? ws.layers[l].from ?? null : null])), discovery, discoveryError, resolutionError: null,
     lock: null, prepared: null,
   };
 }
@@ -154,7 +156,8 @@ export async function soulTarget(contextDir, soul, { remoteOptions } = {}) {
       soulDir: cached && existsSync(join(cached, "soul.yaml")) ? cached : null, definition: soulEntry.definition ?? null, problems: [] },
     workspace: { key: discovery?.key ?? null, name: discovery?.workspace?.name ?? null, deployment, commit: discovery?.commit ?? null, standalone: discovery?.standalone === true },
     modules: (res?.modules || []).map((m) => ({ name: m.name, from: m.from ?? null, manifest: m.manifest ?? null, dir: null, module: m })).sort((a, b) => a.name.localeCompare(b.name)),
-    payloads: obj(res?.payloads) ? res.payloads : {}, slots: obj(res?.slots) ? res.slots : Object.fromEntries(LAYERS.map((l) => [l, null])), slotsFrom: obj(res?.slotsFrom) ? res.slotsFrom : {},
+    payloads: obj(res?.payloads) ? res.payloads : {}, payloadOrigins: obj(res?.payloadOrigins) ? res.payloadOrigins : {}, slots: obj(res?.slots) ? res.slots : Object.fromEntries(LAYERS.map((l) => [l, null])), slotsFrom: obj(res?.slotsFrom) ? res.slotsFrom : {},
+    capabilitiesFrom: obj(res?.capabilitiesFrom) ? res.capabilitiesFrom : {}, turnedOff: Array.isArray(res?.turnedOff) ? res.turnedOff : [],
     discovery, discoveryError: null, resolutionError, lock: prepared?.lock ?? null, prepared,
   };
 }
@@ -184,7 +187,9 @@ function capabilityRows(t) {
       else if (op.context === "home" && !t.home) reason = "needs a running home (--home)";
       return { ...op, argv: [m.command ?? null, op.command], available: !reason, reason };
     });
-    return { id: name, version: m.version ?? null, layer: m.layer ?? null, command: m.command ?? null, from, dir,
+    // composedFrom (feature desktop-facts): where the soul's composition took it from — "workspace" |
+    // "team:<label>" | "soul" (layers-from vocabulary); null for a home (not recorded at spawn). `from` is the module's origin.
+    return { id: name, version: m.version ?? null, layer: m.layer ?? null, command: m.command ?? null, from, composedFrom: t.capabilitiesFrom?.[name] ?? null, dir,
       settings: obj(t.payloads[name]) ? t.payloads[name] : {}, declares: declaredSettings(m), compatibility: compatibilityRow(name, m), missingRequires: missing, operations };
   });
 }
@@ -207,6 +212,9 @@ export function inspectDocument(t, { kernel }) {
   return {
     operationsApi: INSPECT_OPERATIONS_API, kernel, subject: t.subject, workspace: t.workspace,
     souls: [soulRow(t)], layers, capabilities,
+    // The capabilities the soul turned off (feature desktop-facts): its `off` over a workspace/team entry
+    // (reason "off"), or a `<slot>: none` that dropped a workspace default (reason "slot-none", slot).
+    capabilitiesOff: (t.turnedOff || []).map(({ name, reason, slot, overrides }) => ({ id: name, off: true, from: "soul", reason, ...(slot ? { slot } : {}), overrides })),
     // Teams contract item 7 (feature `teams`): the ELIGIBLE teams, one per soul label in order —
     // live for a home (`teamsSource: "recorded"` when its workspace could not be read now).
     teams: t.teams ?? null, teamsSource: t.teamsSource ?? null,
@@ -234,7 +242,7 @@ const item = (subject, status, { required = true, reason = null, producer = "ker
 function providerEnv(t, capability, settings) {
   const env = Object.fromEntries(Object.entries(process.env).filter(([k]) => !/^(OATS_|OAS_|PI_)/.test(k)));
   Object.assign(env, teamEnv({ workspace: { key: t.workspace.key, name: t.workspace.name, deployment: t.deployment, team: t.soul.team, slots: t.slots }, payloads: t.payloads, teams: t.teams, teamsSource: t.teamsSource }));
-  return Object.assign(env, { OATS_CAPABILITY: capability, OATS_SETTINGS: JSON.stringify(settings), OATS_CLI_BIN: CLI_BIN, OATS_WORKSPACE: t.deployment,
+  return Object.assign(env, { OATS_CAPABILITY: capability, OATS_SETTINGS: JSON.stringify(settings), OATS_SETTINGS_ORIGINS: JSON.stringify(t.payloadOrigins?.[capability] ?? {}), OATS_CLI_BIN: CLI_BIN, OATS_WORKSPACE: t.deployment,
     ...(t.home ? { OATS_INSTANCE: t.meta.instance, OATS_INSTANCE_HOME: t.home } : {}), OATS_AGENT: t.soul.name, ...(t.soul.soulDir ? { OATS_SOUL: t.soul.soulDir } : {}) });
 }
 /** An executable inside a module directory: both sides realpath'd (a symlink out of