@awebai/oats 0.55.1 → 0.56.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.
Files changed (78) hide show
  1. package/bin/oats.mjs +78 -62
  2. package/docs/capabilities.md +67 -3
  3. package/docs/design/2026-09-23-workspace-module-contracts.md +27 -3
  4. package/docs/desktop-cli-api.md +317 -35
  5. package/docs/desktop-instance-start.md +105 -12
  6. package/docs/desktop.md +54 -7
  7. package/docs/execution-targets.md +184 -9
  8. package/docs/harness-trust.md +128 -11
  9. package/docs/implementation.md +54 -7
  10. package/docs/integrations.md +1 -1
  11. package/docs/knowledge.md +35 -16
  12. package/docs/official-catalog.md +3 -3
  13. package/docs/packages.md +12 -12
  14. package/docs/release-lane.md +26 -1
  15. package/docs/release-notes/v0.56.0.md +699 -0
  16. package/docs/servers.md +21 -5
  17. package/docs/souls-and-instances.md +8 -4
  18. package/docs/tui.md +99 -26
  19. package/docs/upgrading.md +4 -1
  20. package/docs/workspaces.md +26 -6
  21. package/lib/automations.mjs +3 -4
  22. package/lib/bounded-read.mjs +18 -0
  23. package/lib/capability-show.mjs +13 -2
  24. package/lib/claim.mjs +3 -4
  25. package/lib/core.mjs +480 -152
  26. package/lib/errors.mjs +39 -0
  27. package/lib/harness-trust-write.mjs +119 -40
  28. package/lib/harness-trust.mjs +31 -18
  29. package/lib/instance-inspect.mjs +160 -11
  30. package/lib/instance-lifecycle.mjs +47 -30
  31. package/lib/packages.mjs +8 -5
  32. package/lib/pi-bridge.mjs +18 -19
  33. package/lib/remote.mjs +88 -51
  34. package/lib/retire-output.mjs +9 -4
  35. package/lib/schedule.mjs +3 -4
  36. package/lib/servers.mjs +39 -6
  37. package/lib/session-viewer.mjs +25 -1
  38. package/lib/triggers.mjs +3 -4
  39. package/lib/workspace.mjs +6 -6
  40. package/lib/worktree.mjs +10 -6
  41. package/lib/write-through-private-file.mjs +26 -0
  42. package/package-catalog.json +2 -2
  43. package/package.json +1 -1
  44. package/packages/client/cli-adapter.mjs +108 -13
  45. package/packages/client/cli-locator.mjs +16 -14
  46. package/packages/client/deployment-panel.mjs +4 -3
  47. package/packages/client/display-text.mjs +2 -1
  48. package/packages/client/instance-events-contract.mjs +4 -3
  49. package/packages/client/instance-lifecycle.mjs +228 -0
  50. package/packages/client/instance-presentation.mjs +9 -0
  51. package/packages/client/instance-tree.mjs +10 -8
  52. package/packages/client/kernel-lines.mjs +3 -3
  53. package/packages/client/launch-contract.mjs +11 -0
  54. package/packages/client/lifecycle-cli.mjs +12 -6
  55. package/packages/client/lifecycle-confirmation.mjs +407 -0
  56. package/packages/client/lifecycle-contract.mjs +6 -2
  57. package/packages/client/own-codes.mjs +1 -0
  58. package/packages/client/panel-views.mjs +39 -2
  59. package/packages/client/readiness-contract.mjs +2 -2
  60. package/packages/client/remote-roster.mjs +50 -5
  61. package/packages/client/roster-sections.mjs +3 -3
  62. package/packages/client/session-start.mjs +98 -0
  63. package/packages/client/start-gate.mjs +46 -0
  64. package/packages/client/start-messages.mjs +17 -0
  65. package/packages/client/workspace-views.mjs +2 -2
  66. package/packages/tui/README.md +10 -6
  67. package/packages/tui/lib/actions.mjs +4 -2
  68. package/packages/tui/lib/client.mjs +5 -2
  69. package/packages/tui/lib/config.mjs +39 -9
  70. package/packages/tui/lib/main.mjs +83 -13
  71. package/packages/tui/lib/model.mjs +116 -11
  72. package/packages/tui/lib/open.mjs +45 -0
  73. package/packages/tui/lib/read.mjs +46 -10
  74. package/packages/tui/lib/store.mjs +64 -9
  75. package/packages/tui/lib/term/tty.mjs +71 -12
  76. package/packages/tui/lib/views/frame.mjs +115 -33
  77. package/packages/tui/lib/views/help.mjs +37 -8
  78. package/skills/oats-getting-started/SKILL.md +6 -3
package/lib/errors.mjs CHANGED
@@ -45,6 +45,45 @@ export function errorCause(e) {
45
45
  if (!isDefect(e)) return undefined;
46
46
  return { name: e instanceof Error && typeof e.name === "string" && e.name ? e.name : "Error" };
47
47
  }
48
+ /** The details of a spawn's refusal, by its code: the codes whose answer had details of its own
49
+ * before a spawn went through the door (awebai/oats#1047), each with exactly the keys it had. Every
50
+ * other code, and an error with none, carries the error's details only when `unconfirmed` is true
51
+ * (spawnFailedDetails): never a `home` taken from the error, which a consumer reads as retained
52
+ * effects. The table decides details, never the code. */
53
+ const hookReceipt = (e) => ({ hooks: e.details?.hooks ?? [], ...(e.details?.unconfirmed === true ? { unconfirmed: true } : {}) });
54
+ const SPAWN_REFUSAL_DETAILS = Object.freeze({
55
+ // A launch refusal is a fact about the selection: its own details, as the `E_LAUNCH_…` family's.
56
+ E_MODEL_UNKNOWN: (e) => e.details,
57
+ E_UNSUPPORTED_HARNESS: (e) => e.details,
58
+ E_HARNESS_UNAVAILABLE: (e) => e.details,
59
+ E_CLAUDE_CONFIG_REMOVED: (e) => e.details,
60
+ E_CHILD_SPAWNS_DISABLED: (e) => ({ parent: e.parent, policy: e.policy }),
61
+ E_BRANCH_EXISTS: () => undefined,
62
+ E_BASE_UNKNOWN: () => undefined,
63
+ // Interrupted while its worktree hooks ran (#796): rolled back, the message says how far.
64
+ E_INTERRUPTED: (e) => e.details,
65
+ // The hooks' receipt (paths only), and `unconfirmed` when the rollback could not confirm its effects.
66
+ E_REQUIRED_HOOK_FAILED: hookReceipt,
67
+ E_HOOK_ENVIRONMENT_CONTRACT: hookReceipt,
68
+ // The observed base could not be fetched into the clone: the clone, the repository and the commit.
69
+ E_REMOTE_UNREADABLE: (e) => (e.details?.commit ? e.details : spawnFailedDetails(e)),
70
+ // K6b: the fresh decision travels with the refusal, so a client previews again.
71
+ E_DECISION_STALE: (e) => ({ decision: e.decision }),
72
+ E_IDEMPOTENCY_CONFLICT: (e) => ({ instance: e.instance, home: e.home }),
73
+ E_PLACEMENT_TAKEN: (e) => ({ instance: e.instance, home: e.home }),
74
+ E_INSTANCE_NAME_TAKEN: (e) => ({ instance: e.instance, home: e.home ?? null, ...(e.session ? { session: e.session } : {}) }),
75
+ E_INSTANCE_NAME_INVALID: (e) => e.details,
76
+ E_SPAWN_INCOMPLETE: (e) => ({ ...e.details, instance: e.instance, home: e.home, launched: e.launched }),
77
+ });
78
+ const spawnFailedDetails = (e) => (e?.details?.unconfirmed === true ? e.details : undefined);
79
+ /** The `details` of the answer to an error `e` of `oats spawn` (bin/oats.mjs spawnFail): the table's
80
+ * for a code it holds, a launch refusal's own (`E_LAUNCH_…`), else spawnFailedDetails. */
81
+ export function spawnRefusalDetails(e) {
82
+ const code = kernelCode(e, null);
83
+ if (code && Object.hasOwn(SPAWN_REFUSAL_DETAILS, code)) return SPAWN_REFUSAL_DETAILS[code](e);
84
+ if (code?.startsWith("E_LAUNCH_")) return e.details;
85
+ return spawnFailedDetails(e);
86
+ }
48
87
  /** `e` as a kernel error. One whose code an answer carries (isAnswerCode) is returned as it is. Any other is wrapped:
49
88
  * the code `fallback`, `message` (default: its own), `details.cause` when it has one (errorCause)
50
89
  * and the error itself as `cause`, so that whoever prints the answer still has a defect's stack. */
