@awebai/oats 0.30.1 → 0.30.3

package/bin/oats.mjs

@@ -27,7 +27,7 @@ import {
   LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
   capabilityManifests, capabilityTrust, capabilityExecutablePath,
   officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
-  findInstanceHome, findInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
+  findInstanceHome, findInstanceHomes, workspaceOf, stopInstanceSession, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, instanceSoulDir, recordedKernelBin, launchConfigsAt, launchReportFor, explicitInstanceName, retireInstance, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
 } from "../lib/core.mjs";
 import {
   writeFileAtomic, LOCK_FILE, readLock, writeLock, resolvePackages, memoizedRemote,
@@ -1792,6 +1792,9 @@ async function status() {
       console.log(`      • ${i.instance}  ${i.retirePending ? "RETIRING" : i.running ? "RUNNING" : "idle"}  (branch ${i.branch || "?"}, ${i.work || "?"})`);
       const key = i.home ?? `${a.name}/${i.instance}`;
       if (i.identity) console.log(`          identity: ${servedIdentityLine(i.identity)}`);
+      // The kernel the home's plain `oats` runs (its last launch's), when it is not this one.
+      const launchedBy = i.home ? recordedKernelBin(i.home) : null;
+      if (typeof launchedBy === "string" && (verbose || launchedBy !== CLI_BIN)) console.log(`          kernel: ${launchedBy}${launchedBy !== CLI_BIN ? " (not this oats)" : ""}`);
       const s = ws?.soul.get(key);
       if (s && (verbose || s.status !== "current")) console.log(`          ${soulDriftLine(s, a.name)}`);
       const rows = ws?.drift.get(key) || [];
@@ -1803,6 +1806,31 @@ async function status() {
   }
 }
 
+/** The flags `oats spawn` reads: those taking a value, and switches. `--provider` takes two words.
+ *  `--instance` is refused by a local spawn (with its replacement) but still travels to an older
+ *  host through `--server`, whose route reads it. */
+const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "herdr-socket", "idempotency-key", "instance", "launch-config", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
+const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "yolo"]);
+/** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
+ *  soul or a flag spawn does not read is never ignored. A value flag consumes its value exactly as
+ *  flag() reads it; a missing value is the flag's own check. */
+function spawnArgvProblem(argv) {
+  const soul = argv[0];
+  for (let i = 1; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--provider") { i += 2; continue; }
+    if (a.startsWith("--")) {
+      const name = a.slice(2);
+      if (SPAWN_SWITCHES.has(name)) continue;
+      if (!SPAWN_VALUE_FLAGS.has(name)) return `oats spawn: unknown flag ${a}`;
+      if (argv[i + 1] !== undefined && !argv[i + 1].startsWith("--")) i++;
+      continue;
+    }
+    if (/^[A-Za-z0-9_.-]+=/.test(a)) return `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: a capability setting is given as --provider <capability> key=value (here: --provider <capability> ${a})`;
+    return `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: spawn takes one soul`;
+  }
+  return undefined;
+}
 async function spawnCmd() {
   // JSON mode: contract envelope, stable error codes, stderr-only progress.
   const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
@@ -1831,6 +1859,7 @@ async function spawnCmd() {
   // The slug rule is checked here too, before any side effect (soul fetch).
   if (nameFlag !== undefined) { try { explicitInstanceName(String(nameFlag)); } catch (e) { bail(e.code, e.message); throw e; } }
   if (args.includes("--ephemeral")) bail("E_BAD_ARGS", "--ephemeral was removed by the runtime-boundary ruling — declare the agent in a capability manifest (agents:) for automatic ephemeral semantics");
+  { const problem = spawnArgvProblem(args.slice(1)); if (problem) bail("E_BAD_ARGS", problem); }
   let root;
   // A spawn needs a workspace deployment (lead decision c3-1): no oats-local.yaml
   // in reach is E_LOCAL_MISSING, before anything else is read. The agents root is
@@ -2823,7 +2852,7 @@ function versionCmd() {
     // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
     // runs on resolve/materialize (contract §6); a feature the binary does not implement is
     // never listed.
-    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-2", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2 }));
+    console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux", "herdr"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-2", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from"], automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2 }));
     return;
   }
   console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3084,6 +3113,12 @@ async function serverRouteCmd() {
     const r = spawnSyncProc(route.argv[0], route.argv.slice(1), { stdio: "inherit" });
     process.exit(r.status ?? 1);
   }
+  // A spawn's argv is checked here, before the server is contacted.
+  if (cmd === "spawn") {
+    const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
+    const problem = spawnArgvProblem(local);
+    if (problem) bail("E_BAD_ARGS", problem);
+  }
   // Everything after the command word travels, minus the routing flags; a
   // local --task-file is read here and travels as --task text, since the
   // remote cannot read this machine's files.

package/docs/capabilities.md

@@ -28,7 +28,7 @@ A capability lives in one of two kinds of source:
 A soul says `capabilities: { <name>: { from: here | <repo key> | package } }`
 (or `off`); the workspace supplies defaults. At spawn every resolved
 capability is **copied whole** into the instance (`<home>/.oats/modules/<name>/`,
-skills into `<home>/.agents/skills/<name>/`), and the instance's `AGENTS.md` is
+its skills flat into `<home>/.agents/skills/<skill>/`), and the instance's `AGENTS.md` is
 generated without changing the canonical soul. Nothing is installed or
 activated at a deployment.
 
@@ -237,8 +237,8 @@ live.
 
 Every spawned instance gets a **full copy** of each capability its soul
 resolved to, under `<home>/.oats/modules/<capability>/` (manifest, `bin/`,
-injects, skills), and those skills under
-`<home>/.agents/skills/<capability>/<skill>/`. Its generated `AGENTS.md` is the
+injects, skills), and those skills flat under `<home>/.agents/skills/<skill>/`
+beside the soul's own, one level deep where harnesses discover them. Its generated `AGENTS.md` is the
 soul's `AGENTS.md`, the kernel and work-mode blocks, then each module's inject
 in name order. Two composed skills with one name fail the spawn
 (`E_SKILL_DUPLICATE`). The harness then starts normally, with its own skill

package/docs/configuration.md

@@ -151,10 +151,27 @@ source variable must be set on the host (`E_LAUNCH_ENV_MISSING`, before
 anything is created or stopped), and only the harness's pane receives it.
 `list` and `preview` redact every environment value, literals included.
 
+**The instance's `oats`.** Every launch (`oats spawn`, `session start`,
+`session restart`, locally or through `--server`) writes `<home>/.oats/bin/oats`,
+a link to the launching kernel's `bin/oats.mjs`, and runs the harness with
+`<home>/.oats/bin` first on `PATH` and the rest of `PATH` unchanged. Plain
+`oats` inside an instance is therefore the kernel that launched it, even on a
+machine whose `PATH` finds another kernel first. A launch configuration's own
+`PATH` (literal or `fromEnv`) comes after it. A restart by a different kernel
+re-points the link to that kernel; `spawn --no-launch` writes it too. The
+recipe in `instance.json` records the target as `launch.kernelBin` (no JSON
+answer carries it); `oats status` prints it
+(`kernel:`) under `--verbose`, or when it is not the `oats` running the status.
+A launch that cannot write the link fails with `E_LAUNCH_SHIM` naming the path
+and the cause: a spawn is rolled back, a start starts nothing. The recorded
+`command` does not carry the `PATH`; the kernel adds it when it runs the
+command. Hooks still receive `OATS_CLI_BIN`, unchanged.
+
 **The launch recipe.** A spawn records what a start is made of in
 `instance.json` under `launch`: the harness, the configuration and where it
 came from, the executable, args, env, model, yolo, and each capability's
-launch contribution with its settings and trust. One renderer turns it into
+launch contribution with its settings and trust, and the kernel that launched
+it (`kernelBin`, re-written by every start). One renderer turns it into
 the `command`. Configuration `args` go after the harness's own options and
 before capability arguments; every argument is single-quoted.
 

package/docs/design/2026-09-23-workspace-module-contracts.md

@@ -286,7 +286,8 @@ shims that throw `E_REMOVED { name, contract }`, pointing at this record.
    must match the lock's commit (`E_MATERIALIZE_INTEGRITY { why: "lock" }`); an unknown repo is
    `E_MATERIALIZE_SOURCE`.
 2. The copy's digest must equal the fetch's and any `module.digest` (`E_MATERIALIZE_INTEGRITY`).
-3. Copy skills whole to `<home>/.agents/skills/<name>/<skill>/`.
+3. Copy skills whole to `<home>/.agents/skills/<skill>/`, flat (0.30.2; the grouped
+   `<name>/<skill>/` layout this section first specified hid every skill from the harnesses).
 4. Compose `<home>/AGENTS.md` = soul body (`options.soulAgentsMd` or `soulDir`) + kernel blocks + module
    injects; operating guidance comes from a module such as `oats.core`. Keep `CLAUDE.md → AGENTS.md`
    and `.claude/skills → ../.agents/skills`.

