@awebai/oats 0.45.0 → 0.47.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
@@ -121,18 +121,30 @@ The qualified channel frame starts on its accepted option and permits one
121
121
  Enter only. Folder-trust and API-key questions remain unexpected and block.
122
122
  A qualified normal-output boundary closes observation without asserting readiness.
123
123
 
124
- **Qualified completion and limitation:** exact captured banners cover Claude
125
- 2.1.289 on darwin-arm64 at 110x35 with aweb-channel 1.7.11 installed, and the
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.
128
- Other model, billing, effort or permission banners remain unqualified: the one
129
- Enter can be submitted before `E_SPAWN_INCOMPLETE` with
130
- `launchPrompts.status: blocked`. The submitted answer remains in `answers` and
131
- the event receipt; the pane may already be active. Inspect the retained target;
132
- do not automatically retry input or relaunch it. The installed capture used an
133
- isolated configuration and dummy credentials with runtime network denied. It
134
- proves bounded UI completion, not live-account admission, connection or native
135
- receive readiness, and does not establish success for every production setup.
124
+ **Qualified completion and limitation:** the existing exact captured and
125
+ source-derived empty API/subscription frames remain supported. After one recorded
126
+ submitted channel Enter, the same qualified Claude 2.1.289 darwin-arm64 executable
127
+ also recognizes the [bounded bottom input/footer structure](launch-prompt-completion.md)
128
+ at 110x35. Its six mode labels, five effort labels and finite hints are
129
+ source-qualified; header/billing/model and preceding task text are not structural
130
+ completion conditions. The 21 exact question markers take precedence over both
131
+ completion paths after submission. Normal `? for shortcuts` and `esc to interrupt`
132
+ are not markers. Input authorization and exact-home consent are unchanged.
133
+
134
+ **Accepted reporting risk:** an unknown dialog retaining the composer/footer can
135
+ be misclassified completed. Completion permanently closes input authority, but
136
+ proves neither absence of all questions nor idle/account/channel readiness.
137
+ Missing effort, trailing notices, wrapped footers and other unsupported shapes
138
+ still block. A feature-flag footer change can reduce matches without a binary
139
+ change. A matched structural frame must be saved privately before completed is
140
+ audited; failure reports incomplete with the answer and target preserved.
141
+
142
+ A submitted Enter can therefore precede `E_SPAWN_INCOMPLETE`; the pane may already
143
+ be active. Inspect the answer, checked event receipt and retained target, rather
144
+ than automatically retrying input or relaunching. Existing API fixtures used
145
+ isolated dummy credentials; the observed Max regression is a labeled home-only
146
+ sanitized derivative of one controller-compared in-progress frame, not a new
147
+ end-to-end launch proof or general production-success claim.
136
148
 
137
149
  When a harness update changes the version-bound prompt frame, opted-in homes
138
150
  block again with `blocked: unexpected prompt` until fixtures are refreshed.
@@ -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.
@@ -1596,12 +1626,15 @@ allocated. Use runtime inspection and the existing start/restart lifecycle.
1596
1626
  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