@@ -3,15 +3,40 @@
3
3
  * but cannot eliminate, the race immediately before rename. No rollback. */
4
4
  import * as fs from 'node:fs';
5
5
  import { join, dirname, basename, resolve, isAbsolute } from 'node:path';
6
- import { homedir } from 'node:os';
7
6
  import { createHash, randomUUID } from 'node:crypto';
8
7
  import { execFileSync } from 'node:child_process';
9
8
  import { editClaudeTrust } from './harness-trust-json.mjs';
10
9
  import { editCodexTrust } from './harness-trust-toml.mjs';
11
- import { CONFIG_DIR_VAR, claudeTrusts, codexTrustsRoot, codexTrustedDirs, launchConfigDir } from './harness-trust.mjs';
10
+ import { CONFIG_DIR_VAR, claudeTrusts, codexTrustsRoot, codexTrustedDirs, launchConfigFolder } from './harness-trust.mjs';
11
+ import { launchEnvironment, unestablishedNote } from './core.mjs';
12
12
  const digest = bytes => createHash('sha256').update(bytes).digest('hex');
13
13
  const error = (code, message, details) => Object.assign(new Error(message), { code, details });
14
- const broken = () => error('E_CONFIG_BROKEN', 'Native trust configuration is unreadable, unsafe, invalid, or outside the supported format; inspect the selected file before retrying.');
14
+ const broken = (refusal) => Object.assign(error('E_CONFIG_BROKEN', 'Native trust configuration is unreadable, unsafe, invalid, or outside the supported format; inspect the selected file before retrying.'), { refusal });
15
+ /** Which check refused a configuration file: fixed wording, never the file's content, a parser
16
+ * message or another configuration value. The marker case also gives the way forward. */
17
+ const REFUSALS = {
18
+ type: 'is not a regular file (a symbolic link, directory or other type)',
19
+ links: 'has more than one hard link',
20
+ owner: 'is owned by another user',
21
+ 'special-mode': 'has setuid, setgid or sticky bits set',
22
+ marker: ({ harness, root }) => `has an extended-attribute (@) or ACL (+) marker in ls, which this writer neither copies nor removes; leave the file and its attributes as they are: accept ${harness}'s own folder-trust dialog for ${root} in a ${harness} session that uses this file, then check the harness-trust item of oats readiness`,
23
+ context: 'has a Linux security context that cannot be read',
24
+ metadata: 'its metadata could not be read (the ls probe failed or its answer is not recognized)',
25
+ changed: 'changed while it was being read',
26
+ // Raised while resolving a target, whose callers name it first; kept so the set is closed.
27
+ directory: 'is not in a usable configuration directory (a path that is not a directory, or one with no existing ancestor)',
28
+ size: 'is larger than 8 MiB',
29
+ utf8: 'is not valid UTF-8',
30
+ format: 'is not in the supported format (see "Qualified scope and formats" in docs/harness-trust.md)',
31
+ };
32
+ /** The `problem` of a file the plan refused. An exception no check named is reported by its errno
33
+ * code alone, else by the generic sentence; its message is never echoed. Exported for tests. */
34
+ export function refusalProblem(e, file, context) {
35
+ const wording = REFUSALS[e?.refusal];
36
+ if (wording) return `${file}: ${typeof wording === 'function' ? wording(context) : wording}`;
37
+ if (typeof e?.code === 'string' && /^E[A-Z0-9]+$/.test(e.code)) return `${file}: could not be read (${e.code})`;
38
+ return `${file}: ${broken().message}`;
39
+ }
15
40
  const identity = s => `${s.dev}:${s.ino}`;
16
41
  function stat(path) { try { return fs.lstatSync(path); } catch (e) { if (e.code === 'ENOENT') return null; throw e; } }
17
42
  /** GNU ls uses '.' for a security context alone, '+' for an ACL. macOS
@@ -19,18 +44,23 @@ function stat(path) { try { return fs.lstatSync(path); } catch (e) { if (e.code
19
44
  * context is checked on the same-directory candidate before any replacement. */
20
45
  export function nativeSecurityContext(path, { platform = process.platform, run = execFileSync } = {}) {
21
46
  const flags = platform === 'darwin' ? ['-lde', path] : ['-ld', '--', path];
22
- const mode = run('ls', flags, { encoding: 'utf8' }).split(/\s/, 1)[0];
47
+ let mode; try { mode = run('ls', flags, { encoding: 'utf8' }).split(/\s/, 1)[0]; } catch { throw broken('metadata'); }
23
48
  if (!/^-[-rwxStTs]{9}$/.test(mode)) {
24
- if (platform !== 'linux' || !/^-[-rwxStTs]{9}\.$/.test(mode)) throw broken();
25
- const context = run('ls', ['-Zd', '--', path], { encoding: 'utf8' }).trim().split(/\s/, 1)[0];
26
- if (!context || context === '?' || context.split(':').length < 3) throw broken();
49
+ const marker = /^-[-rwxStTs]{9}(.)$/.exec(mode)?.[1];
50
+ if (marker === '+' || (platform === 'darwin' && marker === '@')) throw broken('marker');
51
+ if (platform !== 'linux' || marker !== '.') throw broken('metadata');
52
+ let context; try { context = run('ls', ['-Zd', '--', path], { encoding: 'utf8' }).trim().split(/\s/, 1)[0]; } catch { throw broken('context'); }
53
+ if (!context || context === '?' || context.split(':').length < 3) throw broken('context');
27
54
  return context;
28
55
  }
29
56
  return null;
30
57
  }