package/docs/desktop-cli-api.md

@@ -36,7 +36,8 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
              "instance-git-remote","souls-declarations","lifecycle-plans","retire-retention","readiness","spawn-preview","instance-events",
              "instance-events-2","schedule-history","schedule-read-2","spawn-preview-2","spawn-idempotency","spawn-idempotency-2","spawn-apply-2",
              "workspace-v2","instance-modules","spawn-provider-payload","served-identity","packages-no-approval","spawn-name","settings-origins",
-             "team-model-2","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference"],
+             "team-model-2","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
+             "preview-composed-from"],
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2}
 ```
@@ -88,6 +89,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
 | `automations` | workspace triggers and schedules; `oats automations refresh` | `automationsApi: 1` |
 | `desktop-facts` | the facts under [Desktop facts](#desktop-facts-feature-desktop-facts-oats-0290) | |
 | `launch-preference` | soul and local launch preferences; `launch`, `launchCurrent`, `launchFrom`; `--reselect-launch`; `key` on soul and agent rows ([Launch preferences](#soul-launch-preferences-feature-launch-preference-oats-0300)) | |
+| `preview-composed-from` | `composedFrom` on preview `modules[]` ([Composition](#the-preview)) | |
 
 Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
 `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -1073,9 +1075,9 @@ it to a temporary copy (`soulFetched: true`).
 ```json
 {"modules":[
    {"name":"nw-tools","from":{"kind":"member","repoKey":"github.com/nw/agents","commit":"66566512…"},"layer":null,"private":false,"declares":[],
-    "changedSince":{"instance":"rm-2","was":"45b86f64…"}},
+    "changedSince":{"instance":"rm-2","was":"45b86f64…"},"composedFrom":"soul"},
    {"name":"oats.okf","from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"ab897841…","integrity":"sha256-bada35…","repoKey":"github.com/awebai/oats-okf"},
-    "layer":"knowledge","private":false,"declares":["state-dir"],"changedSince":false}],
+    "layer":"knowledge","private":false,"declares":["state-dir"],"changedSince":false,"composedFrom":"workspace"}],
  "teams":[{"label":"eng","team":"eng:nw.aweb.ai","default":true,"from":"shared"}],
  "defaultTeam":{"label":"eng","team":"eng:nw.aweb.ai","from":"soul"},
  "resolution":"abacbdb5a7975098d77007c8","declRevision":"068a0d3f1311a9e84e9aff2e","payloadRevision":"81a368006c610194aa35dbe0",
@@ -1124,9 +1126,18 @@ it to a temporary copy (`soulFetched: true`).
 
 **Composition.**
 - `modules[]` (feature `instance-modules`): `{name, from, layer, private,
-  declares, changedSince}`; `from` is what `instance.json` will record.
-  `changedSince` is `null` (no previous instance), `false` (unchanged since the
-  newest one) or `{instance, was}`.
+  declares, changedSince, composedFrom}`; `from` is what `instance.json` will
+  record. `changedSince` is `null` (no previous instance), `false` (unchanged
+  since the newest one) or `{instance, was}`.
+- `composedFrom` (feature `preview-composed-from`, OATS 0.30.2): why the
+  module is there — `"soul"` (the soul declares it, including a soul entry
+  that overrides a workspace default of the same name, a package soul's
+  `from: here`, and every module of a standalone view) or `"workspace"` (a
+  `defaults.<slot>` or `defaults.capabilities` entry). It is the same value
+  `oats inspect --soul` reports as `capabilities[].composedFrom`. It is
+  provenance only: it never enters `resolution`, `declRevision`,
+  `payloadRevision` or `decision.revision`, and `instance.json` does not
+  record it. `from` says where the bytes come from.
 - `capabilities[]` (`{name, origin}`, `origin` `package:<id>@<v>` or
   `member:<repoKey>@<commit>`) and `skills[]` (the soul's own skills as
   strings, module skills as `{name, source: "module:<cap>"}`) are display
@@ -1146,6 +1157,9 @@ it to a temporary copy (`soulFetched: true`).
   repeatable, `a.b=c` nests): a malformed pair is `E_BAD_ARGS`; a capability
   the soul does not resolve is `E_CAPABILITY_MISSING {capability, soul,
   modules}`.
+- Any other positional after the soul, or a flag spawn does not read, is
+  `E_BAD_ARGS` naming the argument, before anything is resolved; a bare
+  `key=value` is refused with the `--provider <capability> key=value` form.
 
 ### The decision
 
@@ -1228,7 +1242,7 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
 
 | Code | Details | When |
 |---|---|---|
-| `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory or removed flags |
+| `E_USAGE`, `E_BAD_ARGS` | | no soul; bad, contradictory, removed or unknown flags; an argument after the soul |
 | `E_LOCAL_MISSING`, `E_NO_DEPLOYMENT` | | no `oats-local.yaml`; no `agents/` root |
 | `E_SOUL_UNKNOWN` | `{name, members, packages}` | no such soul, or not at `--agents-root` |
 | `E_SOUL_AMBIGUOUS` | `{name, repos, qualified}` | several souls answer the bare name; use one of `qualified` |
@@ -1251,6 +1265,7 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
 | `E_PLACEMENT_TAKEN`, `E_IDEMPOTENCY_CONFLICT` | `{instance, home}` | |
 | `E_SPAWN_INCOMPLETE` | `{instance, home, launched}` | |
 | `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
+| `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
 | `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
 | `E_SPAWN_FAILED` | | anything else |
 
@@ -1288,8 +1303,9 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
 `wake`; later starts add `restarts` and `restartCount`.
 
 - `modules.<cap>`: `{from, commit, digest, materializedAt}`; `digest` hashes
-  the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied to
-  `<home>/.agents/skills/<cap>/<skill>/`.
+  the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied flat to
+  `<home>/.agents/skills/<skill>/` (homes spawned by 0.30.1 or earlier keep
+  `<home>/.agents/skills/<cap>/<skill>/`).
 - `providers.<cap>`: the merged payload (`{}` when none).
 - `workspace`: `{key, name, deployment, commit, resolution, standalone, soul,
   layers}`. `name` is recorded, and every hook, command and operation of the
@@ -1658,8 +1674,9 @@ selection flags. See [the start workflow](desktop-instance-start.md).
 - A lost response does not mean the launch failed: check status before a
   retry. A remote home's saved route names its execution host.
 - Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
-  `E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LAUNCH_*`,
-  `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`, `E_SESSION_FAILED`.
+  `E_SESSION_START_BUSY`, `E_INSTANCE_RETIRING`, `E_LAUNCH_*` (among them
+  `E_LAUNCH_SHIM`: the home's `oats` link cannot be written, nothing was
+  started), `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS`, `E_SESSION_FAILED`.
 
 ### Upload
 

package/docs/execution-targets.md

@@ -59,9 +59,15 @@ id distinguishes a replacement occupant of the same pane.
   (default `~/.config/...`) and starts `herdr --session oats server` if no
   server is running there.
 - The adapter speaks the Herdr socket API at an explicit protocol version,
-  with no negotiation. New sessions use protocol 20. A recorded session target
-  may carry protocol 20 or 22, and each call checks that the server's snapshot
-  reports the recorded protocol.
+  20 or 22. A new session records the protocol its server reports (20 for
+  Herdr 0.8, 22 for 0.9) and refuses any other; before 0.30.3 it always
+  selected 20, so Herdr 0.9 could not be spawned on. A recorded target is
+  never renegotiated: each call, the kernel's and the Desktop's, checks that
+  the server's snapshot reports the recorded protocol.
+- Herdr cannot give a pane a command at creation, so OATS types the launch
+  command into the pane's shell. It waits until the shell has drawn its prompt
+  (`herdr pane read`, at most 10 s): text typed earlier is cut at the
+  terminal's line-buffer limit.
 
 ## Lifecycle
 

package/docs/first-team.md

@@ -120,7 +120,7 @@ oats status
 `--harness pi|claude|codex` picks the harness; complete any native folder
 trust or authentication prompt in the printed session. The instance home is
 `agents/<soul>/instances/<instance>/`; `work/` is its repository view;
-`.oats/modules/<cap>/` and `.agents/skills/<cap>/` are the copied capabilities;
+`.oats/modules/<cap>/` are the copied capabilities and `.agents/skills/<skill>/` their skills;
 `instance.json` records `modules` (from, commit, digest), `providers` and
 `workspace`. A running instance never changes under itself — a member that
 moves affects only new spawns, and `oats status` shows the drift

package/docs/knowledge-capability-authoring.md

