@awebai/oats 0.44.1 → 0.46.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/bin/oats.mjs CHANGED
@@ -36,6 +36,7 @@ import {
36
36
  import {
37
37
  writeFileAtomic, LOCK_FILE, canonicalLock, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
38
38
  classifyPackageValue, parsePackageRequest } from "../lib/packages.mjs";
39
+ import { harnessTrust } from "../lib/harness-trust-write.mjs";
39
40
  import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
40
41
  import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
41
42
  import { launchLayers } from "../lib/launch-preference.mjs";
@@ -55,12 +56,12 @@ import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
55
56
  import { planStop, applyStop, planRetire, resolveInstance as resolveInstanceForCli } from "../lib/instance-lifecycle.mjs";
56
57
  import { extraWorktreeLines, formatBytes, workRecoveryLines } from "../lib/retire-output.mjs";
57
58
  const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
58
- import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
59
+ import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
59
60
  import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
60
61
 
61
62
  const rawArgs = process.argv.slice(2);
62
63
  /** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
63
- const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "install-oats", "json", "keep-dir", "keep-env", "no-child-spawns", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
64
+ const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "self", "verbose", "yes", "yolo"]);
64
65
  /** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
65
66
  * routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
66
67
  * `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
@@ -89,7 +90,7 @@ function expandInlineValues(argv) {
89
90
  const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
90
91
  let cmd = args[0];
91
92
  const HELP_WORDS = new Set(["help", "--help", "-h"]);
92
- const KERNEL_COMMANDS = new Set(["automations", "trigger", "capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "update", "version", "workspace"]);
93
+ const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "update", "version", "workspace"]);
93
94
  /** Commands whose argv another parser reads (packages/record and packages/experimental parse process.argv). */
94
95
  const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental"]);
95
96
  /** Commands `--server <id>` runs on a registered server. */
@@ -195,14 +196,16 @@ function operationalKnowledgeNote(composition, soulName) {
195
196
  ? `soul ${soulName} has no oats.core capability (the workspace default); it gets no OATS operating instructions` : null;
196
197
  }
197
198
  /** `doctor --soul`: the instructions an instance of that soul would carry. The soul
198
- * is resolved over the workspace remotes exactly as a spawn preview resolves it,
199
- * the kernel half composed, and the modules materialized into a scratch home
200
- * OUTSIDE the deployment (removed after), so module injects are part of the text.
201
- * Nothing in the deployment is written. Block files of module injects are named
202
- * home-relative (`.oats/modules/<cap>/<inject>`), where an instance carries them. */
199
+ * is resolved over the workspace remotes exactly as a spawn preview resolves it
200
+ * (previewWorkspaceSoul: the soul cache is not written), then composed by the one
201
+ * composer spawn's path, doctor and inspect share (lib/soul-composition.mjs): kernel
202
+ * half, then the modules materialized into a scratch home OUTSIDE the deployment
203
+ * (removed after). Capability blocks are named home-relative
204
+ * (`.oats/modules/<cap>/<inject>`), where an instance carries them. */
203
205
  async function doctorComposition(ctx, soulName, ws, bail) {
204
206
  if (!soulName) return undefined;
205
- const { prepareInstance, previewWorkspaceSoul, materializePrepared, discoverOrStandalone, agentDirOf } = await import("../lib/instance-resolution.mjs");
207
+ const { prepareInstance, previewWorkspaceSoul, discoverOrStandalone } = await import("../lib/instance-resolution.mjs");
208
+ const { composeSoulInstructions } = await import("../lib/soul-composition.mjs");
206
209
  const deployment = dirname(ws.local.path);
207
210
  const root = join(deployment, "agents");
208
211
  const remoteOptions = remoteOptionsFromEnv();
@@ -214,24 +217,8 @@ async function doctorComposition(ctx, soulName, ws, bail) {
214
217
  const prepared = await prepareInstance(deployment, soulName, { remoteOptions, discovery });
215
218
  const pv = await previewWorkspaceSoul(prepared, root);
216
219
  cleanups.push(pv.cleanup);
217
- const agent = findAgentAt(root, agentDirOf(prepared.soulEntry), pv.soulDir);
218
- if (!agent) bail("E_SOUL_UNKNOWN", `soul "${soulName}" was fetched but is not readable as a soul`);
219
- const composition = composeInstanceAgentsMd(pv.soulDir, deployment, agent.name, agent.work || "checkout", agent.kind, prepared);
220
- const scratch = realpathSync(mkdtempSync(join(tmpdir(), "oats-doctor-home-")));
221
- cleanups.push(() => rmSync(scratch, { recursive: true, force: true }));
222
- const outcome = await materializePrepared({ ...prepared, soulAgentsMd: composition.text, soulDir: pv.soulDir }, scratch);
223
- const text = readFileSync(join(scratch, "AGENTS.md"), "utf8");
224
- const known = new Set(composition.blocks.map((b) => b.source));
225
- const outcomeBlocks = Array.isArray(outcome?.blocks) ? outcome.blocks : [];
226
- for (const m of text.matchAll(/^<!-- oats:(capability:[^\s]+) src=(.+?) -->$/gm)) {
227
- const [, source, file] = m;
228
- if (known.has(source)) continue;
229
- known.add(source);
230
- const content = outcomeBlocks.find((b) => b.source === source && b.file === file)?.content ?? (existsSync(file) ? readFileSync(file, "utf8").trim() : "");
231
- const rel = file.startsWith(scratch + sep) ? file.slice(scratch.length + 1) : file;
232
- composition.blocks.push({ source, file: rel, content, materialized: true });
233
- }
234
- return { ...composition, text };
220
+ const { text, blocks, resolved, oatsCoreDeclared } = await composeSoulInstructions({ deployment, prepared, soulDir: pv.soulDir });
221
+ return { text, blocks, resolved, oatsCoreDeclared };
235
222
  } catch (e) {
236
223
  if (e?.code?.startsWith?.("E_")) bail(e.code, e.message, e.details);
237
224
  throw e;
@@ -431,9 +418,13 @@ function soulEntry(soul, root, { capability } = {}) {
431
418
  function dropAmbientRoot() { delete process.env.PI_AGENTS_ROOT; }
432
419
  async function inspectCmd() {
433
420
  const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
434
- const t = await workspaceTarget(bail, { command: "inspect" });
421
+ // Feature soul-composed-instructions: opt-in, soul subject only; without it nothing extra is composed.
422
+ const instructions = args.includes("--instructions");
423
+ if (instructions && flag("home") !== undefined) return bail("E_BAD_ARGS", "--instructions composes a soul's instructions before a spawn: it takes --soul, not --home (an instance's composed AGENTS.md is instance.instructions)");
424
+ let t = await workspaceTarget(bail, { command: "inspect" });
435
425
  if (t) {
436
426
  if (t.resolutionError) return bail(t.resolutionError.code, t.resolutionError.message, t.resolutionError.details ?? undefined);
427
+ if (instructions) t = await withComposedInstructions(t);
437
428
  const doc = inspectDocument(t, { kernel: OATS_VERSION });
438
429
  if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
439
430
  printWorkspaceInspect(doc); return;
@@ -482,6 +473,8 @@ function printWorkspaceInspect(doc) {
482
473
  for (const l of LAYERS) console.log(` ${l} capability: ${doc.layers[l].id || "none"}`);
483
474
  for (const c of doc.capabilities) console.log(` ${c.id}@${c.version || "?"} ${c.from?.kind === "package" ? `package ${c.from.package}` : c.from?.kind === "member" ? `member ${c.from.repoKey}` : ""}${c.operations.length ? ` ops: ${c.operations.map((o) => `${o.name}${o.available ? "" : "(unavailable)"}`).join(", ")}` : ""}`);
484
475
  for (const p of doc.problems) console.log(` ! ${p.code}: ${p.message}`);
476
+ const composed = doc.souls[0].composedInstructions;
477
+ if (composed !== undefined) console.log(composed ? `\nComposed AGENTS.md (a spawn here, resolution ${composed.resolution ?? "?"}${composed.truncated ? ", truncated" : ""}):\n\n${composed.text}` : "\nComposed AGENTS.md: unavailable (see the problems above)");
485
478
  }
486
479
 
487
480
  /** `{ teams, defaultTeam, teamsSource }` for a session start of a workspace home: its teams read
@@ -1230,6 +1223,38 @@ function workspaceContext(bail) {
1230
1223
  return { dir, localPath: found.path, local: found.local, deploymentDir: dirname(found.path), remoteOptions: remoteOptionsFromEnv() };
1231
1224
  }
1232
1225
 
1226
+ /** An explicit host-local operator action; never routed to a remote adapter. */
1227
+ function harnessTrustCmd() {
1228
+ if (args[1] !== "trust") return cmdFail("E_BAD_ARGS", "usage: oats harness trust [--dir <deployment>] [--harness claude|codex|all] [--plan] [--json]");
1229
+ const seen = new Set();
1230
+ for (let i = 2; i < args.length; i++) {
1231
+ const arg = args[i];
1232
+ if (seen.has(arg)) return cmdFail("E_BAD_ARGS", `duplicate argument ${arg}`);
1233
+ seen.add(arg);
1234
+ if (["--plan", "--json"].includes(arg)) continue;
1235
+ if (["--dir", "--harness"].includes(arg) && args[i + 1] && !args[i + 1].startsWith("-")) { i++; continue; }
1236
+ return cmdFail("E_BAD_ARGS", `unsupported argument ${arg}; use oats harness trust --help`);
1237
+ }
1238
+ const selected = flag("harness") ?? "all";
1239
+ if (!["claude", "codex", "all"].includes(selected)) return cmdFail("E_BAD_ARGS", "--harness must be claude, codex, or all");
1240
+ const context = workspaceContext(cmdFail);
1241
+ const show = (result, log = console.log) => {
1242
+ log(`${result.mode}: native harness trust for ${result.root}`);
1243
+ for (const entry of result.entries) log(`${entry.harness}: ${entry.status} ${entry.file ?? "unresolved file"} ${JSON.stringify(entry.key)} ${JSON.stringify(entry.current)} -> ${JSON.stringify(entry.desired)} (${entry.beforeDigest ?? "missing"} -> ${entry.afterDigest ?? "unknown/absent"})`);
1244
+ if (result.audit) log(`audit: ${result.audit.status} ${result.audit.path} ${result.audit.operationId}`);
1245
+ for (const warning of result.warnings) log(`warning: ${warning}`);
1246
+ if (result.reason) log(`reason: ${result.reason}; native configuration may have changed: ${result.mayHaveChanged}`);
1247
+ };
1248
+ try {
1249
+ const result = harnessTrust(context.deploymentDir, { harness: selected, plan: args.includes("--plan") });
1250
+ if (JSON_MODE) jsonOk(result);
1251
+ else show(result);
1252
+ } catch (e) {
1253
+ if (!JSON_MODE && e.details?.operation === "harness-trust") show(e.details, console.error);
1254
+ cmdFail(e.code || "E_CONFIG_BROKEN", e.message, e.details);
1255
+ }
1256
+ }
1257
+
1233
1258
  /** The official catalog's package map (package-catalog.json; OATS_PACKAGE_CATALOG overrides). */
1234
1259
  function catalogForSync(bail) {
1235
1260
  try { return officialPackageCatalog(); }
@@ -1971,7 +1996,8 @@ async function capabilityFacts(rows, discovery, lock, ctx, remote = remoteModule
1971
1996
  }
1972
1997
 
1973
1998
  /** Souls rows' spawnability (feature desktop-facts): the refusal a spawn of each would meet, computed from
1974
- * discovery and the lock without spawning (soulSpawnability). */
1999
+ * discovery and the lock without spawning (soulSpawnability), and what the same resolution composes
2000
+ * (`capabilities`, feature souls-capabilities; null when not spawnable). */
1975
2001
  async function soulFacts(rows, discovery, lock, ctx, remote = remoteModule) {
1976
2002
  const { soulSpawnability } = await import("../lib/instance-resolution.mjs");
1977
2003
  // Indexes built once, each keeping the FIRST match as `find` did (a scan per row was O(souls × members)).
@@ -1984,7 +2010,7 @@ async function soulFacts(rows, discovery, lock, ctx, remote = remoteModule) {
1984
2010
  for (const row of rows) {
1985
2011
  const entry = entryOf(row);
1986
2012
  row.file = { path: `${row.path}/soul.yaml`, url: remoteModule.browseUrl(row.repoKey, row.commit, `${row.path}/soul.yaml`) };
1987
- Object.assign(row, entry ? await soulSpawnability(ctx.local, discovery, lock, entry, { remoteOptions: ctx.remoteOptions, remote }) : { spawnable: false, problem: { code: "E_SOUL_UNKNOWN", message: `${row.name} is not in this discovery` } });
2013
+ Object.assign(row, entry ? await soulSpawnability(ctx.local, discovery, lock, entry, { remoteOptions: ctx.remoteOptions, remote }) : { spawnable: false, problem: { code: "E_SOUL_UNKNOWN", message: `${row.name} is not in this discovery` }, capabilities: null });
1988
2014
  }
1989
2015
  }
1990
2016
 
@@ -3388,7 +3414,7 @@ function versionCmd() {
3388
3414
  // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
3389
3415
  // runs on resolve/materialize (contract §6); a feature the binary does not implement is
3390
3416
  // never listed.
3391
- console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "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-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions"], 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, capabilityShowApi: 1 }));
3417
+ console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "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-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions"], 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, capabilityShowApi: 1 }));
3392
3418
  return;
3393
3419
  }