31
58
  function regular(path, metadataProbe) {
32
59
  const s = stat(path); if (!s) return null;
33
- if (!s.isFile() || s.nlink !== 1 || s.uid !== process.getuid?.() || (s.mode & 0o7000)) throw broken();
60
+ if (!s.isFile()) throw broken('type');
61
+ if (s.nlink !== 1) throw broken('links');
62
+ if (s.uid !== process.getuid?.()) throw broken('owner');
63
+ if (s.mode & 0o7000) throw broken('special-mode');
34
64
  s.securityContext = metadataProbe(path);
35
65
  return s;
36
66
  }
@@ -39,28 +69,30 @@ function canonicalMissingDirectory(path) {
39
69
  for (;;) {
40
70
  const s = stat(at);
41
71
  if (s) {
42
- const real = fs.realpathSync.native(at); if (!fs.statSync(real).isDirectory()) throw broken();
72
+ const real = fs.realpathSync.native(at); if (!fs.statSync(real).isDirectory()) throw broken('directory');
43
73
  return join(real, ...tail.reverse());
44
74
  }
45
- const parent = dirname(at); if (parent === at) throw broken(); tail.push(basename(at)); at = parent;
75
+ const parent = dirname(at); if (parent === at) throw broken('directory'); tail.push(basename(at)); at = parent;
46
76
  }
47
77
  }
48
78
  function snapshot(file, metadataProbe) {
49
79
  const s = regular(file, metadataProbe); if (!s) return { bytes: null, digest: null, identity: null, mode: null, securityContext: null };
50
80
  const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
51
81
  try {
52
- if (identity(fs.fstatSync(fd)) !== identity(s)) throw broken();
53
- const bytes = fs.readFileSync(fd); if (bytes.length > 8 * 1024 * 1024) throw broken();
54
- if (identity(fs.lstatSync(file)) !== identity(s)) throw broken();
82
+ if (identity(fs.fstatSync(fd)) !== identity(s)) throw broken('changed');
83
+ const bytes = fs.readFileSync(fd); if (bytes.length > 8 * 1024 * 1024) throw broken('size');
84
+ if (identity(fs.lstatSync(file)) !== identity(s)) throw broken('changed');
55
85
  return { bytes, digest: digest(bytes), identity: identity(s), mode: s.mode & 0o777, uid: s.uid, gid: s.gid, securityContext: s.securityContext };
56
86
  } finally { fs.closeSync(fd); }
57
87
  }
58
88
  const same = (a, b) => a.digest === b.digest && a.identity === b.identity && a.mode === b.mode && a.uid === b.uid && a.gid === b.gid && a.securityContext === b.securityContext;
89
+ /** The native file `harness` reads under `env`, which holds exactly what selects it: the
90
+ * harness's selector, or the HOME its default folder is under. Nothing is read from this process. */
59
91
  function nativePath(harness, env) {
60
- const home = env.HOME || homedir(); if (!isAbsolute(home)) throw broken();
61
92
  const override = harness === 'claude' ? env.CLAUDE_CONFIG_DIR : env.CODEX_HOME;
62
- if (override && !isAbsolute(override)) throw broken();
63
- const dir = override || (harness === 'claude' ? home : join(home, '.codex'));
93
+ if (override && !isAbsolute(override)) throw broken('relative-override');
94
+ if (!override && !(env.HOME && isAbsolute(env.HOME))) throw broken('relative-home');
95
+ const dir = override || (harness === 'claude' ? env.HOME : join(env.HOME, '.codex'));
64
96
  return join(canonicalMissingDirectory(dir), harness === 'claude' ? '.claude.json' : 'config.toml');
65
97
  }