@@ -29,7 +29,7 @@ an author soul:
 ```yaml
 # oats-workspace.yaml
 packages:
-  oats.framework: v1.4.0            # provides oats.core, oats.setup, oats.knowledge-theory
+  oats.framework: v1.4.1            # provides oats.core, oats.setup, oats.knowledge-theory
 
 # souls/<author-soul>/soul.yaml
 capabilities:

package/docs/official-catalog.md

@@ -9,7 +9,7 @@ or workspace membership alone does not make a package official.
 
 | package | release | capabilities | package souls |
 |---|---|---|---|
-| `oats.framework` | `oats-framework/v1.4.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
+| `oats.framework` | `oats-framework/v1.4.1` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
 | `oats.okf` | `v4.0.5` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
 | `oats.aweb` | `v1.17.1` | `oats.aweb` (messaging) | |
 | `oats.engineering` | `v1.3.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |

package/docs/packages.md

@@ -51,7 +51,7 @@ packages:
 - **Bare version** (`v4.0.5`, `4.0.5`, `1.0.0-rc.1`): the id is looked up in
   the official catalog — `package-catalog.json` in the `oats` repo, or the file
   named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
-  convention (`v4.0.5` or `oats-framework/v1.4.0`) and the payload path. An id
+  convention (`v4.0.5` or `oats-framework/v1.4.1`) and the payload path. An id
   the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
   a package outside the catalog"). The catalog is the reviewed official list
   ([official-catalog.md](official-catalog.md)) and the only way a
@@ -74,7 +74,7 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.4.0
+  oats.framework: v1.4.1
   oats.okf: v4.0.5
   oats.aweb: v1.17.1
 teams:
@@ -212,7 +212,7 @@ At spawn a `from: package` module is fetched at the lock's commit from the
 lock's `url`, at the manifest-listed directory (`oats-package.json#capabilities[]`
 entry), into `<home>/.oats/modules/<cap>/`; the copy's digest is verified
 against what the fetch reported; skills are copied to
-`<home>/.agents/skills/<cap>/<skill>/`. `instance.json.modules.<cap>.from` is
+`<home>/.agents/skills/<skill>/` (flat). `instance.json.modules.<cap>.from` is
 `{ kind: "package", package, version, commit, integrity, repoKey }`. Bumping
 `packages:` and syncing affects **only new spawns**; `oats status` shows a
 running instance's package module as `moved` once the lock points elsewhere.
@@ -332,11 +332,11 @@ A soul that names one of the package's capabilities with
   "policy": "docs/official-catalog.md",
   "packages": {
     "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v4.0.5", "path": "oats-package" },