- `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
1629
+ `blocked`: even after exact or structural completion recognition is qualified,
1630
+ unsupported input/footer shapes and known question markers can block after Enter
1601
1631
  while the actual pane is active. Consumers must preserve that submitted receipt
1602
1632
  and never translate this outcome into “nothing started” or automatic retry.
1603
1633
  The [completion limitation](configuration.md#exact-home-launch-prompt-consent)
1604
- is part of the shipping contract.
1634
+ is part of the shipping contract. Structural completion closes observation only;
1635
+ unknown dialogs retaining the recognized composer/footer can be misclassified.
1636
+ Mandatory structural evidence-save failure reports checked `incomplete` with the
1637
+ same answer and target preserved. Private receipt v2 adds no public DTO fields.
1605
1638
 
1606
1639
  Strict Desktop/pi readers must accept these additive fields and the new event
1607
1640
  kind before a writer containing them ships. For operator recovery, see
@@ -3279,3 +3312,47 @@ One warning per command, however many old spellings it read:
3279
3312
 
3280
3313
  The `--server` routes translate for a host without the `harness` feature:
3281
3314
  they send `--runtime` and `runtime` keys and read its `runtimes` list.
3315
+
3316
+ ### `harness trust`
3317
+
3318
+ `oats harness trust [--dir <deployment>] [--harness claude|codex|all] [--plan] [--json]`
3319
+ is host-local. Bare applies; `--apply`, remote selectors, unsupported harnesses,
3320
+ unknown flags and extra positionals are `E_BAD_ARGS`. Default harness is `all`.
3321
+ It uses the existing success/error JSON envelope. Result:
3322
+
3323
+ ```json
3324
+ {
3325
+ "operation": "harness-trust",
3326
+ "mode": "plan",
3327
+ "root": "/canonical/deployment",
3328
+ "entries": [{
3329
+ "harness": "claude", "file": "/native/.claude.json",
3330
+ "key": ["projects", "/canonical/deployment", "hasTrustDialogAccepted"],
3331
+ "current": null, "desired": true,
3332
+ "beforeDigest": null, "afterDigest": "sha256-hex", "status": "change"
3333
+ }],
3334
+ "audit": null,
3335
+ "warnings": []
3336
+ }
3337
+ ```
3338
+
3339
+ Entry statuses are `change|unchanged|refused|applied|failed|incomplete|not-attempted`.
3340
+ `current` contains only the known trust scalar, or null when missing. Codex's key
3341
+ ends in `trust_level` and its desired value is `trusted`. Digests are raw-byte
3342
+ SHA256 hex; missing files have null beforeDigest. Plan and unattempted entries
3343
+ carry the candidate afterDigest. Failed/incomplete attempted entries carry the
3344
+ last observed digest, or null for an absent/unverifiable file (a warning marks
3345
+ unverifiable observations). The intent retains the candidate digest. Apply's audit is
3346
+ `{path,operationId,status:"recorded"|"incomplete"}`. Override provenance is conveyed
3347
+ in warnings, without native configuration contents.
3348
+
3349
+ Preflight failures use `E_CONFIG_BROKEN` with the result in details. Apply failures
3350
+ use `E_HARNESS_TRUST_INCOMPLETE`, details `{...result,reason,mayHaveChanged}`;
3351
+ reason is the closed set `locked|changed|audit|write|verify`. Partial writes are
3352
+ retained. No existing instance-event envelope or lifecycle DTO changes.
3353
+
3354
+ Audit JSONL rows have `version: 1`, `kind: "harness-trust"`, ISO `at`,
3355
+ `operationId`, `phase: "intent"|"outcome"`, harness, root, file, beforeDigest,
3356
+ afterDigest and status.
3357
+ Intent status is planned; outcome status is applied, unchanged, failed or
3358
+ incomplete. See [native trust](harness-trust.md) for durability and race limits.
package/docs/desktop.md CHANGED
@@ -294,12 +294,12 @@ for a password or key, and never runs anything over ssh itself.
294
294
  ## Instances on servers
295
295
 
296
296
  Every instance a registered server reports shows in its workspace's roster, whoever spawned it. You
297
- can open its terminal, start, restart, stop and remove it, and read its readiness, activity, Git
297
+ can open its terminal, start, restart, stop and retire it, and read its readiness, activity, Git
298
298
  and diffs, as for a local one. The context panel's Soul tab and its Messaging & Teams list read
299
299
  through the server too (`oats inspect --server <id> --home <path>`), and its Work card, "model
300
300
  from" line and "older build" chip show the facts the server relays. Only its pull request is not read here, since the forge reads this
301
301
  computer's clones. Every command goes to the server by the instance's home (`--server <id> --home
302
- <path>`), never by a bare name. Stop and Remove show the plan the server makes, and confirm
302
+ <path>`), never by a bare name. Stop and Retire show the plan the server makes, and confirm
303
303
  against it.
304
304
 
305
305
  A read waits for the server: the view says "Reading from <server>…", and gives up after about
@@ -615,7 +615,8 @@ anchor edited or removed since the original pre-hook snapshot, instead of
615
615
  replacing concurrent changes with stale metadata. `launchPrompts` records `status`,
616
616
  `answers`, `reason` and event `receipt`; unknown prompts use
617
617
  `blocked: unexpected prompt`. Status `incomplete` means the audit could not be
618
- completed, including a possible key followed by an audit failure. It is
618
+ completed, including a possible key followed by an audit failure or failure to
619
+ retain mandatory structural-completion evidence. It is
619
620
  not proof that no input was sent. Both outcomes record `launched:false` while
620
621
  retaining the real process/endpoint for inspection: this is never permission
621
622
  to allocate another harness.
@@ -634,12 +635,81 @@ entry means zero audit destinations were attempted, not a successful write.
634
635
  No audit or metadata write is directed into the replacement home.
635
636
 
636
637
  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
638
+ completion families cover exact installed-plugin and plugin-absent banners,
639
+ plus source-derived billing-only variants of those empty frames (Max, Pro,
640
+ Team and Enterprise), and source-derived empty Max/bypass/medium frames.
641
+ Other model, billing, effort or permission text can leave the pane active while
639
642
  reporting a retained block. Inspect `answers` and the event receipts; never infer
640
643
  that nothing started or nothing was answered. See the