66
98
  function validAudit(file, metadataProbe) {
@@ -80,78 +112,125 @@ function ensureDirectory(path) {
80
112
  if (stat(path)) { if (!fs.lstatSync(path).isDirectory() || fs.realpathSync.native(path) !== path) throw broken(); return; }
81
113
  ensureDirectory(dirname(path)); fs.mkdirSync(path, { mode: 0o700 }); syncDirectory(dirname(path));
82
114
  }
83
- /** The configuration files `name` reads: the ambient one (the operator's env), then one per
84
- * launch configuration whose env moves the harness's configuration directory, in name order,
85
- * deduplicated by canonical directory. No configuration directory is ever created. A launch
115
+ /** The configuration files `name` reads: the ambient one, then one per launch configuration
116
+ * whose env moves the harness's configuration directory (its references resolved from `env`, this
117
+ * process), in name order, deduplicated by canonical directory. A configuration moves it with the
118
+ * harness's selector, or, when the launch has no selector at all (it sets none and the pane has
119
+ * none), with HOME: its default file is then under that HOME, which is the file its launch reads
120
+ * (the same answer, launchEnvironment over the same pane). The ambient file is the one a
121
+ * launch with no launch configuration reads, by the one answer every launch check reads
122
+ * (`launch`: core.mjs launchEnvironment over the deployment's session): the file its selector
123
+ * names, else the default one under its HOME; never this process's own, unless no pane's
124
+ * environment is established, which `note` then says with what was read instead. When that
125
+ * environment cannot be read the ambient target is `unreadable`, with the `problem`: refused, never
126
+ * a file guessed from this process. That holds for a tmux that could not say whether a server
127
+ * runs as well (`unread` on the answer): a failed read. A server known not to run, and a process
128
+ * with no tmux on its PATH to ask with (no prediction is made), leave this process's file as the
129
+ * one to write, with the `note`. No configuration directory is ever created. A launch
86
130
  * configuration's directory that cannot be resolved or does not exist is a target with a
87
131
  * `problem`: refused. A missing ambient directory means the harness has not run as this user:
88
132
  * `skipped` when every harness was asked for (`named` false), a `problem` when this one was named. */
89
- function trustTargets(name, env, launchConfigs, named) {
133
+ function trustTargets(name, env, launchConfigs, named, launch) {
90
134
  const variable = CONFIG_DIR_VAR[name], targets = [], byFile = new Map();
91
135
  const add = (target) => {
92
136
  if (target.file && byFile.has(target.file)) { byFile.get(target.file).launchConfigs.push(...target.launchConfigs); return; }
93
137
  if (target.file) byFile.set(target.file, target);
94
138
  targets.push(target);
95
139
  };
96
- let ambientFile = null;
97
- try { ambientFile = nativePath(name, env); } catch { /* refused below, as a broken file */ }
98
- add({ env, ambient: true, launchConfigs: [], file: ambientFile });
140
+ const selector = launch.of(variable);
141
+ // The default file is under HOME: read only when a launch has no selector.
142
+ const base = selector.absent ? launch.of('HOME') : null;
143
+ const failed = selector.problem ? selector : base?.problem ? base : null;
144
+ const unread = selector.unread ?? base?.unread;
145
+ const unestablished = what => `the file a ${name} launch with no launch configuration reads could not be established: ${what}`;
146
+ if (failed) add({ ambient: true, unreadable: true, launchConfigs: [], file: null, problem: unestablished(`${failed.problem}${failed.remedy ? `: ${failed.remedy}` : ''}`) });
147
+ else if (unread) add({ ambient: true, unreadable: true, launchConfigs: [], file: null, problem: unestablished(`${unread}. A server that could not be asked may run under another account than this process's, so this process's file is not written in its place`) });
148
+ else {
149
+ const ambientEnv = base ? { HOME: base.value } : { [variable]: selector.value };
150
+ let ambientFile = null, ambientProblem;
151
+ try { ambientFile = nativePath(name, ambientEnv); } catch (e) {
152
+ // What selects it names no usable file: say which name and where it was read, never its value.
153
+ const { source } = base ?? selector;
154
+ ambientProblem = unestablished(e.refusal === 'relative-home' || e.refusal === 'relative-override' ? `${source} is not an absolute path` : `${source} does not select a usable ${name} configuration directory`);
155
+ }
156
+ add({ env: ambientEnv, ambient: true, launchConfigs: [], file: ambientFile, selected: base ? null : selector, note: unestablishedNote(launch, base ? [variable, 'HOME'] : [variable]), ...(ambientProblem ? { problem: ambientProblem } : {}) });
157
+ }
99
158
  for (const config of Object.values(launchConfigs).filter(c => c.harness === name).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0)) {
100
- const resolved = launchConfigDir(name, config.env, env);
101
- if (!resolved) continue;
159
+ const resolved = launchConfigFolder(variable, config.env, env);
102
160
  const named = text => `launch configuration ${config.name}: ${text}`;
161
+ if (!resolved) {
162
+ // No selector of its own: its launch reads the pane's, as the ambient one does, and when
163
+ // there is none, the default file under its HOME. A HOME it sets itself moves that file.
164
+ if (!Object.hasOwn(config.env || {}, 'HOME') || !selector.absent) continue;
165
+ const home = launchEnvironment({ configEnv: config.env, configName: config.name, env, pane: launch.pane }).of('HOME');
166
+ if (home.problem) { add({ ambient: false, launchConfigs: [config.name], file: null, problem: named(home.problem) }); continue; }
167
+ const homeEnv = { HOME: home.value };
168
+ let file; try { file = nativePath(name, homeEnv); } catch (e) { add({ ambient: false, launchConfigs: [config.name], file: null, problem: named(`HOME ${JSON.stringify(home.value)} ${e.refusal === 'relative-home' ? 'is not an absolute path' : `does not select a usable ${name} configuration directory`}`) }); continue; }
169
+ add({ env: homeEnv, ambient: false, launchConfigs: [config.name], file, dir: dirname(file), underHome: true });
170
+ continue;
171
+ }
103
172
  if (resolved.problem) { add({ ambient: false, launchConfigs: [config.name], file: null, problem: named(resolved.problem) }); continue; }
104
- const targetEnv = { ...env, [variable]: resolved.dir };
173
+ const targetEnv = { [variable]: resolved.dir };
105
174
  let file; try { file = nativePath(name, targetEnv); } catch { add({ ambient: false, launchConfigs: [config.name], file: null, problem: named(`${variable} ${resolved.dir} is not a usable directory`) }); continue; }
106
175
  add({ env: targetEnv, ambient: false, launchConfigs: [config.name], file, dir: resolved.dir });
107
176
  }
108
177
  for (const t of targets) if (t.file && !t.problem && !fs.existsSync(dirname(t.file))) {
109
- if (t.launchConfigs.length) t.problem = `launch configuration ${t.launchConfigs[0]}: ${variable} ${t.dir ?? dirname(t.file)} does not exist; OATS never creates a harness configuration directory: create it, or start ${name} with it once, then rerun`;
178
+ if (t.launchConfigs.length) t.problem = `launch configuration ${t.launchConfigs[0]}: ${t.underHome ? `${t.dir} (${name}'s directory under its HOME)` : `${variable} ${t.dir ?? dirname(t.file)}`} does not exist; OATS never creates a harness configuration directory: create it, or start ${name} with it once, then rerun`;
110
179
  else if (named) t.problem = `${dirname(t.file)} does not exist: ${name} has not run as this user; OATS never creates a harness configuration directory: start ${name} once, then rerun`;
111
180
  else t.skipped = `${dirname(t.file)} does not exist: ${name} has not run as this user`;
112
181
  }
113
182
  for (const t of targets) t.launchConfigs.sort();
114
183
  return targets;
115
184
  }
116
- /** Planning performs reads only, including when native directories do not exist. */
117
- export function planHarnessTrust(root, { harness = 'all', env = process.env, launchConfigs = {}, metadataProbe = nativeSecurityContext } = {}) {
185
+ /** Planning performs reads only, including when native directories do not exist. `launch`: the
186
+ * one answer for a launch of this deployment with no launch configuration (trustTargets); a caller
187
+ * that gives none has established no pane's environment, so `env` is read and the plan says so.
188
+ * A refusal keeps its code, E_CONFIG_BROKEN, whenever a target is refused for its configuration or
189
+ * its file; E_RUNTIME_ENDPOINT_UNKNOWN when the only refused targets are those whose pane's
190
+ * environment could not be read. Either way the details hold the plan, the refused entries in it. */
191
+ export function planHarnessTrust(root, { harness = 'all', env = process.env, launchConfigs = {}, metadataProbe = nativeSecurityContext, launch = launchEnvironment({ env, pane: { unestablished: ': no launch environment was given' } }) } = {}) {
118
192
  if (!['all', 'claude', 'codex'].includes(harness)) throw error('E_BAD_ARGS', '--harness must be claude, codex, or all');
119
193
  // Native lookup preserves the on-disk casing on case-insensitive APFS; the
120
194
  // JS realpath implementation can retain the caller's spelling as a wrong key.
121
195
  root = fs.realpathSync.native(root);
122
- const result = { operation: 'harness-trust', mode: 'plan', root, entries: [], audit: null, warnings: [] }, plans = [];
196
+ const result = { operation: 'harness-trust', mode: 'plan', root, entries: [], audit: null, warnings: [] }, plans = [], unreadable = new Set();
123
197
  for (const name of harness === 'all' ? ['claude', 'codex'] : [harness]) {
124
- for (const target of trustTargets(name, env, launchConfigs, harness !== 'all')) {
198
+ for (const target of trustTargets(name, env, launchConfigs, harness !== 'all', launch)) {
199
+ if (target.note) result.warnings.push(`${name}: ${target.note}`);
125
200
  const key = ['projects', root, name === 'claude' ? 'hasTrustDialogAccepted' : 'trust_level'];
126
201
  const entry = { harness: name, file: target.file, ambient: target.ambient, launchConfigs: target.launchConfigs, key, current: null, desired: name === 'claude' ? true : 'trusted', beforeDigest: null, afterDigest: null, status: 'refused', ...(target.problem ? { problem: target.problem } : {}) };
127
202
  result.entries.push(entry);
203
+ if (target.unreadable) unreadable.add(entry);
128
204
  if (target.skipped) { entry.status = 'skipped'; entry.reason = target.skipped; continue; }
129
205
  if (target.problem || !target.file) continue;
130
206
  try {
131
207
  const file = target.file;
132
208
  const before = snapshot(file, metadataProbe); entry.beforeDigest = before.digest;
133
209
  const text = before.bytes?.toString('utf8') ?? (name === 'claude' ? '{}' : '');
134
- if (before.bytes && !Buffer.from(text).equals(before.bytes)) throw broken();
135
- const edited = (name === 'claude' ? editClaudeTrust : editCodexTrust)(text, root);
210
+ if (before.bytes && !Buffer.from(text).equals(before.bytes)) throw broken('utf8');
211
+ // An editor's own exception is a format refusal; its message is never inspected.
212
+ let edited; try { edited = (name === 'claude' ? editClaudeTrust : editCodexTrust)(text, root); } catch { throw broken('format'); }
136
213
  // Preflight the existing reader's supported representation as well as
137
214
  // native syntax; never discover a known compatibility gap after writing.
138
- if (name === 'codex' && !codexTrustedDirs(edited.text).has(root)) throw broken();
215
+ if (name === 'codex' && !codexTrustedDirs(edited.text).has(root)) throw broken('format');
139
216
  const after = Buffer.from(edited.text);
140
217
  entry.current = edited.current; entry.afterDigest = digest(after);
141
218
  entry.status = before.bytes?.equals(after) ? 'unchanged' : 'change';
142
219
  plans.push({ entry, before, after, env: target.env });
143
- const overrideKey = CONFIG_DIR_VAR[name];
144
- if (target.ambient && env[overrideKey]) result.warnings.push(`${overrideKey} selects ${env[overrideKey]}; effective file ${file}`);
145
- } catch { /* Per-file refusal; never echo native content or parser exceptions. */ }
220
+ if (target.ambient && target.selected) result.warnings.push(`${CONFIG_DIR_VAR[name]} selects ${target.selected.value} (${target.selected.source}); effective file ${file}`);
221
+ } catch (e) { if (entry.status === 'refused') entry.problem = refusalProblem(e, target.file, { harness: name, root }); /* Per-file refusal; never echo native content or parser exceptions. */ }
146
222
  }
147
223
  }
148
224
  const problems = result.entries.filter(e => e.problem).map(e => e.problem);
149
- if (result.entries.some(e => e.status === 'refused')) throw error('E_CONFIG_BROKEN', problems.length ? `Harness trust targets cannot be resolved; nothing was written: ${problems.join('; ')}` : broken().message, result);
225
+ const refused = result.entries.filter(e => e.status === 'refused');
226
+ if (refused.length && refused.every(e => unreadable.has(e))) throw error('E_RUNTIME_ENDPOINT_UNKNOWN', `Harness trust targets cannot be established; nothing was written: ${problems.join('; ')}`, result);
227
+ // Every refused entry names its problem; the generic sentence is a fallback that should not occur.
228
+ if (refused.length) throw error('E_CONFIG_BROKEN', problems.length ? `Harness trust refused; nothing was written: ${problems.join('; ')}` : broken().message, result);
150
229
  return { result, plans };
151
230
  }
152
- export function harnessTrust(root, { harness = 'all', plan = false, env = process.env, launchConfigs = {}, checkpoint = () => {}, metadataProbe = nativeSecurityContext } = {}) {
231
+ export function harnessTrust(root, { harness = 'all', plan = false, env = process.env, launchConfigs = {}, checkpoint = () => {}, metadataProbe = nativeSecurityContext, launch } = {}) {
153
232
  let prepared;
154
- try { prepared = planHarnessTrust(root, { harness, env, launchConfigs, metadataProbe }); }
233
+ try { prepared = planHarnessTrust(root, { harness, env, launchConfigs, metadataProbe, ...(launch ? { launch } : {}) }); }
155
234
  catch (e) { if (e.details?.operation === 'harness-trust') e.details.mode = plan ? 'plan' : 'apply'; throw e; }
156
235
  const { result, plans } = prepared;
157
236
  if (plan) return result;
@@ -22,24 +22,32 @@ import { homedir } from "node:os";
22
22
  const real = (p) => { try { return realpathSync.native(p); } catch { return resolve(p); } };
23
23
  const userHome = (env) => env.HOME || homedir();
24
24
 
25
- /** The variable that moves each harness's configuration directory. */
26
- export const CONFIG_DIR_VAR = { claude: "CLAUDE_CONFIG_DIR", codex: "CODEX_HOME" };
25
+ /** The variable that moves each harness's configuration folder: the three selectors. */
26
+ export const HARNESS_FOLDER_VAR = Object.freeze({ claude: "CLAUDE_CONFIG_DIR", codex: "CODEX_HOME", pi: "PI_CODING_AGENT_DIR" });
27
+ /** Of those, the harnesses that have folder trust. */
28
+ export const CONFIG_DIR_VAR = { claude: HARNESS_FOLDER_VAR.claude, codex: HARNESS_FOLDER_VAR.codex };
27
29
  /** The configuration file `harness` reads under `env`: $CLAUDE_CONFIG_DIR/.claude.json or
28
30
  * ~/.claude.json; $CODEX_HOME/config.toml or ~/.codex/config.toml. */
29
31
  export function harnessConfigFile(harness, env = process.env) {
30
32
  if (harness === "claude") return join(env.CLAUDE_CONFIG_DIR || userHome(env), ".claude.json");
31
33
  return join(env.CODEX_HOME || join(userHome(env), ".codex"), "config.toml");
32
34
  }
33
- /** The configuration directory a launch configuration's `env` gives `harness`: `{dir}` from a
34
- * literal or a {fromEnv} resolved from the host `base`; `{problem}` when the reference is not set
35
- * on this host or the path is not absolute; null when the configuration leaves it to the host. */
36
- export function launchConfigDir(harness, configEnv = {}, base = process.env) {
37
- const name = CONFIG_DIR_VAR[harness];
38
- if (!name || !Object.hasOwn(configEnv || {}, name)) return null;
39
- const v = configEnv[name];
40
- const dir = typeof v === "string" ? v : base[v?.fromEnv];
41
- if (dir === undefined) return { problem: `${name} references ${v?.fromEnv}, not set on this host` };
42
- return isAbsolute(dir) ? { dir } : { problem: `${name} ${JSON.stringify(dir)} is not an absolute path` };
35
+ /** The harness folder a launch configuration's `env` names with `variable` (one of
36
+ * HARNESS_FOLDER_VAR): `{dir}` from a literal or a {fromEnv} resolved from the host `base`;
37
+ * `{problem}` when the reference is not set on this host (with its `fromEnv`) or the path is not
38
+ * absolute; null when the configuration leaves it to the host. The one reader of a launch
39
+ * configuration's folder, for every harness: the trust code (claude, codex) and the pi bridge. It
40
+ * lives here because this module owns the table of which variable moves which harness's folder and
41
+ * reads nothing but files, so core.mjs, harness-trust-write.mjs and pi-bridge.mjs each import it and
42
+ * none imports another for it. pi expands a leading `~` itself, against HOME, so its folder is read
43
+ * that way; Claude Code and Codex take the value as it is. */
44
+ export function launchConfigFolder(variable, configEnv = {}, base = process.env) {
45
+ if (!variable || !Object.hasOwn(configEnv || {}, variable)) return null;
46
+ const v = configEnv[variable];
47
+ const named = typeof v === "string" ? v : base[v?.fromEnv];
48
+ if (named === undefined) return { problem: `${variable} references ${v?.fromEnv}, not set on this host`, fromEnv: v?.fromEnv };
49
+ const dir = variable === HARNESS_FOLDER_VAR.pi ? named.replace(/^~(?=$|\/)/, () => userHome(base)) : named;
50
+ return isAbsolute(dir) ? { dir } : { problem: `${variable} ${JSON.stringify(named)} is not an absolute path` };
43
51
  }
44
52
 
45
53
  /** `dir` and its ancestors, nearest first. */
@@ -147,12 +155,17 @@ export function codexTrustsRoot(root, { env = process.env } = {}) {
147
155
  const shellWord = value => /^[A-Za-z0-9_\/.,:@%+=-]+$/.test(value) ? value : "'" + value.replaceAll("'", "'\"'\"'") + "'";
148
156
 
149
157
  /** The spawn and readiness warning for a launch whose harness configuration does not trust the
150
- * deployment (`file`, the file the launch reads; `problem` when that file cannot be resolved);
151
- * null when `covered`, or for a harness without folder trust. A missing root entry does not
152
- * prove the harness will prompt (a native gate may skip it), so this says only what the file
153
- * lacks, and the one operator command that writes it (never run by readiness or a launch). */
154
- export function harnessTrustWarning({ harness, root, file, problem, covered }) {
158
+ * deployment (`file`, the file the launch reads, and `from`, where the launch gets the variable
159
+ * that selects it; `problem` when the launch configuration does not resolve it); null when
160
+ * `covered`, or for a harness without folder trust. A missing root entry does not prove the
161
+ * harness will prompt (a native gate may skip it), so this says only what the file lacks, and the
162
+ * one operator command that writes it (never run by readiness or a launch). `unreadable` (why,
163
+ * and what would make it readable): the environment of the launch's pane could not be read, so
164
+ * which file the launch will read is not known; the warning then says that, and nothing about
165
+ * trust. */
166
+ export function harnessTrustWarning({ harness, root, file, from, problem, unreadable, covered }) {
155
167
  if (covered || !Object.hasOwn(CONFIG_DIR_VAR, harness)) return null;
168
+ if (unreadable) return `${harness} folder trust: the configuration file this launch will read could not be established (${unreadable}); nothing is said about its trust`;
156
169
  if (problem) return `${harness} folder trust is not established: ${problem}`;
157
- return `${harness} folder trust is not established in ${file}: oats harness trust --dir ${shellWord(root)}`;
170
+ return `${harness} folder trust is not established in ${file}${from ? ` (${from})` : ""}: oats harness trust --dir ${shellWord(root)}`;
158
171
  }
@@ -11,12 +11,14 @@
11
11
  * block or config levels, and there is no `trusted` check: declaring a package
12
12
  * in `packages:` is the trust decision. */
13
13
  import { spawnSync } from "node:child_process";
14
- import { accessSync, constants as fsConstants, existsSync, readFileSync, realpathSync, statSync } from "node:fs";
14
+ import { accessSync, constants as fsConstants, existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
15
15
  import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
16
- import { capabilityManifests, kernelBin, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
16
+ import { capabilityManifests, skillEntriesIn, kernelBin, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, previewLaunchEnvironment, removedLaunchEnv, homeDeclaredLaunchEnv, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
17
17
  import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests, soulsOffered } from "./instance-resolution.mjs";
18
18
  import { declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
19
- import { kernelCompatibility } from "./resolve.mjs";
19
+ import { kernelCompatibility, unsafeRelPath } from "./resolve.mjs";
20
+ import { compareCodepoints, decodeText, FILES_PER_SKILL, SKILL_DOC_BUDGET, skillDocDescription, TEXT_LIMIT } from "./capability-show.mjs";
21
+ import { readFileHead } from "./bounded-read.mjs";
20
22
  import { discoveredTeamKeys, isRemovedTeamKeys, isTeamRefusal, recordedTeams, reportRows, soulKeyOf, teamKeyOf, soulTeams, teamModel, teamProblems } from "./teams.mjs";
21
23
  import { launchLayers, launchReport } from "./launch-preference.mjs";
22
24
  import { loadLocal } from "./workspace.mjs";
@@ -41,7 +43,7 @@ const real = (p) => { try { return realpathSync(p); } catch { return resolve(p);
41
43
  /** A resolution refusal that is a readiness FACT (the soul cannot resolve as the
42
44
  * lock stands), not a failure to answer: reported as a failing `installed` item —
43
45
  * or, for a refusal of the soul's teams (isTeamRefusal), as a team item in `configured`. */
44
- const RESOLUTION_FACTS = new Set(["E_PACKAGE_MISSING", "E_PACKAGE_INTEGRITY", "E_CAPABILITY_MISSING", "E_LOCK_SCHEMA", "E_REQUIREMENT_INACTIVE"]);
46
+ const RESOLUTION_FACTS = new Set(["E_PACKAGE_MISSING", "E_PACKAGE_INTEGRITY", "E_CAPABILITY_MISSING", "E_LOCK_SCHEMA"]);
45
47
  const isResolutionFact = (e) => RESOLUTION_FACTS.has(e?.code) || isTeamRefusal(e);
46
48
 
47
49
  /** Is `name` an executable on PATH? (manifest `requires`, no shell). */
@@ -265,7 +267,9 @@ function soulRow(t) {
265
267
  declarations: declarationsOf(s.definition), declarationProblems: s.problems,
266
268
  instructions: s.soulDir ? readTextCapped(join(s.soulDir, "AGENTS.md")) : null,
267
269
  // Feature soul-composed-instructions: only on a soul target that asked (inspect --instructions).
268
- ...(t.kind === "soul" && t.composedInstructions !== undefined ? { composedInstructions: t.composedInstructions } : {}) };
270
+ ...(t.kind === "soul" && t.composedInstructions !== undefined ? { composedInstructions: t.composedInstructions } : {}),
271
+ // Feature soul-skills: only on a soul target that asked (inspect --skills).
272
+ ...(t.kind === "soul" && t.skills !== undefined ? { skills: t.skills } : {}) };
269
273
  }
270
274
 
271
275
  /** The soul target with `composedInstructions` (feature soul-composed-instructions): the AGENTS.md a
@@ -284,6 +288,137 @@ export async function withComposedInstructions(t, { compose = composeSoulInstruc
284
288
  }
285
289
  }
286
290
 
291
+ // ---------- the soul's own skills (feature soul-skills) ----------
292
+ /** The whole `skills` field carries at most this many UTF-8 bytes of `text`, summed in answer order. */
293
+ export const SOUL_SKILLS_TEXT_BUDGET = 1024 * 1024;
294
+ const SKILLS_UNREADABLE = "soul-skills-unreadable", SKILL_FILES_UNREADABLE = "soul-skill-files-unreadable";
295
+ /** What readFileHead refuses: not a regular file, or not the file lstat found. */
296
+ const HEAD_REFUSALS = new Set(["invalid-declaration", "integrity-drift"]);
297
+ /** An entry the listing refuses, or a file it lists and cannot read safely: that skill's files are not listed. */
298
+ class Unlisted extends Error {}
299
+ /** A name that is not a safe relative path component (unsafeRelPath), or holds a control character. */
300
+ const unsafeName = (name) => unsafeRelPath(name) || /[\x00-\x1f\x7f]/.test(name);
301
+ /** A filesystem error (it has a syscall), a readFileHead refusal or one of ours, as the short reason a problem
302
+ * gives; anything else is a defect and is thrown. */
303
+ function unlistedReason(e, path) {
304
+ if (e instanceof Unlisted) return e.message;
305
+ if (typeof e?.syscall === "string") return `could not read ${path} (${e.code ?? e.syscall})`;
306
+ if (HEAD_REFUSALS.has(e?.code)) return `could not read ${path} (${e.message})`;
307
+ throw e;
308
+ }
309
+
310
+ /* Containment, by the kernel's realpath idiom (manifestPath): every directory is listed, and every file read, only
311
+ * once its realpath lies inside the realpath of its skill, and the skill's inside the soul's. No symlink is ever
312
+ * followed: the walk takes entry types from readdir (lstat semantics), and a file is read through readFileHead
313
+ * (lstat a regular file, open O_NOFOLLOW|O_NONBLOCK, fstat the same file).
314
+ * The residual race, deliberately left: an ancestor directory swapped for a symlink in the instant between a check
315
+ * and the open can redirect a read (O_NOFOLLOW guards the last component only; Node has no openat). Only someone
316
+ * who can write the deployment's agents/ tree can do that, and that person already controls the soul copy and
317
+ * every instance's AGENTS.md. */
318
+ function insideOf(real, root, shown, where) {
319
+ const rel = relative(root, real);
320
+ if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Unlisted(`${shown} resolves outside ${where}`);
321
+ return real;
322
+ }
323
+
324
+ /** Every regular file under the skill directory `dir` (`path` relative to the soul), recursively: paths relative
325
+ * to it, in codepoint order. A symlink (never followed), FIFO, socket or device is not listed; an entry with an
326
+ * unsafe name refuses the listing. */
327
+ function skillFilePaths(dir, realSkill, path) {
328
+ const out = [];
329
+ const walk = (abs, rel) => {
330
+ insideOf(realpathSync(abs), realSkill, rel ? `${path}/${rel}` : path, "its skill");
331
+ const dirs = [];
332
+ for (const e of readdirSync(abs, { withFileTypes: true })) {
333
+ const entry = rel ? `${rel}/${e.name}` : e.name;
334
+ if (unsafeName(e.name)) throw new Unlisted(`${JSON.stringify(entry)} is not a safe file name`);
335
+ if (e.isDirectory()) dirs.push(e.name);
336
+ else if (e.isFile()) out.push(entry);
337
+ }
338
+ for (const d of dirs) walk(join(abs, d), rel ? `${rel}/${d}` : d);
339
+ };
340
+ walk(dir, "");
341
+ return out.sort(compareCodepoints);
342
+ }
343
+
344
+ /** A listed file of the skill, proved inside it, read up to `max` bytes. → { bytes, size } */
345
+ function readSkillFile(dir, realSkill, path, rel, max) {
346
+ const abs = join(dir, ...rel.split("/"));
347
+ insideOf(realpathSync(abs), realSkill, `${path}/${rel}`, "its skill");
348
+ return readFileHead(abs, max);
349
+ }
350
+
351
+ /** One skill's row. Its files are listed and read in order against `budget` ({used, spent}); the budget is
352
+ * charged only when the skill's files are listed (a `files: null` skill is not in the answer's text). */
353
+ function soulSkillRow(soulDir, realSoul, { name, src }, budget) {
354
+ const path = relative(soulDir, src).split(sep).join("/");
355
+ const row = { name, path, description: null, files: null, filesTruncated: false };
356
+ const problem = (reason) => ({ row, problem: { code: SKILL_FILES_UNREADABLE, message: `skills: ${path}: could not list its files: ${reason}` } });
357
+ if (unsafeName(name)) return problem(`${JSON.stringify(name)} is not a safe skill name`);
358
+ let realSkill;
359
+ try { realSkill = insideOf(realpathSync(src), realSoul, path, "the soul"); } catch (e) { return problem(unlistedReason(e, path)); }
360
+ // The description by capabilities show's rule (skillDocDescription): SKILL.md read up to SKILL_DOC_BUDGET; null
361
+ // when it cannot be read, is a symlink, is binary or is larger.
362
+ let doc = null;
363
+ try { doc = readSkillFile(src, realSkill, path, "SKILL.md", SKILL_DOC_BUDGET); } catch (e) { unlistedReason(e, `${path}/SKILL.md`); }
364
+ if (doc) row.description = skillDocDescription(doc.bytes, doc.size);
365
+ let paths;
366
+ try { paths = skillFilePaths(src, realSkill, path); } catch (e) { return problem(unlistedReason(e, path)); }
367
+ let { used, spent } = budget;
368
+ const files = [];
369
+ for (const rel of paths.slice(0, FILES_PER_SKILL)) {
370
+ const filePath = `${path}/${rel}`;
371
+ let read;
372
+ // TEXT_LIMIT + 4 bytes: one past the bytes decodeText examines, so it answers on the head as on the whole file.
373
+ try { read = rel === "SKILL.md" && doc ? doc : readSkillFile(src, realSkill, path, rel, spent ? 0 : TEXT_LIMIT + 4); }
374
+ catch (e) { return problem(unlistedReason(e, filePath)); }
375
+ const omitted = { path: filePath, bytes: read.size, text: null, binary: false, truncated: false, omitted: true };
376
+ if (spent) { files.push(omitted); continue; }
377
+ const decoded = decodeText(read.bytes);
378
+ const cost = decoded.text === null ? 0 : Buffer.byteLength(decoded.text, "utf8");
379
+ if (used + cost > SOUL_SKILLS_TEXT_BUDGET) { spent = true; files.push(omitted); continue; }
380
+ used += cost;
381
+ files.push({ path: filePath, bytes: read.size, ...decoded });
382
+ }
383
+ Object.assign(budget, { used, spent });
384
+ return { row: { ...row, files, filesTruncated: paths.length > FILES_PER_SKILL }, problem: null };
385
+ }
386
+
387
+ /** The soul's own skills as `inspect --soul --skills` reports them: → { skills, problems }. Exactly the skills a
388
+ * spawn copies (spawn's skillEntriesIn, run strict, so a skill it cannot examine is a problem, not a missing
389
+ * skill), sorted by name in codepoint order; `[]` without a `skills/` directory; null, with a problem, when they
390
+ * cannot be listed (a symlinked `skills/` included, which is never followed). Read-only. */
391
+ export function soulSkills(soulDir) {
392
+ const unreadable = (reason) => ({ skills: null, problems: [{ code: SKILLS_UNREADABLE, message: `skills: ${reason}` }] });
393
+ const tree = join(soulDir, "skills");
394
+ try {
395
+ let st;
396
+ try { st = lstatSync(tree); } catch (e) { if (e?.code === "ENOENT") return { skills: [], problems: [] }; throw e; }
397
+ if (st.isSymbolicLink()) return unreadable("the soul's skills/ is a symbolic link, which is not followed");
398
+ if (!st.isDirectory()) return unreadable("the soul's skills is not a directory");
399
+ const realSoul = realpathSync(soulDir);
400
+ insideOf(realpathSync(tree), realSoul, "skills/", "the soul");
401
+ const budget = { used: 0, spent: false };
402
+ const skills = [], problems = [];
403
+ for (const entry of skillEntriesIn(tree, { strict: true }).sort((a, b) => compareCodepoints(a.name, b.name))) {
404
+ const { row, problem } = soulSkillRow(soulDir, realSoul, entry, budget);
405
+ skills.push(row);
406
+ if (problem) problems.push(problem);
407
+ }
408
+ return { skills, problems };
409
+ } catch (e) { return unreadable(unlistedReason(e, "skills/")); }
410
+ }
411
+
412
+ /** The soul target with `skills` (feature soul-skills): the soul's own skills from the soul copy inspect
413
+ * materialised (soulSkills). Null when that copy failed (its copyError already says why) or the soul does not
414
+ * resolve; reading problems are `skillsProblems`. */
415
+ export async function withSkills(t) {
416
+ if (t.kind !== "soul") return t;
417
+ if (t.soul.copyError || !t.soul.soulDir || !t.prepared) return { ...t, skills: null };
418
+ const { skills, problems } = soulSkills(t.soul.soulDir);
419
+ return { ...t, skills, ...(problems.length ? { skillsProblems: problems } : {}) };
420
+ }
421
+
287
422
  /** `oats inspect --json` on the workspace model. */
288
423
  /** What the target's capabilities declare and this kernel ignores (an unknown hook event):
289
424
  * [{ code, capability, path, message }]. A soul's from its resolution, where each manifest is read
@@ -322,7 +457,7 @@ export function inspectDocument(t, { kernel }) {
322
457
  launchConfig: m.launch?.launchConfig ?? null, launchConfigDefault: m.launch?.launchConfigDefault === true, launched: !!m.launched, createdAt: m.createdAt || null,
323
458
  resolution: m.workspace?.resolution ?? null, soulDir: t.soul.soulDir, instructions: { ...readTextCapped(join(t.home, "AGENTS.md")), sources: m.instructions || [] } } : null,
324
459
  ...(m ? { identity: servedIdentityOf(m) } : {}),
325
- problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.composedInstructionsProblem ? [t.composedInstructionsProblem] : []), ...(t.discoveryError ? [t.discoveryError] : []),
460
+ problems: [...t.soul.problems, ...(t.soul.copyError ? [t.soul.copyError] : []), ...(t.composedInstructionsProblem ? [t.composedInstructionsProblem] : []), ...(t.skillsProblems || []), ...(t.discoveryError ? [t.discoveryError] : []),
326
461
  ...t.modules.filter((x) => !x.manifest).map((x) => ({ code: "module-missing", message: `${x.name} is recorded but its module copy has no readable oats.json`, capability: x.name })),
327
462
  ...capabilities.filter((c) => !c.compatibility.ok).map((c) => ({ code: "capability-incompatible", message: `${c.id} requires oats ${c.compatibility.range}; this kernel is ${c.compatibility.kernel} (re-spawn from the deployment with a release whose range admits it)`, capability: c.id, range: c.compatibility.range, kernel: c.compatibility.kernel }))],
328
463
  warnings: targetWarnings(t),
@@ -365,9 +500,15 @@ function launchItems(t) {
365
500
  /** `harness-trust` (#341, #886): whether the configuration file the claude or codex session this
366
501
  * subject launches reads trusts the deployment: a passing item naming that file, or a warning that
367
502
  * folder trust is not established there (a missing root entry does not prove a prompt). The file is
368
- * the launch's own: an instance's recorded harness, home and recorded launch env; a soul's selected
369
- * launch configuration, for a home under the agents root. Reads, never writes, the harness's
370
- * configuration (lib/harness-trust.mjs). */
503
+ * the launch's own (#993): the one its launch configuration names (an instance's recorded launch
504
+ * env; a soul's selected launch configuration, for a home under the agents root), else the one the
505
+ * pane it would run in selects, as a command that only reads can know it (core.mjs
506
+ * previewLaunchEnvironment): never this process's own. Two answers are `unknown`, each with its
507
+ * sentence in `reason`. No pane's environment is established (no OATS tmux server runs): `file` is
508
+ * what this process would read, the reason says what it holds and names what was read instead.
509
+ * The pane's environment could not be read: `file` is null, and the reason says which name, read
510
+ * from where, and nothing about trust. Reads, never writes, the harness's configuration
511
+ * (lib/harness-trust.mjs). */
371
512
  function folderTrustItems(t) {
372
513
  const harness = t.home ? t.meta?.harness : t.launch?.effective?.harness;
373
514
  if (harness !== "claude" && harness !== "codex") return [];
@@ -377,8 +518,16 @@ function folderTrustItems(t) {
377
518
  const config = t.home ? null : (() => { try { return launchConfigsAt(t.deployment)[name]; } catch { return undefined; } })();
378
519
  const yolo = t.home ? (t.meta?.yolo ?? t.meta?.launch?.yolo) : config?.yolo;
379
520
  const configEnv = t.home ? t.meta?.launch?.env : config?.env;
380
- const trust = launchFolderTrust({ harness, home: t.home ?? t.agentsRoot, meta, yolo, configEnv: obj(configEnv) ? configEnv : {}, launchConfig: name });
381
- return [item("launch", trust.warning ? "fail" : "pass", { required: false, producer: "harness folder trust", code: "harness-trust", reason: trust.warning,
521
+ const env = obj(configEnv) ? configEnv : {};
522
+ // A home's launch removes what its providers declare and its recorded payload leaves out (core.mjs
523
+ // removedLaunchEnv): a selector among them is not the pane's.
524
+ const recipe = t.home && obj(t.meta?.launch) ? t.meta.launch : null;
525
+ const removed = recipe ? removedLaunchEnv({ declared: homeDeclaredLaunchEnv(t.meta, recipe, Object.fromEntries((t.modules || []).filter((m) => m.manifest).map((m) => [m.name, m.manifest]))), hooksEnv: obj(recipe.hooks?.env) ? recipe.hooks.env : {}, configEnv: env }) : [];
526
+ const trust = launchFolderTrust({ harness, home: t.home ?? t.agentsRoot, meta, yolo, configEnv: env, launchConfig: name,
527
+ launch: previewLaunchEnvironment({ configEnv: env, configName: name, removed, ...(t.home ? { home: t.home, meta: t.meta } : { deployment: t.deployment }) }) });
528
+ // Not the pane's: what this process would read says nothing certain about the launch.
529
+ const unestablished = trust.note ? trust.warning ?? `${harness} folder trust is established in ${trust.file}; that file is this process's, not known to be the one a launch will read: ${trust.note}` : null;
530
+ return [item("launch", trust.unreadable || unestablished ? "unknown" : trust.warning ? "fail" : "pass", { required: false, producer: "harness folder trust", code: "harness-trust", reason: unestablished ?? trust.warning,
382
531
  harness, file: trust.file, deployment: t.deployment })];
383
532
  }
384
533
  /** `launch-prompt` (a warning): this home's last start blocked at a prompt that equals no