-    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.4.0", "path": "oats-package" }
+    "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.4.1", "path": "oats-package" }
   }
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.4.0`
-resolves to tag `oats-framework/v1.4.0`. Resolving through the catalog never
+`ref` carries the tag convention: a workspace's `oats.framework: v1.4.1`
+resolves to tag `oats-framework/v1.4.1`. Resolving through the catalog never
 advances a lock by itself: `oats sync` does, and says so.

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

@@ -0,0 +1,85 @@
+# OATS 0.30.2
+
+## Changed
+
+- **Desktop: a faster, calmer load.** The backend reads a deployment's status
+  and workspace status in parallel, holds the souls and capabilities catalogs
+  and soul inspections server-side (re-read when the workspace state or a
+  Desktop mutation moves, or when viewed after 60 s), and slows its cycle
+  from 5 s to 30 s while no window is focused. Returning to the window no longer
+  re-reads the capabilities list or cancels the observation in flight. When
+  the installed CLI supports `--max-age`, background reads accept the kernel's
+  recent observation; `/api/panel`, `/api/agents`, `/api/workspace-sync` and
+  `/api/capabilities` inspect now report `observedAt` and `refreshing`.
+- **Desktop: Where it works shows the work folder.** The Instance tab's Where
+  it works card adds a Folder row, `<home>/work`, between Branch and Home, with
+  a copy button; in checkout, attached and workspace mode a muted "shared" tag
+  says it links to the tree other instances share.
+
+- **Desktop: consistent loading states.** The sidebar roster, the hierarchy,
+  the soul inspector and readiness now run on one state model: skeletons
+  shaped like the final content instead of false empty lists,
+  content and focus kept while refreshing, stale data labelled with its
+  observation's age and a Retry, and the actions that need current state held
+  with an accessible reason until a good read.
+
+- **Desktop: the Workspace view and the instance panel join the loading-state
+  model.** The Souls grid, the Capabilities tab and its capability pages, and
+  the instance panel's Soul and Messaging sections show skeletons at the real
+  row and card size instead of empty claims, keep their content (and a held
+  table) through a refresh or a failed re-read, and name a stale observation's
+  age with a Retry; the spawn dialog's harness, model and launch hints describe
+  the preview for the choices on screen only.
+- **The spawn preview says why each module is there.** Every `modules[]` row
+  of `oats spawn … --preview --json` carries `composedFrom`: `"soul"` when the
+  soul declares the capability (a package soul's `from: here` and every module
+  of a standalone view included), `"workspace"` when a workspace default
+  (`defaults.<slot>` or `defaults.capabilities`) gave it. It is the value
+  `oats inspect --soul` already reports as `capabilities[].composedFrom`.
+  Provenance only: `resolution`, `declRevision`, `payloadRevision` and the
+  spawn decision are unchanged, so a previewed decision still binds its apply.
+  Gate on the new feature `preview-composed-from`
+  ([Desktop CLI API](../desktop-cli-api.md#the-preview)).
+
+## Fixed
+
+- **Instance skills are flat again, so Claude Code finds them.** Since the
+  workspace model (0.25.0) spawn copied each module's skills grouped by
+  capability, `<home>/.agents/skills/<capability>/<skill>/SKILL.md`. Claude
+  Code discovers skills one level deep (`.claude/skills/<skill>/SKILL.md`), so
+  no capability skill resolved there: `/oats-operate`, `/oats-aweb`,
+  `/okf-consultation` and the rest were missing from the session although the
+  composed `AGENTS.md` tells the agent to load them. (pi's loader recurses, so
+  pi instances were not affected.) Spawn now copies every skill, the soul's
+  own and every module's, flat to `<home>/.agents/skills/<skill>/`, the
+  layout the Agent Skills convention and every harness expect;
+  `.claude/skills → ../.agents/skills` is unchanged. `instance.json` records
+  the flat paths (`capabilities[].skills`; a module's skill tree in
+  `composition.expected[].resolved` is the skills root).
+- **One skill name, one directory.** Every composed skill shares the flat
+  directory, so names are unique across the soul and its modules, compared
+  case-insensitively: a soul's own skill named like a module's skill, or two
+  names differing only in case, is `E_SKILL_DUPLICATE` at spawn and the home
+  is removed. A soul skill named like a *capability* (`oats.okf`) is no
+  longer a collision. No soul in this repository is affected.
+- **oats.framework 1.4.1** (oats.core 2.2.1): the `oats-operate` skill shows
+  the flat layout.
+
+**Existing Claude Code instances keep their grouped layout and still do not
+see their capability skills: respawn them to pick up the fix.** Nothing
+rewrites an existing home: a running instance never changes under itself, and
+moving its skills would contradict what its `instance.json` recorded. Until
+it is respawned, an agent can read a skill by path,
+`.agents/skills/<capability>/<skill>/SKILL.md`.
+
+## Still known in 0.30.2
+
+The 0.30.1 notes planned the first two below for 0.30.2. They are not in this
+release; they are planned for 0.30.3.
+
+- With no teams configured, a spawn is refused by the provider
+  (`E_SPAWN_FAILED`, relaying "no teams configured: run `oats aweb setup`"),
+  not by the kernel's `E_TEAM_UNCONFIGURED`.
+- A capability operator command run from a deployment needs `--soul <soul>`.
+- On a team you control (BYOT), retire cannot revoke membership; the retire
+  prints the owner's `aw id team remove-member` command, as in 0.30.0.

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

@@ -0,0 +1,75 @@
+# OATS 0.30.3
+
+## Changed
+
+- **Desktop: the whole app works from the keyboard, with a Linux-sane keymap.**
+  Changed Linux and Windows defaults: the command palette is now Ctrl+Shift+P
+  on Linux and Windows; close tab Ctrl+Shift+W; split Ctrl+Shift+E /
+  Ctrl+Shift+O (close the split Ctrl+Shift+Alt+W); Spawn instance
+  Ctrl+Shift+N; the theme cycle has no default chord (on macOS too; the palette
+  keeps it). No default chord takes a key a program in the terminal reads:
+  plain Ctrl+W, Ctrl+K, Ctrl+\, Ctrl+P and Ctrl+B, F6, Alt+digit and
+  Ctrl+PgUp/PgDn (and ⌃digits on macOS) always reach the program, and nothing
+  binds Super. New: go to tab (⌥⌘1–⌥⌘9 / Alt+1–Alt+9), Ctrl+PgDn / Ctrl+PgUp,
+  ⌘3 / Ctrl+3 for Automations, and F6 / Shift+F6 to move between the sidebar,
+  the instances, the main area and the instance panel; from a terminal,
+  ⇧⌘F6 / Ctrl+Shift+F6 leaves it for the next region. Your own rebinds are
+  kept; one that now clashes with another shortcut is flagged in the shortcuts
+  editor, never changed for you. Quick Open (⌘P / Ctrl+P)
+  now opens the spawn dialog for the soul you pick, and Esc takes you back to
+  where you were; ⌘↵ / Ctrl+Enter spawns from any field, and Tab walks the
+  form in the order you see it. Keyboard gaps found in an audit are closed:
+  roster rows of unknown state, Independent nodes in the Active overview, the
+  Automations row menu, the schedule form and focus lost after switching tabs
+  or views. The keymap and the audit are in
+  `packages/desktop/docs/desktop-keyboard.md`.
+- **Desktop: the spawn dialog says why each capability is there.** In "What
+  will be created", each Capabilities row shows a muted reason tag beside its
+  source: **Soul**, **Workspace default**, or, for a workspace default that
+  fills a core slot, **Workspace default · messaging** (knowledge, messaging or
+  tasks). It is the preview's `composedFrom`, read only from a CLI that reports
+  `preview-composed-from`; with an older CLI the rows show no tag, never a
+  guess. The Core capabilities table is unchanged.
+- **Desktop: clearer overview lines, a centred rail, pinned Workspace controls.**
+  The Active overview draws parent links as smooth curves from a parent's
+  bottom to its child's top, with dashed arcs between siblings, in a colour
+  that is visible in every theme. The collapsed instance panel's icons sit
+  on its centre line. In Workspace, the Capabilities section pills and search
+  and the Teams header stay in view while the content scrolls, and scrolling
+  to the end of a list no longer moves the whole window.
+
+## Fixes
+
+- **Plain `oats` inside an instance is the kernel that launched it.** On a
+  machine with two kernels side by side (a global 0.24 for classic
+  deployments and a 0.30 prefix install), an agent typing `oats` got whatever
+  `PATH` found first: `oats aweb teams` answered `E_UNKNOWN_COMMAND` in a 0.30
+  home. Every launch (spawn, `session start`, `session restart`) now writes
+  `<home>/.oats/bin/oats`, a link to the launching kernel, and runs the harness
+  with `<home>/.oats/bin` first on `PATH`. A restart by another kernel
+  re-points it. The recipe records the target as `launch.kernelBin`, and
+  `oats status` shows it (`kernel:`) when it is not the running `oats`. A
+  launch that cannot write the link fails with `E_LAUNCH_SHIM`. Existing homes
+  get the link at their next start or restart.
+- **`oats spawn` refuses an argument it does not read.** A positional after
+  the soul, or a flag spawn does not know, is `E_BAD_ARGS` naming it, before
+  anything is resolved or created. `oats spawn <soul> join=oats` used to be
+  accepted and the bare `join=oats` ignored, so the instance joined nothing;
+  the refusal now names the form that was meant, `--provider <capability>
+  key=value`. A routed spawn (`--server`) is refused on this machine, before
+  the server is contacted.
+- **Herdr 0.9 spawns work.** A new Herdr session was always opened at protocol
+  20, so `oats spawn --backend herdr` against Herdr 0.9, which speaks protocol
+  22, failed with "Herdr snapshot does not match selected protocol 20". A new
+  session now records the protocol its server reports when it is one OATS
+  supports (20 or 22), and refuses any other by name. A recorded session is
+  still checked against its recorded protocol on every call and is never
+  renegotiated. The Desktop attaches to protocol-22 sessions too; it accepted
+  only protocol 20 before. An instance recorded at protocol 20 is unreachable
+  after an in-place Herdr 0.8 → 0.9 upgrade until it is respawned.
+- **A Herdr launch no longer arrives cut.** OATS typed the launch command into
+  the new pane before its shell had started. The terminal's line buffer
+  (1024 bytes on macOS) dropped the rest of the longer command, so the harness
+  never started: the shell waited on an unclosed quote. On Herdr 0.9, 0 of 5
+  fresh panes ran a 2000-character command intact. A launch now waits, up to
+  10 s, until the pane has drawn its prompt, then types; 5 of 5 ran intact.

package/docs/souls-and-instances.md

@@ -29,6 +29,7 @@ that model.
 | Instance operating doc | `<home>/AGENTS.md` (generated) |
 | Instance skills | `<home>/.agents/skills/` |
 | Instance modules | `<home>/.oats/modules/<capability>/` (the copies this instance runs) |
+| Instance `oats` | `<home>/.oats/bin/oats` (a link to the kernel that last launched it) |
 | Instance record | `<home>/instance.json` (`modules`, `providers`, `workspace`, `teams`) |
 
 ## Soul anatomy
@@ -122,10 +123,11 @@ full copy** of every capability the soul resolved to:
 <agents-root>/<soul>/instances/<instance>/
   AGENTS.md                        # generated: soul AGENTS.md + kernel/work-mode blocks + each module's inject
   CLAUDE.md → AGENTS.md
-  .agents/skills/                  # canonical skill tree — soul skills + <capability>/<skill>/ full copies
-    <capability>/<skill>/SKILL.md
+  .agents/skills/                  # canonical skill tree, flat: the soul's skills and every module's, full copies
+    <skill>/SKILL.md               # one level deep, where every harness discovers skills
   .claude/skills → ../.agents/skills
   .oats/modules/<capability>/      # the whole capability: oats.json, bin/, injects/, skills/ (hooks run from here)
+  .oats/bin/oats → <kernel>/bin/oats.mjs  # the kernel that last launched this home: first on the harness's PATH
   work/                            # worktree, checkout symlink, attached tree, or private directory
   TASK.md                          # briefing and task
   instance.json                    # provenance (below); `soulDir` = the soul directory hooks get as OATS_SOUL
@@ -193,7 +195,8 @@ bump affects only new spawns.
 OATS is a skill contributor, not a skill sandbox. The harness (pi, Claude Code,
 Codex) starts with cwd = the instance home and its **own** skill discovery
 intact: it sees, nearest first, the instance's `.agents/skills/` (soul skills
-and the copied capability skills), the repo's own `.agents/skills/` once it
+and the copied capability skills, all flat at `.agents/skills/<skill>/SKILL.md`,
+the one level deep Claude Code discovers through `.claude/skills`), the repo's own `.agents/skills/` once it
 works in `work/`, and whatever the operator keeps at machine level. All three
 are intended. Two *composed* skills with one name is a spawn error naming both
 capabilities (`E_SKILL_DUPLICATE`); a composed skill versus an ambient one is
@@ -243,7 +246,10 @@ it would bind, `providers` (the `--provider` map exactly as given) and
 the apply refuses with `E_DECISION_STALE` if a member
 moved in between. `--provider <cap> key=value` (repeatable; dotted keys nest)
 must name a capability the soul resolves (`E_CAPABILITY_MISSING` otherwise) and
-needs a workspace deployment. The full DTOs are in
+needs a workspace deployment. Spawn takes one soul and the flags it reads:
+another positional, or a flag it does not know, is `E_BAD_ARGS` naming the
+argument, before anything is created (a bare `key=value` is a provider
+setting given without `--provider <capability>`). The full DTOs are in
 [desktop-cli-api.md](desktop-cli-api.md#workspace-model-workspaceapi-2).
 
 Examples of spawn hooks:

package/docs/workspaces.md

@@ -54,7 +54,7 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
   - git:github.com/acme/tools              # a member that ALSO publishes a package (see below)
 
 packages:                                  # the ONLY versioned things
-  oats.framework: v1.4.0                   # bare version → resolves through the official catalog
+  oats.framework: v1.4.1                   # bare version → resolves through the official catalog
   oats.okf: v4.0.5
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 

package/lib/core.mjs

@@ -1537,7 +1537,7 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, s
           // Hooks also run through direct core callers (not only bin/oats).
           // Author this from the running kernel, never PATH, ambient env or
           // a caller's extraEnv: those may point at a different executable.
-          OATS_CLI_BIN: realpathSync(join(PKG_ROOT, "bin", "oats.mjs")),
+          OATS_CLI_BIN: kernelBin(),
           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
@@ -2191,6 +2191,53 @@ export function launchEnvRefs(recipe, env = process.env) {
 export function launchEnvTmuxFlags(recipe, env) { return launchEnvRefs(recipe, env).map((r) => ` -e ${shq(`${r.name}=${r.value}`)}`).join(""); }
 export function launchEnvExports(recipe, env) { return launchEnvRefs(recipe, env).map((r) => `export ${r.name}=${shq(r.value)}; `).join(""); }
 
+/** The canonical path of this kernel's CLI: what the home's shim points at, and OATS_CLI_BIN. */
+export function kernelBin() { return realpathSync(join(PKG_ROOT, "bin", "oats.mjs")); }
+/** Where a home's `oats` lives: first on its harness's PATH, so plain `oats` inside an instance is
+ *  the kernel that launched it, whatever other `oats` the host's PATH finds first. */
+export const kernelShimDir = (home) => join(home, ".oats", "bin");
+/** Write <home>/.oats/bin/oats, a symlink to this kernel's CLI, replacing any shim a previous
+ *  launch (perhaps by another kernel) left: built aside, then renamed over. `.oats` and `.oats/bin`
+ *  must be directories of the home itself: a link there would carry the write outside the home.
+ *  The target, or E_LAUNCH_SHIM naming the path and the cause (a launch never runs with the
+ *  wrong `oats`), before anything outside the home is touched. */
+export function writeKernelShim(home) {
+  const dir = kernelShimDir(home), shim = join(dir, "oats");
+  let target, aside;
+  try {
+    target = kernelBin();
+    for (const d of [join(home, ".oats"), dir]) {
+      let st;
+      try { st = lstatSync(d); }
+      catch (e) { if (e.code !== "ENOENT") throw e; mkdirSync(d); st = lstatSync(d); }
+      if (!st.isDirectory()) throw new Error(`${d} is ${st.isSymbolicLink() ? "a symbolic link" : "not a directory"}`);
+    }
+    if (realpathSync(dir) !== join(realpathSync(home), ".oats", "bin")) throw new Error(`${dir} resolves outside the home`);
+    aside = join(dir, `.oats-${randomUUID()}`);
+    symlinkSync(target, aside);
+    renameSync(aside, shim);
+    return target;
+  } catch (e) {
+    if (aside) rmSync(aside, { force: true });
+    throw oatsError("E_LAUNCH_SHIM", `cannot write the kernel shim ${shim}${target ? ` (to ${target})` : ""}: ${e.message}; nothing was started`);
+  }
+}
+/** A parsed launch command's environment prefix with the home's shim directory first on PATH: a
+ *  configuration's PATH (literal or reference) follows it, else the PATH the command runs under. */
+function shimPathPrefix(tokens, binary, home) {
+  const dir = shq(kernelShimDir(home));
+  const prefix = tokens.slice(0, binary);
+  const texts = prefix.map((t) => t.name !== "PATH" ? t.text : t.kind === "env" ? `PATH=${dir}:${shq(t.value)}` : `PATH=${dir}:"$${t.source}"`);
+  if (!prefix.some((t) => t.name === "PATH")) texts.push(`PATH=${dir}:"$PATH"`);
+  return texts;
+}
+/** The persisted launch command as a shell runs it: the same command, with the home's kernel shim
+ *  first on PATH. The persisted bytes never carry it (they stay a shape parseLaunchCommand reads). */
+export function launchShellCommand(command, home) {
+  const { tokens, binary } = parseLaunchCommand(command);
+  return [...shimPathPrefix(tokens, binary, home), ...tokens.slice(binary).map((t) => t.text)].join(" ");
+}
+
 /** The harness command line of a recipe. With no configuration the bytes
  *  equal what spawn rendered before recipes: env prefix, the executable, the
  *  harness's own arguments, capability launch args, the task prompt. A
@@ -2234,14 +2281,15 @@ export function renderLaunchRecipe(recipe, { home, instance, redact = false }) {
 
 /** Execution, not preview: mark pending before dispatch, then resolve native
  * storage inside the backend shell under the actual command environment.
- * The original executable/argv is exec'd unchanged after recording succeeds. */
+ * The original executable/argv is exec'd unchanged after recording succeeds,
+ * with the home's kernel shim first on PATH (every launch runs through here). */
 function nativeRecordCommand(command, home, harness) {
   const { tokens, binary } = parseLaunchCommand(command);
   const args = tokens.slice(binary + 1).filter(t => t.kind !== "prompt").map(t => t.value ?? t.text);
   const id = prepareNativeStart(home, harness);
   const recorder = join(PKG_ROOT, "packages", "record", "bin", "record-native-start.mjs");
   const inner = `${shq(process.execPath)} ${shq(recorder)} ${shq(home)} ${shq(id)} ${shq(harness)} ${shq(JSON.stringify(args))} && exec ${tokens.slice(binary).map(t => t.text).join(" ")}`;
-  return `${tokens.slice(0, binary).map(t => t.text).join(" ")} /bin/sh -c ${shq(inner)}`;
+  return `${shimPathPrefix(tokens, binary, home).join(" ")} /bin/sh -c ${shq(inner)}`;
 }
 
 
@@ -2374,7 +2422,7 @@ export function planLaunch({ home, instance, meta, contextDir, agentLike, select
     version: LAUNCH_RECIPE_VERSION, harness, launchConfig: config?.name || null, launchConfigSource: config?.source || null,
     executable: executable.path || executable.declared || harness, executableDeclared: executable.declared ?? null, executableResolvedFrom: executable.resolvedFrom,
     args: [...(config?.args || [])], env: { ...configEnv }, model: model || null, ...(yolo !== undefined ? { yolo } : {}),
-    hooks: frozen ? { launch: hooks.launch, env: hooks.env, contributions: hooks.contributions } : hooks, prompt: LAUNCH_PROMPT,
+    hooks: frozen ? { launch: hooks.launch, env: hooks.env, contributions: hooks.contributions } : hooks, prompt: LAUNCH_PROMPT, kernelBin: kernelBin(),
     ...(frozen?.legacy ? { legacy: { ...frozen.legacy, ...(hooks.refreshed?.length ? { replacedBy: hooks.refreshed } : {}) } } : {}),
   };
   const inst = instance || meta?.instance || basename(home);
@@ -2412,11 +2460,18 @@ export function redactLaunchCommand(command) {
   try { return parseLaunchCommand(command).tokens.map((t) => t.kind === "env" && !IDENTITY_LAUNCH_ENV.has(t.name) ? `${t.name}='<redacted>'` : t.text).join(" "); }
   catch { return "<unparseable launch command withheld>"; }
 }
-/** The recipe with every environment value withheld. */
+/** The recipe as answers carry it: every environment value withheld, and without `kernelBin`
+ *  (the home's record keeps it; human `oats status` reads it from there). */
 export function redactLaunchRecipe(recipe) {
   const env = Object.fromEntries(Object.keys(recipe.env || {}).sort().map((n) => [n, typeof recipe.env[n] === "string" ? { redacted: true } : { fromEnv: recipe.env[n].fromEnv }]));
   const hooks = recipe.hooks ? { ...recipe.hooks, env: Object.fromEntries(Object.keys(recipe.hooks.env || {}).sort().map((n) => [n, { redacted: true }])) } : undefined;
-  return { ...recipe, env, ...(hooks ? { hooks } : {}) };
+  const { kernelBin: _recorded, ...answered } = recipe;
+  return { ...answered, env, ...(hooks ? { hooks } : {}) };
+}
+/** The kernel a home's last launch pointed its `oats` at (instance.json launch.kernelBin), or null. */
+export function recordedKernelBin(home) {
+  try { const bin = JSON.parse(readFileSync(join(home, "instance.json"), "utf8"))?.launch?.kernelBin; return typeof bin === "string" ? bin : null; }
+  catch { return null; }
 }
 /** Spawn. With `o.prepared` (workspace model: a resolution prepared by
  *  instance-resolution.mjs) this is ASYNC — capabilities are fetched and copied
@@ -2992,7 +3047,7 @@ function* spawnBody(root, agent, o = {}) {
     return e;
   };
   // Workspace model: copy every resolved capability WHOLE into the new home
-  // (.oats/modules/<cap>/ + .agents/skills/<cap>/) and record modules/providers
+  // (.oats/modules/<cap>/, its skills flat in .agents/skills/<skill>/) and record modules/providers
   // in instance.json. Then REBUILD the capability rows against the copies that
   // landed (H1): until now `resolvedCfg.capabilities` were PLANNED rows (no
   // skills, no inject, no dir) — hooks, environment, requirements, retirement
@@ -3034,9 +3089,14 @@ function* spawnBody(root, agent, o = {}) {
         const row = rows.find((c) => c.id === r.module);
         if (r.type === "injection") { r.path = row?.inject; continue; }
         if (r.type === "skill-tree") {
-          const skillsRoot = join(home, ".agents", "skills", r.module);
+          // Module skills land flat in the canonical skills root; the entries are
+          // the names materialize placed for this module (what the resolution
+          // promised), verified against the root in the completeness check.
+          const skillsRoot = join(home, ".agents", "skills");
           r.path = existsSync(skillsRoot) ? skillsRoot : undefined;
-          r.entries = (row?.skills || []).map((p) => basename(p));
+          r.entries = Array.isArray(materializeOutcome?.skills)
+            ? materializeOutcome.skills.filter((s) => s.module === r.module).map((s) => s.name)
+            : (row?.skills || []).map((p) => basename(p));
         }
       }
     } catch (e) { throw rollbackEmptyOrPreparedHome(e); }
@@ -3074,30 +3134,43 @@ function* spawnBody(root, agent, o = {}) {
   }
   if (!existsSync(join(home, "CLAUDE.md"))) symlinkSync("AGENTS.md", join(home, "CLAUDE.md"));
 
-  // Skills: module skills were copied WHOLE into <home>/.agents/skills/<module>/
+  // Skills: module skills were copied WHOLE and FLAT into <home>/.agents/skills/<skill>/
   // by materialize (decision 7/13); here only the soul's own skills join them, one
-  // directory each. There is no override: a soul skill named like a module's
-  // directory is a duplicate (decision 16). The harness is launched with its normal
+  // directory each, at the same level — the one level every harness discovers. There
+  // is no override: a soul skill named like a module's skill is a duplicate (decision 16). The harness is launched with its normal
   // discovery — the machine's and the repo's skills are the harness's business.
   const sources = [];
   const soulSkills = join(soulDir, "skills");
   if (existsSync(soulSkills)) sources.push({ id: "soul", path: soulSkills });
   const chosen = new Map();
+  // Names compare case-insensitively: one directory per skill on a case-insensitive
+  // filesystem (APFS, NTFS) must not silently merge `Foo` into `foo`.
+  const moduleSkillOwner = new Map((materializeOutcome?.skills || []).map((s) => [s.name.toLowerCase(), s.module]));
+  const chosenKeys = new Map();
   const offer = (name, src, source) => {
-    if (chosen.has(name) || existsSync(join(home, ".agents", "skills", name))) throw oatsError("E_SKILL_DUPLICATE", `skill "${name}" from ${source} collides with ${chosen.get(name)?.source ?? `module ${name}'s skill directory`}`);
+    const key = name.toLowerCase();
+    if (chosenKeys.has(key) || moduleSkillOwner.has(key) || existsSync(join(home, ".agents", "skills", name))) {
+      const other = chosenKeys.get(key) ?? (moduleSkillOwner.has(key) ? `module ${moduleSkillOwner.get(key)}'s skill` : `the existing .agents/skills/${name}`);
+      throw oatsError("E_SKILL_DUPLICATE", `skill "${name}" from ${source} collides with ${other}`);
+    }
     chosen.set(name, { src, source });
