@awebai/oats 0.45.0 → 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(); }
@@ -3389,7 +3414,7 @@ function versionCmd() {
3389
3414
  // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
3390
3415
  // runs on resolve/materialize (contract §6); a feature the binary does not implement is
3391
3416
  // never listed.
3392
- 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"], 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 }));
3393
3418
  return;
3394
3419
  }
3395
3420
  console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
@@ -3936,6 +3961,7 @@ else if (cmd === "update") {
3936
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); }
3937
3962
  updateCmd();
3938
3963
  }
3964
+ else if (cmd === "harness") harnessTrustCmd();
3939
3965
  else if (cmd === "readiness") await readinessCmd();
3940
3966
  else if (cmd === "instance") instanceCmd();
3941
3967
  else if (cmd === "root") console.log(resolve(new URL("..", import.meta.url).pathname));
@@ -4132,17 +4158,21 @@ Usage:
4132
4158
  a detached external retirement runs
4133
4159
  oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
4134
4160
  [--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
4135
- [--max-age <s>] [--json] installed capabilities with health, effective
4136
- layer bindings and activation, declared
4161
+ [--instructions] [--max-age <s>] installed capabilities with health, effective
4162
+ [--json] layer bindings and activation, declared
4137
4163
  operations with availability; --home answers the
4138
4164
  running home's recorded modules and their drift
4139
- from the deployment
4165
+ from the deployment; --instructions (--soul only)
4166
+ adds the AGENTS.md a spawn of the soul here would write
4140
4167
  oats operation run <layer>:<name> run an operation the soul's core capability for that
4141
4168
  (--home <abs> | --soul <name> [--dir <d>]) layer declares (knowledge:harvest, knowledge:
4142
4169
  [--arg k=v ...] [--json] inspect ...): resolved from the home's recorded
4143
4170
  modules or the deployment's soul, trust checked, the provider's
4144
4171
  own command run in the home or scope, envelope
4145
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
4146
4176
  oats launch-config list [--dir <scope> named launch configurations effective at a scope,
4147
4177
  | --home <abs> | --soul <name>] a home's recorded context or a soul's own scope:
4148
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
@@ -40,7 +40,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
40
40
  "team-model-3","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
41
41
  "preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
42
42
  "workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
43
- "automation-descriptions","souls-capabilities"],
43
+ "automation-descriptions","souls-capabilities","soul-composed-instructions"],
44
44
  "automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
45
45
  "readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
46
46
  "capabilityShowApi":1}
@@ -111,6 +111,7 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
111
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` |
112
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
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)) | |
114
115
 
115
116
  Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
116
117
  `workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
@@ -323,7 +324,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
323
324
  ### `oats inspect`
324
325
 
325
326
  ```text
326
- 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
327
328
  ```
328
329
 
329
330
  An instance subject, abridged:
@@ -378,6 +379,35 @@ capabilities}`, each the soul.yaml section as written or `null`.
378
379
  `null` before a spawn has copied the soul. `declarationProblems` holds
379
380
  `soul-declarations-unreadable` when soul.yaml does not parse.
380
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
+
381
411
  **Layers.** `id` is the capability filling the slot or `null`. `from`
382
412
  (feature `layers-from`) is `"soul"` or `"workspace"`, `null` for an empty slot
383
413
  or a home spawned before it was recorded.
@@ -1597,7 +1627,8 @@ Same-key spawn replay cannot convert a blocked outcome to successful spawn.
1597
1627
 
1598
1628
  `answers` can contain a `submitted` answer even when the final status is
1599
1629
  `blocked`: the accepted installed-plugin and plugin-absent completion banners
1600
- 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
1601
1632
  while the actual pane is active. Consumers must preserve that submitted receipt
1602
1633
  and never translate this outcome into “nothing started” or automatic retry.
1603
1634
  The [completion limitation](configuration.md#exact-home-launch-prompt-consent)
@@ -3279,3 +3310,47 @@ One warning per command, however many old spellings it read:
3279
3310
 
3280
3311
  The `--server` routes translate for a host without the `harness` feature:
3281
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.
@@ -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
 
@@ -0,0 +1,147 @@
1
+ # Explicit native harness trust
2
+
3
+ Run this command on the host where Claude or Codex runs, while other native
4
+ configuration editors are quiescent:
5
+
6
+ ```sh
7
+ oats harness trust --dir /absolute/deployment --harness all --plan
8
+ oats harness trust --dir /absolute/deployment --harness all
9
+ ```
10
+
11
+ `--plan` reads only. The bare command applies a fresh plan; there is no `--apply`.
12
+ The default harness is `all`, in Claude-then-Codex order. `claude` or `codex`
13
+ selects one. The deployment is resolved from the existing local command context,
14
+ including when invoked from an instance home, then canonicalized with the native
15
+ filesystem lookup. The result, native key, audit and reader verification use that
16
+ on-disk spelling, including on case-insensitive APFS. No remote
17
+ adapter, arbitrary file selector, parent-root substitution or harness launch is
18
+ performed. A native executable need not be installed to edit the qualified format.
19
+
20
+ The command writes only the canonical deployment root's native trust leaf:
21
+
22
+ - Claude: `projects[root].hasTrustDialogAccepted = true` in
23
+ `$CLAUDE_CONFIG_DIR/.claude.json`, or `~/.claude.json`.
24
+ - Codex: `projects[root].trust_level = "trusted"` in
25
+ `$CODEX_HOME/config.toml`, or `~/.codex/config.toml`.
26
+
27
+ Nonempty override directories must be absolute. Directory aliases are resolved;
28
+ symlink/nonregular/hardlinked leaves, foreign ownership and ACLs refuse. On Linux, GNU ls's single `.` security-context marker is accepted;
29
+ the context must be readable, match the same-directory candidate before replacement,
30
+ and remain unchanged at verification. A differing directory-default context refuses
31
+ before rename; OATS does not relabel files. This comparison narrows metadata races,
32
+ not the documented uncooperative-writer race. Tests simulate these SELinux probes;
33
+ they are not a live SELinux-host qualification.
34
+
35
+ On macOS, any extended-attribute (`@`) or ACL (`+`) marker deliberately refuses,
36
+ including `com.apple.provenance`. This v1 writer does not copy or remove those
37
+ attributes. Inspect the selected file; a refusal never authorizes stripping its
38
+ metadata automatically. Existing file permissions are preserved.
39
+ New config directories use 0700 and files 0600. The plan shows the effective file,
40
+ semantic key, current/desired trust scalar, byte digests and override provenance;
41
+ it never returns other config values or credentials.
42
+
43
+ This explicit act is the exception to read-only launch trust checks. Spawning,
44
+ scaffolding, starting and retiring do not write native trust or create consent
45
+ records. Existing Codex root-trust/yolo per-invocation overrides are unchanged.
46
+ This command does not enable development-channel prompt consent, change permission
47
+ mode, authenticate, install a plugin, or establish model/channel readiness.
48
+
49
+ ## Qualified scope and formats
50
+
51
+ Claude 2.1.289 darwin-arm64 was qualified against pinned native source and a
52
+ private no-Git deployment. One native root acceptance preceded two fresh child
53
+ launches. Root trust was true before each; neither child had accepted trust;
54
+ both reached ordinary UI. Native child bookkeeping later contained false.
55
+ Both bypass-mode controls in a separate disposable deployment still asked trust.
56
+ Native source independently walks trusted ancestors outside repository boundaries.
57
+ The recorded recipe and source exclude channel argv as a grant of trust. There
58
+ was no contemporaneous per-process environment snapshot; the same-runner root
59
+ trust question and absence of child recipe/capability bypass settings support
60
+ this bounded evidence. This is not qualification of other versions, nested Git
61
+ layouts or account/channel readiness.
62
+
63
+ Codex 0.160.1 native source independently declares a project `trust_level` and
64
+ writes `trusted`/`untrusted` under the project path. See the pinned
65
+ [native writer](https://github.com/openai/codex/blob/rust-v0.160.1/codex-rs/core/src/config/mod.rs)
66
+ and [configuration type](https://github.com/openai/codex/blob/rust-v0.160.1/codex-rs/config/src/config_toml.rs).
67
+ OATS's existing root-consent-to-exact-home invocation override remains separate
68
+ from native ancestor inheritance; Claude evidence is not Codex evidence.
69
+
70
+ JSON parsing rejects duplicate keys and wrong shapes. Only the required missing
71
+ object suffix or existing boolean token changes; unrelated large numbers, keys,
72
+ spacing and newlines remain byte-identical. False becomes true; an existing true
73
+ is a byte/mtime-preserving no-op.
74
+
75
+ The dependency-free TOML editor supports ordinary single-line assignments,
76
+ quoted/bare/dotted keys, explicit project tables, dotted trust keys and the
77
+ reader's inline project form containing only `trust_level`. It validates scalar,
78
+ single-line array and inline-table structure, duplicate/conflicting definitions,
79
+ and signed 64-bit integers. Multiline values, array-of-table headers, dates,
80
+ nondecimal numbers and unsupported representations refuse even if another TOML
81
+ parser accepts them. Root-level inline `projects` and inline project entries with
82
+ additional fields refuse rather than write a shape the existing readiness reader
83
+ does not consume. Comments, whitespace and line endings outside edit spans stay
84
+ unchanged. Untrusted becomes trusted; other trust values/types refuse. Both
85
+ editors validate the candidate and compare semantic trees with only the intended
86
+ leaf changed. Unsupported native format changes require refreshed qualification.
87
+
88
+ A Claude root entry cannot cover a home behind an intervening Git boundary.
89
+ Readiness may still warn after an unchanged root apply. Inspect that boundary;
90
+ do not automatically write a second root or answer a trust dialog.
91
+
92
+ ## Durability, audit and recovery
93
+
94
+ All selected configs are preflighted before any native write. Cooperating OATS
95
+ writers acquire exclusive destination locks in canonical-path order plus an audit
96
+ lock. Existing locks refuse promptly. The human/JSON error message names the exact
97
+ lock path so an operator can inspect an interrupted apply; OATS never steals or
98
+ deletes another invocation's lock, even when it appears stale. Identity and
99
+ raw-byte digests are rechecked after locking and immediately before replacement.
100
+ Candidate files are exclusively created beside the destination, fsynced, atomically
101
+ renamed and verified through the existing trust reader. Native writers do not
102
+ honor OATS locks: final checks detect observed drift but cannot guarantee exclusion
103
+ against an uncooperative writer racing the rename. No native process is stopped.
104
+
105
+ The deployment-private `.agents/harness-trust.jsonl` is independent of instance
106
+ lifetime, alongside other private kernel events. Its new directory/file modes are
107
+ 0700/0600. A checked, durable intent precedes each changed file; a checked outcome
108
+ follows it. An unchanged apply records an outcome without touching config bytes
109
+ or mtime. Plan creates no audit, directory, lock or temporary file. Invalid or
110
+ truncated existing JSONL refuses until operator inspection.
111
+
112
+ `all` is not a transaction. Failure stops later work, retains earlier changes and
113
+ reports unattempted entries. Trust may already have been consumed, so no rollback
114
+ is simulated. Inspect the native files and audit before rerunning; a correct
115
+ existing entry converges as a no-op. `E_HARNESS_TRUST_INCOMPLETE` has closed reasons
116
+ `locked|changed|audit|write|verify` and a conservative `mayHaveChanged` flag.
117
+ An audit failure before a write prevents it; failure after a possible replacement
118
+ reports incomplete and preserves intent evidence. The command never claims that
119
+ failure means native trust was undone.
120
+
121
+ ### Native qualification references
122
+
123
+ Claude source qualification used executable SHA256
124
+ `03d66745e3bb69ec727d66023696f3820bc0a00a8a5ba725eb6706d0c67cbe69`.
125
+ Its native exact/ancestor lookup is in byte range 182226330–182227750;
126
+ the startup trust decision is 197759244–197759315. The lookup has no
127
+ permission-mode or channel-argument input. Environment gates remain a separate
128
+ limit: `CLAUDE_CODE_SANDBOXED`, `IS_DEMO`, `CLAUBBIT` and the native `Le(false)`
129
+ gate can bypass the question. The disposable observation did not record a
130
+ contemporaneous child-process environment snapshot. No proprietary source is
131
+ included here.
132
+
133
+ Codex qualification is source-derived from `rust-v0.160.1`, independently of the
134
+ Claude observation. `set_project_trust_level_inner` (core config lines 2343–2410)
135
+ writes the exact project key and trust scalar; `ProjectConfig` (config type
136
+ lines 603–615) consumes the enum. The
137
+ [loader](https://github.com/openai/codex/blob/rust-v0.160.1/codex-rs/config/src/loader/mod.rs)
138
+ uses exact normalized project lookup keys (lines 1030–1082), preferring canonical
139
+ path spelling (1370–1398). This qualifies the native representation; OATS retains
140
+ its separately tested invocation override instead of claiming universal native
141
+ ancestor inheritance. The source files' SHA256 digests are:
142
+
143
+ | Upstream path | SHA256 |
144
+ | --- | --- |
145
+ | `codex-rs/core/src/config/mod.rs` | `854f5a6b184714740500b8d3eae2bb04cb88172efccf11d38a74f2f6189c0341` |
146
+ | `codex-rs/config/src/config_toml.rs` | `453b5ed4d49cf3768ce47e1f2fe1987c92d694bba9b52373dcf10f15901ab9d1` |
147
+ | `codex-rs/config/src/loader/mod.rs` | `2ec85a665f827dd7080f8e562c960e49158b0d8a11b1022cc0a93eed05986d0c` |
@@ -53,7 +53,8 @@ published to npm. Its developer docs are in
53
53
  | `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit |
54
54
  | `materialize.mjs` | copying modules into a home and composing it |
55
55
  | `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata |
56
- | `instruction-composition.mjs` | the generated `AGENTS.md` |
56
+ | `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
57
+ | `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul` and `inspect --soul --instructions` |
57
58
  | `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
58
59
  | `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
59
60
  | `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
@@ -67,7 +68,9 @@ published to npm. Its developer docs are in
67
68
  | `servers.mjs` | routing commands to a registered server |
68
69
  | `launch-prompt-policy.mjs` | strict host-local exact-home aweb development-channel consent, canonical directory validation and config provenance |
69
70
  | `launch-prompts.mjs`, `launch-prompt-transport.mjs` | bounded launch-only controller and visible-screen transport; private process authority, injectable clock/transport, durable checked receipts and the fixture-gated exact aweb development-channel signature |
70
- | `harness-trust.mjs` | reading (never writing) Claude's and Codex's folder trust for a launch |
71
+ | `harness-trust.mjs` | read-only native trust coverage and operator remedy for launches |
72
+ | `harness-trust-write.mjs` | explicit operator plan/apply, cooperating locks, durable deployment audit and no-rollback outcomes |
73
+ | `harness-trust-json.mjs`, `harness-trust-toml.mjs` | bounded native parsers and byte-preserving edits of one trust leaf |
71
74
 
72
75
  The schedule registry stores explicit concurrency caps, leaving the schedule
73
76
  cap absent for its effective default of five. `readRegistry()` is a pure,