3394
3420
  console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3935,6 +3961,7 @@ else if (cmd === "update") {
3935
3961
  if (t || flag("to") !== undefined) { cmdFail("E_BAD_ARGS", "oats update takes no package: pin package versions in oats-workspace.yaml (`oats package add <id> <version>`), then `oats sync`; bare `oats update [--check] [--yes]` updates the kernel"); process.exit(1); }
3936
3962
  updateCmd();
3937
3963
  }
3964
+ else if (cmd === "harness") harnessTrustCmd();
3938
3965
  else if (cmd === "readiness") await readinessCmd();
3939
3966
  else if (cmd === "instance") instanceCmd();
3940
3967
  else if (cmd === "root") console.log(resolve(new URL("..", import.meta.url).pathname));
@@ -4131,17 +4158,21 @@ Usage:
4131
4158
  a detached external retirement runs
4132
4159
  oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
4133
4160
  [--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
4134
- [--max-age <s>] [--json] installed capabilities with health, effective
4135
- layer bindings and activation, declared
4161
+ [--instructions] [--max-age <s>] installed capabilities with health, effective
4162
+ [--json] layer bindings and activation, declared
4136
4163
  operations with availability; --home answers the
4137
4164
  running home's recorded modules and their drift
4138
- from the deployment
4165
+ from the deployment; --instructions (--soul only)
4166
+ adds the AGENTS.md a spawn of the soul here would write
4139
4167
  oats operation run <layer>:<name> run an operation the soul's core capability for that
4140
4168
  (--home <abs> | --soul <name> [--dir <d>]) layer declares (knowledge:harvest, knowledge:
4141
4169
  [--arg k=v ...] [--json] inspect ...): resolved from the home's recorded
4142
4170
  modules or the deployment's soul, trust checked, the provider's
4143
4171
  own command run in the home or scope, envelope
4144
4172
  relayed; a view answers {documents: [...]}
4173
+ oats harness trust [--dir <deployment>] explicitly trust one canonical deployment root
4174
+ [--harness claude|codex|all] in native host configuration; --plan reads only,
4175
+ [--plan] [--json] bare command applies with a durable audit
4145
4176
  oats launch-config list [--dir <scope> named launch configurations effective at a scope,
4146
4177
  | --home <abs> | --soul <name>] a home's recorded context or a soul's own scope:
4147
4178
  [--agents-root <abs>] [--json] harness, executable, args, env (values redacted,
@@ -93,8 +93,8 @@ launchPromptAnswers:
93
93
 
94
94
  `awebDevelopmentChannel` is a strict boolean; absent means `false`. Unknown keys
95
95
  are refused. `workspaceTrust` is unsupported: remove it and handle folder trust
96
- with the harness. Folder-trust automation is separate work in
97
- [oats#712](https://github.com/awebai/oats/issues/712); it is not enabled here.
96
+ through the explicit [native trust command](harness-trust.md). Launch prompt
97
+ consent does not authorize a native trust write.
98
98
  Each home key is an exact absolute canonical path, with no symlink alias,
99
99
  wildcard, dot segment, trailing separator, ancestor inheritance or soul-wide
100
100
  default. A home not yet created uses its resolved existing directory ancestor
@@ -124,7 +124,13 @@ A qualified normal-output boundary closes observation without asserting readines
124
124
  **Qualified completion and limitation:** exact captured banners cover Claude
125
125
  2.1.289 on darwin-arm64 at 110x35 with aweb-channel 1.7.11 installed, and the
126
126
  original plugin-absent banner. Both name Opus 5.5, API Usage Billing, auto mode
127
- and medium effort. Only the bounded canonical-home directory line may vary.
127
+ and medium effort. Source-derived synthetic variants additionally allow exactly
128
+ `Claude Max`, `Claude Pro`, `Claude Team` or `Claude Enterprise` in place of
129
+ `API Usage Billing`; these are not observed subscription captures. Claude may
130
+ prefer an account-specific plan display name over those fallback labels; other
131
+ display names remain unqualified even for subscribers on those plans. Every other
132
+ row stays exact apart from the bounded canonical-home directory line. This
133
+ interim extension does not cover task-filled screens or bypass-permissions mode.
128
134
  Other model, billing, effort or permission banners remain unqualified: the one
129
135
  Enter can be submitted before `E_SPAWN_INCOMPLETE` with
130
136
  `launchPrompts.status: blocked`. The submitted answer remains in `answers` and
@@ -38,8 +38,9 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
38
38
  "instance-events-2","schedule-history","schedule-read-2","spawn-preview-2","spawn-idempotency","spawn-idempotency-2","spawn-apply-2",
39
39
  "workspace-v2","instance-modules","spawn-provider-payload","served-identity","packages-no-approval","spawn-name","settings-origins",
40
40
  "team-model-3","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
41
- "preview-composed-from","observe-max-age","spawn-preview-max-age","capability-show","capture-file","workspace-identity",
42
- "server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you"],
41
+ "preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
42
+ "workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
43
+ "automation-descriptions","souls-capabilities","soul-composed-instructions"],
43
44
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
44
45
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
45
46
  "capabilityShowApi":1}