+    chosenKeys.set(key, source);
   };
-  // Same enumerator preflight used, so "what a tree promises" and "what gets
-  // copied" cannot drift apart.
-  for (const source of sources) for (const entry of skillEntriesIn(source.path)) offer(entry.name, entry.src, source.id);
-  mkdirSync(join(home, ".agents", "skills"), { recursive: true });
-  mkdirSync(join(home, ".claude"), { recursive: true });
-  for (const [name, selected] of [...chosen].sort(([a], [b]) => a.localeCompare(b))) {
-    // Pi's recursive skill scanner does not descend through directory symlinks.
-    // Copy each selected tree so the exact instance-local set is real and immutable.
-    copyTreeSafe(realpathSync(selected.src), join(home, ".agents", "skills", name));
-  }
-  if (!existsSync(join(home, ".claude", "skills"))) symlinkSync(join("..", ".agents", "skills"), join(home, ".claude", "skills"));
+  // A refusal here comes after materialize populated the home: remove it whole,
+  // like every other failure between materialize and the completeness check.
+  try {
+    // Same enumerator preflight used, so "what a tree promises" and "what gets
+    // copied" cannot drift apart.
+    for (const source of sources) for (const entry of skillEntriesIn(source.path)) offer(entry.name, entry.src, source.id);
+    mkdirSync(join(home, ".agents", "skills"), { recursive: true });
+    mkdirSync(join(home, ".claude"), { recursive: true });
+    for (const [name, selected] of [...chosen].sort(([a], [b]) => a.localeCompare(b))) {
+      // Pi's recursive skill scanner does not descend through directory symlinks.
+      // Copy each selected tree so the exact instance-local set is real and immutable.
+      copyTreeSafe(realpathSync(selected.src), join(home, ".agents", "skills", name));
+    }
+    if (!existsSync(join(home, ".claude", "skills"))) symlinkSync(join("..", ".agents", "skills"), join(home, ".claude", "skills"));
+  } catch (e) { throw rollbackEmptyOrPreparedHome(e); }
 
   // EXPECTED == MATERIALIZED. Preflight proved every declared resource resolves;
   // this proves the copies actually landed, so "the composition is complete" is