641
644
  [completion limitation](configuration.md#exact-home-launch-prompt-consent).
642
645
 
646
+ ### Private unmatched launch evidence
647
+
648
+ This section also covers mandatory structural-completion evidence.
649
+
650
+ After a submitted launch answer, an unmatched 110x35 frame is retained locally
651
+ at `<home>/.oats/launch-prompt-evidence/<sha256(startId)>/frame.txt`, with
652
+ `receipt.json` published last. This is the exact UTF-8 text already compared by
653
+ the controller, including whitespace and final newline, not a later recapture.
654
+ It is bounded to 64 KiB and 35 rows. There is no new input, observation, retry,
655
+ geometry change or readiness claim. Evidence is also mandatory when the post-answer
656
+ [structural completion rule](launch-prompt-completion.md) selects completion.
657
+ Previously qualified exact completion does not acquire that requirement. No
658
+ frame is saved before a submitted answer or for unrelated blocked reasons.
659
+
660
+ Find the invocation's existing `launch-prompt` event in the home's
661
+ `.oats-events.jsonl` (or the checked event rows in `launchPrompts.receipt`). Its
662
+ `data.startId` supplies the string to hash with SHA-256, UTF-8, yielding the
663
+ lowercase hexadecimal directory name. Match the event's home, socket, window,
664
+ pane, PID and `signatureDigest`; do not assume a top-level spawn-result `startId`.
665
+ Spawn and same-home start/restart use this same controller and event path.
666
+
667
+ New evidence directories are owner-only 0700 and files 0600. The writer checks
668
+ canonical directory identities, ownership, modes and symlinks, refuses ACLs on
669
+ evidence directories/files (including macOS ACLs hidden by xattrs), refuses an
670
+ existing invocation directory, and publishes bounded files without overwrite.
671
+ The private receipt binds the start, target, original home identity, dimensions,
672
+ frame inode, byte count and SHA-256. `retainedAt` is write time; `captureTime:null`
673
+ means no independent capture timestamp was recorded. It does not substitute an
674
+ event timestamp for capture time. Same-uid concurrent mutation between checks is
675
+ not excluded.
676
+
677
+ Private receipt version 2 uses `kind:"launch-prompt-frame"` and admits only
678
+ `outcome:"blocked", recognition:"unmatched"` or
679
+ `outcome:"completed", recognition:"structural"`. These fields describe the
680
+ recognition whose frame was saved, not the final public launch result: a later
681
+ audit or cleanup failure can still report `incomplete`. Historical version 1
682
+ receipts with `kind:"launch-prompt-unmatched"` describe blocked/unmatched
683
+ evidence. Readers must reject unknown versions, kinds or crossed pairs rather
684
+ than infer completion from an artifact's presence.
685
+
686
+ Before collecting a frame, verify its original `frameIdentity`, byte count,
687
+ digest and dimensions against the receipt, and bind the receipt's `startId`,
688
+ home and target to the checked launch event. A copied file has a different
689
+ inode: preserve the original identity as provenance instead of comparing the
690
+ copy's inode with it. Missing, partial, mismatched or failed-save evidence, or
691
+ an incomplete public launch result, must not be reported as a successful
692
+ completed observation. Collection never recaptures the pane or retries input.
693
+
694
+ Verify both files, receipt/identity/digest and the corresponding checked event
695
+ before treating the save as complete. A frame alone is partial evidence. Failed
696
+ publication, fsync, readback or temporary-file cleanup leaves the launch blocked
697
+ and adds only `; private launch evidence retention failed` to its diagnostic
698
+ reason. Already published files may remain, including a receipt if a later
699
+ verification fails; their presence alone is not a success claim. The submitted
700
+ answer is preserved. Existing event-audit failures still report `incomplete`.
701
+ A structural-completion save failure instead reports checked `incomplete` with
702
+ `private launch evidence retention failed`, preserving the submitted answer and
703
+ retained target. It never retries publication or input. An audit failure remains
704
+ incomplete even if private evidence was saved. No public result or event contains
705
+ the raw screen or private receipt.
706
+
707
+ The frame can contain private task or account text. It stays on this host with
708
+ no automatic transmission or expiry. Preserve needed evidence privately before
709
+ retirement; it follows the home's ordinary conservative recovery behavior, with
710
+ no integrity-neutral exclusion or new cleanup policy. A saved frame is evidence
711
+ for review, never automatic permission to activate a new matcher.
712
+
643
713
  Retiring a blocked or incomplete spawned home can preserve a recovery copy
644
714
  labelled `changed instance-home bytes`, even without authored changes: the
645
715
  kernel changed metadata from `launched:true` to `false` after its baseline.
@@ -759,3 +829,12 @@ When yolo is true, OATS adds `--dangerously-skip-permissions` for Claude Code,
759
829
  and `--yolo` plus trust for the instance home for Codex. pi takes no flag.
760
830
  `--no-yolo` removes only those added flags; native settings stay in force.
761
831
  Unattended execution never implies yolo.
832
+
833
+ ### Explicit deployment trust
834
+
835
+ Use `oats harness trust --dir <deployment> --harness claude|codex|all --plan`,
836
+ then the same command without `--plan`, on the execution host. This is the explicit
837
+ operator-only native-config write path; spawn/start/retire remain read-only with
838
+ respect to native trust. See [native trust](harness-trust.md) for qualified formats,
839
+ Git-boundary limits, audit evidence and partial-failure recovery. Root trust does
840
+ 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