@@ -109,6 +110,8 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
109
110
  | `operator-default-soul` | a capability command from a deployment without `--soul` runs as the first soul that provides its namespace (named on stderr); none is `E_BAD_ARGS`, OATS 0.39.0 ([capabilities.md](capabilities.md)) | |
110
111
  | `waiting-on-you` | the `waiting` event kind and the session boundary rule; `oats instance waiting` and `oats instance attention`; `waitingOnYou` (with `message`) on `oats status --json` instance rows, on `oats session inspect --json` and in the events read, OATS 0.40.0 ([Waiting on you](#waiting-on-you)) | `eventsApi: 2` |
111
112
  | `automation-descriptions` | a `description` on every trigger and schedule row, local or workspace, by one rule; `oats schedule update <id> --description=<text>` (the description only) and `oats trigger update <id> --description=<text>`; `--description=<text>` on `schedule add` and `trigger add`, OATS 0.43.0 ([Shared row fields](#automations-shared-rows)) | |
113
+ | `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
114
+ | `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
112
115
 
113
116
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
114
117
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -321,7 +324,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
321
324
  ### `oats inspect`
322
325
 
323
326
  ```text
324
- oats inspect (--home <abs> | --soul <name> [--dir <d>]) [--max-age <s>] --json
327
+ oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions]) [--max-age <s>] --json
325
328
  ```
326
329
 
327
330
  An instance subject, abridged:
@@ -376,6 +379,35 @@ capabilities}`, each the soul.yaml section as written or `null`.
376
379
  `null` before a spawn has copied the soul. `declarationProblems` holds
377
380
  `soul-declarations-unreadable` when soul.yaml does not parse.
378
381
 
382
+ `composedInstructions` (feature `soul-composed-instructions`) is present only
383
+ with `--instructions`, which takes a soul subject (`--home` is `E_BAD_ARGS`);
384
+ without the flag the key is absent and nothing extra is composed. It is the
385
+ AGENTS.md a spawn of this soul here with no flags would write, produced by
386
+ spawn's own composition — the kernel blocks, then each capability's inject,
387
+ materialized into a scratch home outside the deployment and removed. It is
388
+ `{file: null, text, truncated, resolution, body, sources}`. `text` and
389
+ `truncated` follow the 200,000-character cap of `instructions`; `resolution` is
390
+ the resolution revision it was composed at. `body` is the soul's own AGENTS.md,
391
+ `{start, end, truncated}`, and `body.start` is always 0. `sources` lists each
392
+ block in text order like `instance.instructions.sources`, as `{source, file,
393
+ start, end, truncated}`: `source` is the marker's (`kernel:instance-boundary`,
394
+ `work-mode:<mode>`, `capability:<id>`). `file` is home-relative by design here
395
+ — `.oats/modules/<id>/<inject>` for a capability, `null` for a kernel block —
396
+ while `instance.instructions.sources[].file` is a host path: same key,
397
+ different base. Ranges are `[start, end)` into `text` in JavaScript string
398
+ units; `sources` is contiguous with `body` and with each other, with no
399
+ overlaps (each part ends after the blank line that separates it from the
400
+ next). A block's range includes its opening and closing marker lines. Ranges
401
+ are clamped to `text`: a part cut by the cap has `truncated: true` and may lack
402
+ its closing marker, and one wholly past the cap has `start == end ==
403
+ text.length`. The text equals what the spawn writes except that capability
404
+ markers' `src=` is home-relative. It is `null` when the soul resolves but
405
+ cannot be composed here, with the kernel's code and sentence, naming
406
+ `composedInstructions`, in `problems[]`. Routed with `--server <id>`, the flag
407
+ travels to the host; a host whose probe does not advertise
408
+ `soul-composed-instructions` is refused with `E_REMOTE_INCOMPATIBLE`, and
409
+ nothing is sent.
410
+
379
411
  **Layers.** `id` is the capability filling the slot or `null`. `from`
380
412
  (feature `layers-from`) is `"soul"` or `"workspace"`, `null` for an empty slot
381
413
  or a home spawned before it was recorded.
@@ -826,12 +858,14 @@ packages' capabilities and souls, sorted by name, then origin. Both carry
826
858
  "teams":[{"label":"mine","team":"mine:ana.aweb.ai","default":true,"from":"local"},{"label":"global","team":null,"default":false,"from":"shared"}],
827
859
  "defaultTeam":{"label":"mine","team":"mine:ana.aweb.ai","from":"deployment"},
828
860
  "private":false,"path":"souls/writer","work":"directory","description":"Drafts campaigns.","harness":"pi","model":null,"harnessFrom":"kernel-default",
829
- "file":{"path":"souls/writer/soul.yaml","url":null},"spawnable":true,"problem":null},
861
+ "file":{"path":"souls/writer/soul.yaml","url":null},"spawnable":true,"problem":null,
862
+ "capabilities":[{"name":"oats.aweb","kind":"package","package":"oats.aweb","from":"workspace"}]},
830
863
  {"name":"knowledge-maintainer","qualifiedName":"oats.okf/knowledge-maintainer","origin":"package oats.okf v4.1.1","kind":"package","package":"oats.okf",
831
864
  "version":"4.1.1","repoKey":"github.com/awebai/oats-okf","commit":"e1d604f7…","teams":null,"defaultTeam":null,"private":false,
832
865
  "path":"oats-package/souls/knowledge-maintainer","work":"directory","description":"Reviews harvested knowledge.","harness":"pi","model":null,
833
866
  "harnessFrom":"kernel-default","file":{"path":"oats-package/souls/knowledge-maintainer/soul.yaml","url":null},
834
- "spawnable":false,"problem":{"code":"E_TEAM_UNKNOWN","message":"team \"reviewers\" is not declared (oats-local.yaml#/defaultTeam): …"}}],
867
+ "spawnable":false,"problem":{"code":"E_TEAM_UNKNOWN","message":"team \"reviewers\" is not declared (oats-local.yaml#/defaultTeam): …"},
868
+ "capabilities":null}],
835
869
  "problems":[]}
836
870
  ```
837
871
 
@@ -846,7 +880,8 @@ are absent until `sync`.
846
880
  **Soul rows:** `name, origin, kind (member | external | package), repoKey,
847
881
  commit, teams, defaultTeam, private (always false), path, work, description`,
848
882
  plus the Desktop facts `harness, model, harnessFrom, file, spawnable,
849
- problem`, and (feature `launch-preference`) `key` and `launch`.
883
+ problem`, (feature `souls-capabilities`) `capabilities`, and (feature
884
+ `launch-preference`) `key` and `launch`.
850
885
  - `key` is the soul key that `souls.launch` uses, and that
851
886
  `oats soul teams <key>` takes: `qualifiedName` for a package
852
887
  soul, the bare `name` for a member or external soul. Two member souls that
@@ -857,6 +892,16 @@ problem`, and (feature `launch-preference`) `key` and `launch`.
857
892
  [TeamRow](#the-team-row-teamrow) list and a
858
893
  [DefaultTeam](#the-default-defaultteam); both `null` when the soul's teams
859
894
  do not resolve (`problem` names the `E_TEAM_*` code).
895
+ - `capabilities` (feature `souls-capabilities`, OATS 0.45.0): what the soul's
896
+ resolution composes, slots and additive alike, sorted by `name`. Each entry
897
+ names its capability with the capability row's own keys: `name`, `kind`
898
+ (`member` | `package`), then `repoKey` for a member or `package` for a
899
+ package, so it matches exactly one `oats capabilities` row. `from` is why
900
+ the soul has it: `soul` (it declares it) or `workspace` (a workspace
901
+ default), as in inspect's `layers.<slot>.from`. A capability the soul
902
+ turned off (`off`, or `<slot>: none` over a workspace default) is not
903
+ listed. `null` whenever `spawnable` is false (`problem` names why),
904
+ including a soul disabled on this machine; never `[]` for unknown.
860
905
  - Package souls (feature `package-souls`) add `qualifiedName`
861
906
  (`<package>/<soul>`), `package` and `version`. Spawn one by
862
907
  `qualifiedName` (the bare name when unique). Its instances live under
@@ -1353,8 +1398,9 @@ offers **covers** it when all of these hold on this machine:
1353
1398
  - it is not in `souls.disabled`;
1354
1399
  - it resolves as a spawn would;
1355
1400
  - its modules include `oats.setup`;
1356
- - it empties no layer slot the workspace fills, so it keeps the workspace's
1357
- core, messaging and knowledge.
1401
+ - it does not empty the messaging slot the workspace fills (`messaging:
1402
+ none`), so it stays reachable. Emptying `knowledge` or `tasks` does not
1403
+ disqualify it (0.45.0).
1358
1404
 
1359
1405
  It covers a team when that team is among its resolved teams. Detection is by
1360
1406
  composition only: a soul's name never counts, and there is no role marker. An
@@ -1388,8 +1434,8 @@ relevant, each as `{soul, code}`:
1388
1434
  - a soul whose `soul.yaml` names `oats.setup` but that is disabled
1389
1435
  (`E_SOUL_DISABLED`), ambiguous (`E_SOUL_AMBIGUOUS`) or refused (the
1390
1436
  resolution's code);
1391
- - a soul that composes `oats.setup` but empties a slot the workspace fills
1392
- (`slot-none`, with `slots`).
1437
+ - a soul that composes `oats.setup` but empties the messaging slot the
1438
+ workspace fills (`slot-none`, with `slots: ["messaging"]`).
1393
1439
 
1394
1440
  Coverage that holds adds no item.
1395
1441
 
@@ -1581,7 +1627,8 @@ Same-key spawn replay cannot convert a blocked outcome to successful spawn.
1581
1627
 
1582
1628
  `answers` can contain a `submitted` answer even when the final status is
1583
1629
  `blocked`: the accepted installed-plugin and plugin-absent completion banners
1584
- pin specific model/billing/effort/permission text. A different normal-looking banner can block after Enter
1630
+ pin specific model/effort/permission text and finite billing labels, including
1631
+ source-derived Max/Pro/Team/Enterprise variants of the empty API frame. A different normal-looking banner can block after Enter
1585
1632
  while the actual pane is active. Consumers must preserve that submitted receipt
1586
1633
  and never translate this outcome into “nothing started” or automatic retry.
1587
1634
  The [completion limitation](configuration.md#exact-home-launch-prompt-consent)
@@ -3263,3 +3310,47 @@ One warning per command, however many old spellings it read:
3263
3310
 
3264
3311
  The `--server` routes translate for a host without the `harness` feature:
3265
3312
  they send `--runtime` and `runtime` keys and read its `runtimes` list.
3313
+
3314
+ ### `harness trust`
3315
+
3316
+ `oats harness trust [--dir <deployment>] [--harness claude|codex|all] [--plan] [--json]`
3317
+ is host-local. Bare applies; `--apply`, remote selectors, unsupported harnesses,
3318
+ unknown flags and extra positionals are `E_BAD_ARGS`. Default harness is `all`.
3319
+ It uses the existing success/error JSON envelope. Result:
3320
+
3321
+ ```json
3322
+ {
3323
+ "operation": "harness-trust",
3324
+ "mode": "plan",
3325
+ "root": "/canonical/deployment",
3326
+ "entries": [{
3327
+ "harness": "claude", "file": "/native/.claude.json",
3328
+ "key": ["projects", "/canonical/deployment", "hasTrustDialogAccepted"],
3329
+ "current": null, "desired": true,
3330
+ "beforeDigest": null, "afterDigest": "sha256-hex", "status": "change"
3331
+ }],
3332
+ "audit": null,
3333
+ "warnings": []
3334
+ }
3335
+ ```
3336
+
3337
+ Entry statuses are `change|unchanged|refused|applied|failed|incomplete|not-attempted`.
3338
+ `current` contains only the known trust scalar, or null when missing. Codex's key
3339
+ ends in `trust_level` and its desired value is `trusted`. Digests are raw-byte
3340
+ SHA256 hex; missing files have null beforeDigest. Plan and unattempted entries
3341
+ carry the candidate afterDigest. Failed/incomplete attempted entries carry the
3342
+ last observed digest, or null for an absent/unverifiable file (a warning marks
3343
+ unverifiable observations). The intent retains the candidate digest. Apply's audit is
3344
+ `{path,operationId,status:"recorded"|"incomplete"}`. Override provenance is conveyed
3345
+ in warnings, without native configuration contents.
3346
+
3347
+ Preflight failures use `E_CONFIG_BROKEN` with the result in details. Apply failures
3348
+ use `E_HARNESS_TRUST_INCOMPLETE`, details `{...result,reason,mayHaveChanged}`;
3349
+ reason is the closed set `locked|changed|audit|write|verify`. Partial writes are
3350
+ retained. No existing instance-event envelope or lifecycle DTO changes.
3351
+
3352
+ Audit JSONL rows have `version: 1`, `kind: "harness-trust"`, ISO `at`,
3353
+ `operationId`, `phase: "intent"|"outcome"`, harness, root, file, beforeDigest,
3354
+ afterDigest and status.
3355
+ Intent status is planned; outcome status is applied, unchanged, failed or
3356
+ incomplete. See [native trust](harness-trust.md) for durability and race limits.
package/docs/desktop.md CHANGED
@@ -383,10 +383,10 @@ Roster rows, soul cards, the soul page, the context panel and the spawn
383
383
  dialog show each instance's or soul's harness as a small badge, next to its
384
384
  name. The badge names the harness the CLI reports; it says nothing about
385
385
  whether that harness is installed or signed in. Pi's badge is the official
386
- pi.dev press-kit mark (MIT). The Claude Code and Codex badges are OATS's own
387
- drawings: they are not those products' logos, and OATS is not affiliated
388
- with or endorsed by Anthropic or OpenAI. An unknown or unreported harness
389
- shows "?". Sources and licences are in
386
+ pi.dev press-kit mark (MIT), and Claude Code's is Anthropic's Claude spark
387
+ in the theme's colours. The Codex badge is OATS's own drawing, not OpenAI's
388
+ logo. OATS is not affiliated with or endorsed by Anthropic or OpenAI. An
389
+ unknown or unreported harness shows "?". Sources and licences are in
390
390
  `packages/desktop/renderer/harness-marks/README.md`.
391
391
 
392
392
  ## Security posture
@@ -634,8 +634,9 @@ entry means zero audit destinations were attempted, not a successful write.
634
634
  No audit or metadata write is directed into the replacement home.
635
635
 
636
636
  A blocked result can follow a successfully submitted Enter. The accepted
637
- completion families cover exact installed-plugin and plugin-absent banners;
638
- different model, billing, effort or permission text can leave the pane active while
637
+ completion families cover exact installed-plugin and plugin-absent banners,
638
+ plus source-derived billing-only variants of those empty frames (Max, Pro,
639
+ Team and Enterprise). Other model, billing, effort or permission text can leave the pane active while
639
640
  reporting a retained block. Inspect `answers` and the event receipts; never infer
640
641
  that nothing started or nothing was answered. See the
641
642
  [completion limitation](configuration.md#exact-home-launch-prompt-consent).
@@ -759,3 +760,12 @@ When yolo is true, OATS adds `--dangerously-skip-permissions` for Claude Code,
759
760
  and `--yolo` plus trust for the instance home for Codex. pi takes no flag.
760
761
  `--no-yolo` removes only those added flags; native settings stay in force.
761
762
  Unattended execution never implies yolo.
763
+
764
+ ### Explicit deployment trust
765
+
766
+ Use `oats harness trust --dir <deployment> --harness claude|codex|all --plan`,
767
+ then the same command without `--plan`, on the execution host. This is the explicit
768
+ operator-only native-config write path; spawn/start/retire remain read-only with
769
+ respect to native trust. See [native trust](harness-trust.md) for qualified formats,
770
+ Git-boundary limits, audit evidence and partial-failure recovery. Root trust does
771
+ not establish channel/account/model readiness or enable launch-prompt consent.
@@ -82,20 +82,20 @@ them. Do not commit `oats-local.yaml`.
82
82
 
83
83
  **Trust the deployment once, for unattended launches.** Claude Code and Codex
84
84
  ask before they work in a folder they have not seen, and every instance home is
85
- new: a launch that stops at that prompt waits for a human. OATS never writes
86
- the harnesses' configuration, so trust the deployment directory yourself, once
87
- per harness you use:
85
+ new: a launch that stops at that prompt waits for a human. On the target host,
86
+ preview the exact deployment-root entry, then explicitly apply it while native
87
+ configuration writers are quiescent:
88
88
 
89
89
  ```bash
90
- cd ~/acme && claude # accept the folder-trust prompt, then quit
91
- cd ~/acme && codex # choose "Trust and continue", then quit
90
+ oats harness trust --dir ~/acme --harness all --plan
91
+ oats harness trust --dir ~/acme --harness all
92
92
  ```
93
93
 
94
- One entry covers every instance home under the deployment
95
- ([souls-and-instances.md](souls-and-instances.md#unattended-launches-folder-trust)
96
- says how each harness applies it). Until then, a claude or codex spawn warns
97
- that its session will stop at the folder-trust prompt, and so does
98
- `oats readiness`.
94
+ Select `claude` or `codex` instead of `all` when only one is needed. The apply
95
+ records a deployment audit; it does not launch a harness. Claude inheritance
96
+ stops at a Git boundary; Codex uses the existing per-invocation home override.
97
+ See [native trust](harness-trust.md) for qualification, format and recovery
98
+ limits. Spawn and `oats readiness` warn when the selected home remains uncovered.
99
99
 
100
100
  ## 3. Give the deployment a team
101
101