@@ -3119,18 +3192,14 @@ function* spawnBody(root, agent, o = {}) {
       if (!chosen.has(name)) incomplete.push(`skill "${name}", promised by ${r.source} (${r.declared}), is missing from the composed set`);
     }
   }
-  // Prepared spawn: every module's declared skill must have been copied under
-  // .agents/skills/<module>/<skill>/ by materialize — verify the copies landed
-  // as readable skills (the module directory alone proves nothing).
+  // Prepared spawn: every module's declared skill must have been copied to
+  // .agents/skills/<skill>/ by materialize — verify the copies landed as
+  // readable skills, one level deep, where the harnesses discover them.
   if (o.prepared) {
-    for (const m of o.prepared.resolution.modules) for (const s of m.manifest.skills || []) {
-      const sk = join(home, ".agents", "skills", m.name);
-      if (!existsSync(sk)) { incomplete.push(`module "${m.name}" declares skills but .agents/skills/${m.name} is absent`); break; }
-    }
     for (const r of expectedResources) {
       if (r.deferred !== "materialize" || r.type !== "skill-tree") continue;
-      if (!r.path) { incomplete.push(`module "${r.module}" declares skill tree ${r.declared} but .agents/skills/${r.module} is absent`); continue; }
-      if (!r.entries.length) incomplete.push(`module "${r.module}" declares skill tree ${r.declared} but no skill was copied under .agents/skills/${r.module}`);
+      if (!r.path) { incomplete.push(`module "${r.module}" declares skill tree ${r.declared} but .agents/skills is absent`); continue; }
+      if (!r.entries.length) incomplete.push(`module "${r.module}" declares skill tree ${r.declared} but none of its skills was copied into .agents/skills`);
       for (const name of r.entries) if (!hasSkillDoc(join(r.path, name))) incomplete.push(`skill "${name}" (module ${r.module}) did not materialize as a readable SKILL.md`);
     }
   }
@@ -3463,6 +3532,8 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
     // instance.json beside its rendering, which is executed in the instance's
     // tmux window. Capabilities contributed harness-specific arguments and
     // environment through their spawn hook; both are recorded with provenance.
+    // The home's `oats` is this kernel, launched now or later (--no-launch).
+    const shimTarget = writeKernelShim(home);
     const recipe = {
       version: LAUNCH_RECIPE_VERSION, harness,
       launchConfig: launchConfig?.name || null, launchConfigSource: launchConfig?.source || null,
@@ -3470,12 +3541,12 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
       args: [...(launchConfig?.args || [])], env: { ...(launchConfig?.env || {}) },
       model: model || null, ...(yolo !== undefined ? { yolo } : {}),
       hooks: { launch: { ...hookRes.launch }, env: { ...hookRes.env }, contributions: hookRes.contributions || [] },
-      prompt: LAUNCH_PROMPT,
+      prompt: LAUNCH_PROMPT, kernelBin: shimTarget,
     };
     if (triggerEventFile) recipe.env.OATS_TRIGGER_EVENT_FILE = triggerEventFile;
     const cmdline = renderLaunchRecipe(recipe, { home, instance });
 
-    // Module skills as materialize landed them (.agents/skills/<module>/<skill>/),
+    // Module skills as materialize landed them (flat, .agents/skills/<skill>/),
     // beside the soul's own: per-skill provenance `module:<cap>` (lead decision c3),
     // `from` = the home's module copy the skill was copied from.
     const moduleSkills = (materializeOutcome?.skills || []).map((row) => ({ name: row.name, source: `module:${row.module}`, from: join(home, row.from) }));
@@ -4879,6 +4950,9 @@ export function startInstanceSession(home, o = {}) {
       try { state = inspectSessionTarget(target, o.io); } catch (e) { if (backend === "tmux" && lostTmuxServer(e)) { serverGone = true; state = { present: false, state: "stopped" }; } else throw oatsError("E_SESSION_UNKNOWN", `after the stop, cannot establish the state of ${meta.instance}: ${String(e.stderr ?? e.message ?? "").trim() || e.message}`); }
       if (state.present && state.state !== "shell") throw oatsError("E_SESSION_UNKNOWN", `${meta.instance} read as stopped and then as ${state.state} again; nothing was started`);
     }
+    // The kernel that launches the harness is the one the agent's plain `oats` runs.
+    checkRoots();
+    writeKernelShim(realHome);
     const startedAt = new Date().toISOString();
     const id = randomUUID();
     checkRoots();

package/lib/herdr.mjs

@@ -1,11 +1,12 @@
 /** Herdr 0.8.x/0.9.x host-local backend (explicit protocols 20/22).
- * SSH belongs to the CLI router; protocol selection is never negotiation. */
+ * SSH belongs to the CLI router. A new session records the server's protocol once; a recorded
+ * target is never renegotiated. */
 import { execFileSync, spawn } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
-// Keep the existing legacy/default protocol literal; captured callers select one.
+// The legacy protocol literal; a new session records the protocol its server reports (ensureHerdr).
 export const HERDR_PROTOCOL = 20;
 export const HERDR_SUPPORTED_PROTOCOLS = Object.freeze([20, 22]);
 export const isSupportedHerdrProtocol = (value) => HERDR_SUPPORTED_PROTOCOLS.includes(value);
@@ -21,10 +22,15 @@ export function herdrSocket(session = "oats") {
   return join(process.env.XDG_CONFIG_HOME || join(homedir(), ".config"), "herdr", "sessions", session, "herdr.sock");
 }
 
-export function herdrCommand(target, args, { timeout = 10000, exec = execFileSync } = {}) {
+/** One Herdr CLI call on the target's socket, its stdout as text. */
+function herdrOutput(target, args, { timeout = 10000, exec = execFileSync } = {}) {
   const env = { ...process.env, HERDR_SOCKET_PATH: target.socket };
   delete env.HERDR_SESSION;
-  const output = exec(target.binary || "herdr", args, { env, encoding: "utf8", timeout, maxBuffer: 8 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+  return exec(target.binary || "herdr", args, { env, encoding: "utf8", timeout, maxBuffer: 8 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] });
+}
+
+export function herdrCommand(target, args, io) {
+  const output = herdrOutput(target, args, io);
   // Some successful terminal mutations have no output; reads below require
   // their documented result shape independently.
   if (!output.trim()) return {};
@@ -42,9 +48,20 @@ export function herdrSnapshot(target, io) {
   return snapshot;
 }
 
-export function ensureHerdr({ binary = "herdr", socket, session = "oats" } = {}) {
-  const target = { backend: "herdr", binary, socket: resolve(socket || herdrSocket(session)), protocol: HERDR_PROTOCOL };
-  try { herdrSnapshot(target); return target; }
+/** The target for a NEW session on the server at `socket`: it records the supported protocol that server
+ * reports (Herdr 0.8 speaks 20, 0.9 speaks 22). Every later call checks the snapshot against that recorded
+ * protocol, so a recorded target is never renegotiated. */
+function newSessionTarget(target, io) {
+  const protocol = herdrCommand(target, ["api", "snapshot"], io).snapshot?.protocol;
+  if (!isSupportedHerdrProtocol(protocol)) throw Object.assign(new Error(`Herdr server speaks protocol ${protocol ?? "unknown"}; OATS supports ${HERDR_SUPPORTED_PROTOCOLS.join(" and ")}`), { unsupportedProtocol: true });
+  const selected = { ...target, protocol };
+  herdrSnapshot(selected, io);
+  return selected;
+}
+
+export function ensureHerdr({ binary = "herdr", socket, session = "oats", io } = {}) {
+  const target = { backend: "herdr", binary, socket: resolve(socket || herdrSocket(session)) };
+  try { return newSessionTarget(target, io); }
   catch (e) {
     // An explicit socket belongs to an operator-managed server. Never start a
     // different server when it cannot be inspected or is incompatible.
@@ -59,7 +76,8 @@ export function ensureHerdr({ binary = "herdr", socket, session = "oats" } = {})
   let error;
   for (let i = 0; i < 30; i++) {
     pause(100);
-    try { herdrSnapshot(target); return target; } catch (e) { error = e; }
+    // A server that answers with an unsupported protocol is up: waiting longer cannot change its answer.
+    try { return newSessionTarget(target, io); } catch (e) { if (e.unsupportedProtocol) throw e; error = e; }
   }
   throw new Error(`Herdr did not start: ${error?.message || "no socket"}`);
 }
@@ -81,8 +99,27 @@ export function inspectHerdr(target, io) {
   return { present: !!pane, pane, agent, status: agent?.agent_status || "unknown" };
 }
 
+/** Wait until a new pane's shell has drawn something (its prompt) before typing into it. Text typed
+ * earlier sits in the terminal's canonical line buffer, which drops a line past 1024 bytes on macOS:
+ * a launch command is longer than that, and arrived cut. Bounded; a Herdr that cannot read a pane
+ * leaves the old behaviour (type at once). */
+function awaitShellReady(target, io) {
+  const deadline = Date.now() + (io?.shellReadyMs ?? 10000);
+  for (;;) {
+    let text;
+    // `pane read` answers the screen as plain text, not a JSON envelope.
+    const remaining = Math.max(100, deadline - Date.now());
+    try { text = herdrOutput(target, ["pane", "read", target.paneId, "--source", "visible"], { ...io, timeout: Math.min(2000, remaining) }); }
+    catch { return; }
+    if (typeof text === "string" && text.trim()) return;
+    if (Date.now() >= deadline) return;
+    pause(100);
+  }
+}
+
 export function launchHerdr(target, command, io) {
   if (!inspectHerdr(target, io).present) throw new Error("Herdr launch pane disappeared");
+  awaitShellReady(target, io);
   // This is the allocated shell's one launch command. Exec avoids a fallback
   // shell that could accidentally consume a subsequent agent notification.
   herdrCommand(target, ["pane", "run", target.paneId, `exec /bin/sh -c ${quote(command)}`], io);

package/lib/instance-inspect.mjs

@@ -221,7 +221,7 @@ function capabilityRows(t) {
       return { ...op, argv: [m.command ?? null, op.command], available: !reason, reason };
     });
     // 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.
+    // "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 };
   });

package/lib/instance-resolution.mjs

@@ -5,7 +5,7 @@
  *  its Git remotes in the operator's access context → find the soul among the
  *  confirmed members (or external souls) → resolve every capability by `from:`
  *  (member = latest state, package = the locked version) → materialize
- *  each capability WHOLE into the new home (`.oats/modules/`, `.agents/skills/`) →
+ *  each capability WHOLE into the new home (`.oats/modules/`, skills flat in `.agents/skills/`) →
  *  compose AGENTS.md → launch the harness normally.
  *
  *  This module owns the async half (discover + resolve) and the materialize call;
@@ -24,7 +24,7 @@ import { resolveSoul, kernelCompatibility } from "./resolve.mjs";
 import { BY_TEAM_REMOVED, recordedTeams, reportRows, soulKeyOf, soulTeams, teamModel } from "./teams.mjs";
 import { launchLayers } from "./launch-preference.mjs";
 import { declaredSettings } from "./capability-contract.mjs";
-import { materialize, MODULES_DIR, SKILLS_DIR } from "./materialize.mjs";
+import { materialize, moduleSkills, MODULES_DIR, SKILLS_DIR } from "./materialize.mjs";
 import { fetchRemoteTree } from "./remote.mjs";
 import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, symlinkSync, statSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -524,9 +524,11 @@ export function toCapabilityRows(resolution, home) {
   for (const m of resolution.modules) {
     const dir = join(home, MODULES_DIR, m.name);
     const manifest = m.manifest;
-    const skills = [];
-    const skillsRoot = join(home, SKILLS_DIR, m.name);
-    if (existsSync(skillsRoot)) for (const e of readdirSync(skillsRoot, { withFileTypes: true })) if (e.isDirectory()) skills.push(join(skillsRoot, e.name));
+    // Skills are flat under <home>/.agents/skills/<skill>/; which of them this module
+    // contributed is read from its own copy, enumerated exactly as materialize placed them.
+    const skills = existsSync(dir)
+      ? moduleSkills(resolution, m, dir).map((s) => join(home, SKILLS_DIR, s.name)).filter((p) => existsSync(p))
+      : [];
     const inject = manifest.inject ? join(dir, manifest.inject) : undefined;
     rows.push({
       id: m.name, capability: m.name, manifest, layer: manifest.layer ?? undefined, command: manifest.command,
@@ -564,8 +566,12 @@ function requiredHooksOf(manifest) {
   return Object.entries(hooks).filter(([, s]) => s && typeof s === "object" && s.required === true).map(([e]) => e);
 }
 
-/** What a preview shows about modules: from/commit/digest per module and whether
- *  it changed since the newest existing instance of the same soul in `agentsRoot`. */
+/** What a preview shows about modules: from/commit/digest per module, whether
+ *  it changed since the newest existing instance of the same soul in `agentsRoot`,
+ *  and `composedFrom` (feature preview-composed-from): why the soul's composition
+ *  has it — "soul" | "workspace", the resolution's capabilitiesFrom. Provenance
+ *  only: it is outside every fingerprint. `null` only for a resolution without
+ *  capabilitiesFrom (an older in-process caller); never for a resolved module. */
 export function modulesPreview(resolution, agentsRoot, soulName) {
   let previous = null;
   const instancesDir = join(agentsRoot, soulName, "instances");
@@ -583,7 +589,8 @@ export function modulesPreview(resolution, agentsRoot, soulName) {
   return resolution.modules.map((m) => {
     const prev = previous?.modules?.[m.name];
     const changedSince = !previous ? null : !prev ? { instance: previous.name, was: null } : (prev.commit !== m.from.commit ? { instance: previous.name, was: prev.commit } : false);
-    return { name: m.name, from: m.from, layer: m.manifest.layer ?? null, private: !!m.private, declares: declaredSettings(m.manifest), changedSince };
+    return { name: m.name, from: m.from, layer: m.manifest.layer ?? null, private: !!m.private, declares: declaredSettings(m.manifest), changedSince,
+      composedFrom: resolution.capabilitiesFrom?.[m.name] ?? null };
   });
 }
 

package/lib/materialize.mjs

@@ -6,7 +6,9 @@
  * materialize(resolution, home, options)
  *   For every module of the resolution: fetch its capability directory whole into
  *   <home>/.oats/modules/<name>/, verify the copy's content digest, copy its skills as
- *   FULL copies into <home>/.agents/skills/<name>/<skill>/, compose <home>/AGENTS.md
+ *   FULL copies into <home>/.agents/skills/<skill>/ — FLAT, one level deep, where every
+ *   harness discovers them (Claude Code through .claude/skills/<skill>/); skill names are
+ *   unique across the modules (E_SKILL_DUPLICATE) — compose <home>/AGENTS.md
  *   (soul body + each module's inject, same marker comments as the kernel composer),
  *   keep the CLAUDE.md / .claude/skills aliases, and record modules + providers in
  *   <home>/instance.json.
@@ -16,7 +18,7 @@
  * place. Any failure before the commit removes the staging directory and leaves the home
  * exactly as it was (a `.oats/` directory created only for staging is removed too). The
  * commit re-checks the home's shape (no symlink planted at .oats/.agents/.claude or the
- * module targets during the fetch), then runs a short sequence of renames — modules,
+ * module and skill targets during the fetch), then runs a short sequence of renames — modules,
  * skills, AGENTS.md, instance.json, and the CLAUDE.md / .claude/skills aliases — with a
  * rollback journal: should any step fail, everything already placed is undone and the
  * previous AGENTS.md / instance.json restored before a named error (E_MATERIALIZE_HOME)
@@ -205,7 +207,7 @@ function hasSkillDoc(dir) {
 /** The skills a module contributes → [{ name, path }] (path relative to the module root).
  * Precedence: resolution.skills rows for the module; else manifest.skills; else every
  * skills/<dir>/SKILL.md in the fetched tree. */
-function moduleSkills(resolution, module, moduleDir) {
+export function moduleSkills(resolution, module, moduleDir) {
   const declared = (resolution.skills || []).filter((s) => s && s.module === module.name);
   const rows = [];
   if (declared.length) {
@@ -335,13 +337,22 @@ export async function materialize(resolution, home, options = {}) {
   const parents = [join(homeAbs, ".oats"), modulesRoot, join(homeAbs, ".agents"), skillsRoot, join(homeAbs, ".claude")];
   /** The home must still be what we checked: module targets absent, every parent a real directory (or absent).
    * Run before the fetch AND immediately before the commit — a symlink planted in between must not be written through. */
+  // Skill targets are known only once each module is fetched; the commit-time re-check covers them.
+  // skill name, lower-cased → { module, path, name }: one directory per skill, and on a
+  // case-insensitive filesystem `Foo` and `foo` are one directory.
+  const skillOwners = new Map();
   const assertHomeShape = () => {
     for (const { module } of sources) {
-      for (const target of [join(modulesRoot, module.name), join(skillsRoot, module.name)]) {
-        let st = null;
-        try { st = lstatSync(target); } catch {}
-        if (st) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries module ${module.name}; materialize never overwrites a module in place`, { home: homeAbs, module: module.name, path: target });
-      }
+      const target = join(modulesRoot, module.name);
+      let st = null;
+      try { st = lstatSync(target); } catch {}
+      if (st) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries module ${module.name}; materialize never overwrites a module in place`, { home: homeAbs, module: module.name, path: target });
+    }
+    for (const owner of skillOwners.values()) {
+      const name = owner.name, target = join(skillsRoot, name);
+      let st = null;
+      try { st = lstatSync(target); } catch {}
+      if (st) throw fail("E_MATERIALIZE_HOME", `${target} already exists — the instance already carries a skill named ${name}; materialize never overwrites a skill in place`, { home: homeAbs, module: owner.module, skill: name, path: target });
     }
     for (const p of parents) {
       let st = null;
@@ -378,7 +389,6 @@ export async function materialize(resolution, home, options = {}) {
     mkdirSync(join(staging, "skills"), { recursive: true, mode: 0o755 });
 
     const moduleRows = [], skillRows = [], capabilityBlocks = [], recorded = {};
-    const skillOwners = new Map();
     for (const { module, source } of sources) {
       const stagedModule = join(staging, "modules", module.name);
       const finalModule = join(modulesRoot, module.name);
@@ -412,15 +422,21 @@ export async function materialize(resolution, home, options = {}) {
       }
 
       for (const skill of moduleSkills(resolution, module, stagedModule)) {
-        const owner = skillOwners.get(skill.name);
-        if (owner && owner !== module.name) {
-          throw fail("E_SKILL_DUPLICATE", `skill ${JSON.stringify(skill.name)} is contributed by both ${owner} and ${module.name}`, { name: skill.name, modules: [owner, module.name] });
+        // Skills land flat, so a name is one directory in the home: two sources for one
+        // name — two modules, or two paths of one module — are a duplicate.
+        const key = skill.name.toLowerCase();
+        const owner = skillOwners.get(key);
+        if (owner && owner.module === module.name && owner.path === skill.path && owner.name === skill.name) continue;
+        if (owner) {
+          const detail = owner.module === module.name ? `${module.name} (${owner.path} and ${skill.path})` : `both ${owner.module} and ${module.name}`;
+          const names = owner.name === skill.name ? JSON.stringify(skill.name) : `${JSON.stringify(owner.name)} / ${JSON.stringify(skill.name)} (one directory on a case-insensitive filesystem)`;
+          throw fail("E_SKILL_DUPLICATE", `skill ${names} is contributed by ${detail}`, { name: skill.name, modules: [owner.module, module.name] });
         }
-        skillOwners.set(skill.name, module.name);
+        skillOwners.set(key, { module: module.name, path: skill.path, name: skill.name });
         const src = join(stagedModule, ...skill.path.split("/"));
-        const staged = join(staging, "skills", module.name, skill.name);
+        const staged = join(staging, "skills", skill.name);
         copyTree(src, staged, `${module.name}/${skill.path}`);
-        skillRows.push({ module: module.name, name: skill.name, from: `${MODULES_DIR}/${module.name}/${skill.path}`.split(sep).join("/"), path: join(skillsRoot, module.name, skill.name) });
+        skillRows.push({ module: module.name, name: skill.name, from: `${MODULES_DIR}/${module.name}/${skill.path}`.split(sep).join("/"), path: join(skillsRoot, skill.name) });
       }
 
       for (const rel of moduleInjects(resolution, module, stagedModule)) {
@@ -478,10 +494,8 @@ export async function materialize(resolution, home, options = {}) {
     };
     try {
       for (const p of [join(homeAbs, ".oats"), modulesRoot, join(homeAbs, ".agents"), skillsRoot, join(homeAbs, ".claude")]) mkdirTracked(p);
-      for (const { module } of sources) {
-        placeDir(join(staging, "modules", module.name), join(modulesRoot, module.name));
-        if (existsSync(join(staging, "skills", module.name))) placeDir(join(staging, "skills", module.name), join(skillsRoot, module.name));
-      }
+      for (const { module } of sources) placeDir(join(staging, "modules", module.name), join(modulesRoot, module.name));
+      for (const row of skillRows) placeDir(join(staging, "skills", row.name), row.path);
       swapIn(join(staging, "AGENTS.md"), join(homeAbs, "AGENTS.md"), "AGENTS.md");
       swapIn(join(staging, "instance.json"), instanceFile, "instance.json");
       // Aliases (relative symlinks), only when absent — the canonical-plus-alias construction stays; inside the transaction.

package/package-catalog.json

@@ -33,7 +33,7 @@
     },
     "oats.framework": {
       "url": "https://github.com/awebai/oats.git",
-      "ref": "oats-framework/v1.4.0",
+      "ref": "oats-framework/v1.4.1",
       "path": "oats-package"
     }
   },

package/package.json

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

package/skills/oats-getting-started/SKILL.md

@@ -60,7 +60,7 @@ members:
   - git:github.com/acme/agents          # the host is a member too
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.4.0                # bare versions resolve through the official catalog
+  oats.framework: v1.4.1                # bare versions resolve through the official catalog
   oats.okf: v4.0.5
 defaults:
   capabilities: { oats.core: { from: package } }