@awebai/oats 0.51.0 → 0.53.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 (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
@@ -1,18 +1,8 @@
1
1
  /** Launch-only tmux observations. Exact visible bytes, never scrollback or
2
- * joined wrapped lines; both identity/geometry reads must agree. */
2
+ * joined wrapped lines; both identity/geometry reads must agree. The transport
3
+ * never resizes: matching is width-independent. */
3
4
  import { execFileSync } from 'node:child_process';
4
5
  import { isAbsolute } from 'node:path';
5
- import { performance } from 'node:perf_hooks';
6
-
7
- function budget(timeout) {
8
- if (!Number.isFinite(timeout) || timeout <= 0) throw new Error('invalid launch timeout');
9
- const deadline = performance.now() + timeout;
10
- return () => {
11
- const left = deadline - performance.now();
12
- if (left <= 0) throw new Error('launch geometry timeout');
13
- return left;
14
- };
15
- }
16
6
 
17
7
  export const LAUNCH_PANE_FORMAT = '#{window_id}\t#{pane_id}\t#{pane_pid}';
18
8
  const SNAPSHOT_FORMAT = `${LAUNCH_PANE_FORMAT}\t#{pane_width}\t#{pane_height}\t#{window_panes}`;
@@ -28,7 +18,6 @@ export function launchPromptTransport(io) {
28
18
  encoding: 'utf8', timeout: Math.max(1, Math.floor(timeout)), killSignal: 'SIGKILL', maxBuffer: 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
29
19
  }));
30
20
  };
31
- const pins = new WeakMap();
32
21
  const transport = {
33
22
  // Called only before this invocation respawns an already-owned exact pane.
34
23
  identity(socket, paneId) {
@@ -49,49 +38,6 @@ export function launchPromptTransport(io) {
49
38
  if (lines.length !== Number(fields[4])) throw new Error('incomplete visible capture');
50
39
  return { ...actual, width: Number(fields[3]), height: Number(fields[4]), text: lines.join('\n') + '\n' };
51
40
  },
52
- // Pin only an exclusively owned window. Tokens are invocation-local and
53
- // cannot be reconstructed from an event receipt or another transport.
54
- pin(target, geometry, timeout) {
55
- if (!Number.isSafeInteger(geometry?.width) || geometry.width < 1 || !Number.isSafeInteger(geometry?.height) || geometry.height < 1) throw new Error('invalid launch geometry');
56
- const remaining = budget(timeout);
57
- const before = transport.snapshot(target, remaining());
58
- const windowSize = run(target, ['show-options', '-w', '-q', '-v', '-t', target.windowId, 'window-size'], remaining()).trim();
59
- if (!['', 'largest', 'smallest', 'manual', 'latest'].includes(windowSize)) throw new Error('invalid window-size policy');
60
- // An empty option is inherited; restoration must unset our local override.
61
- const token = Object.freeze({ previous: Object.freeze({ width: before.width, height: before.height, windowSize }) });
62
- pins.set(token, { target: { ...target }, previous: token.previous });
63
- try {
64
- transport.snapshot(target, remaining());
65
- run(target, ['set-option', '-w', '-t', target.windowId, 'window-size', 'manual', ';',
66
- 'resize-window', '-t', target.windowId, '-x', String(geometry.width), '-y', String(geometry.height)], remaining());
67
- const after = transport.snapshot(target, remaining());
68
- if (after.width !== geometry.width || after.height !== geometry.height) throw new Error('launch geometry pin failed');
69
- return token;
70
- } catch (error) {
71
- // A failed command may already have changed the option/dimensions.
72
- try { transport.restore(target, token, 3000); error.geometryRestored = true; }
73
- catch { error.geometryRestoreFailed = true; }
74
- throw error;
75
- }
76
- },
77
- restore(target, token, timeout) {
78
- const remaining = budget(timeout);
79
- const saved = pins.get(token);
80
- if (!saved || ['socket', 'windowId', 'paneId', 'pid'].some(key => String(saved.target[key]) !== String(target[key]))) throw new Error('invalid launch geometry token');
81
- // Consume even on failure: no retries can resize a replacement process.
82
- pins.delete(token);
83
- transport.snapshot(target, remaining());
84
- const { width, height, windowSize } = saved.previous;
85
- const reset = windowSize === ''
86
- ? ['set-option', '-w', '-u', '-t', target.windowId, 'window-size']
87
- : ['set-option', '-w', '-t', target.windowId, 'window-size', windowSize];
88
- run(target, ['set-option', '-w', '-t', target.windowId, 'window-size', 'manual', ';',
89
- 'resize-window', '-t', target.windowId, '-x', String(width), '-y', String(height), ';', ...reset], remaining());
90
- const after = transport.snapshot(target, remaining());
91
- const restoredPolicy = run(target, ['show-options', '-w', '-q', '-v', '-t', target.windowId, 'window-size'], remaining()).trim();
92
- if (after.width !== width || after.height !== height || restoredPolicy !== windowSize) throw new Error('launch geometry restoration failed');
93
- return { status: 'restored' };
94
- },
95
41
  send(target, key, timeout) {
96
42
  if (key !== 'Enter') throw new Error('invalid launch action');
97
43
  run(target, ['send-keys', '-t', target.paneId, key], timeout);
@@ -1,28 +1,41 @@
1
1
  import { lstatSync, realpathSync } from "node:fs";
2
2
  import { createHash } from "node:crypto";
3
3
  import { performance } from "node:perf_hooks";
4
+ import { DEV_CHANNEL_ENTRIES, FLAG_IGNORED_ENTRIES, matchDevChannelEntry, matchFlagIgnoredEntry, devChannelDifference, normalizeScreen, showsClaudeSession } from "./launch-prompt-fixtures.mjs";
5
+ import { hasClaudeQuestionMarker } from "./launch-prompt-completion.mjs";
4
6
 
5
7
  const LIMIT = 30000;
6
8
  const INTERVAL = 100;
9
+ // The settle window. Before the Enter, an unknown screen is a verdict only once it has held this
10
+ // long unchanged: Claude paints transient frames while it starts (a logo mid-animation, a renderer
11
+ // notice) and, under load, holds one for a second or more. After the Enter, a start completes only
12
+ // once its captures have been clean (non-blank, no question marker, no entry) this long in a row,
13
+ // the screen free to change: a working session repaints all the time. No key is sent while waiting.
14
+ const SETTLE = 2000;
15
+ // The confirmation may stay painted briefly after its Enter; seen again after
16
+ // this long, it came back.
17
+ const RETURN = 2000;
18
+ const OBSERVATION_TIMEOUT = "blocked: observation timeout";
19
+ /** Whether a recorded reason says the screen never settled within the bound, so no prompt
20
+ * was established (a failed evidence write appends to the reason, never changes its start). */
21
+ export const neverSettled = (reason) => typeof reason === "string" && reason.startsWith(OBSERVATION_TIMEOUT);
7
22
  const digest = (text) => createHash("sha256").update(text).digest("hex");
8
23
  const sameTarget = (a, b, pid = true) => a && b && ["socket", "windowId", "paneId", ...(pid ? ["pid"] : [])].every(k => String(a[k]) === String(b[k]));
9
24
  const validTarget = t => t && typeof t.socket === "string" && t.socket.length > 0 && /^@\d+$/.test(t.windowId) && /^%\d+$/.test(t.paneId) && /^[1-9]\d*$/.test(String(t.pid));
10
25
  const wait = ms => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
11
26
 
12
- /** Private, single-invocation authority. Production fixtures must pass the separate qualification adapter.
13
- * Transport captures visible bytes only and independently verifies ownership and
14
- * stable geometry around capture. Every call receives the remaining deadline.
15
- * Synthetic fixtures are injectable for tests; accepting a real version/platform
16
- * fixture is a separate review gate. A fixture binds an exact home and complete
17
- * frames (text, width, height), never a substring or whitespace normalization.
27
+ /** Private, single-invocation authority over the development-channel
28
+ * confirmation in the one pane this start created. The caller constructs it only
29
+ * when the launch argv engages it (launchPromptEngages). It sends at most one
30
+ * fixed Enter, and only while the normalized screen EQUALS a tolerance entry.
31
+ * A screen whose notice block EQUALS a flag-ignored entry means Claude ignored
32
+ * the flag and shows no confirmation: that start ends flag-ignored, with no key.
33
+ * Transport captures visible bytes only and independently verifies ownership
34
+ * around capture. Every call receives the remaining deadline.
18
35
  * audit receives launch-prompt event data and returns appendEvent's checked result.
19
36
  */
20
- export function createLaunchPromptController({ home, startId, harness, policy = {}, transport, audit, retainFrame, classifyCompletion,
21
- now = () => performance.now(), sleep = wait, fixtures = [], geometry, validateExecutable, expectedHomeIdentity }) {
22
- const selectedHarness = typeof harness === "string" ? { name: harness } : { ...harness };
23
- const consent = { ...policy };
24
- // Copy fixture data so a caller cannot change signatures during an answer.
25
- const accepted = structuredClone(fixtures);
37
+ export function createLaunchPromptController({ home, startId, transport, audit, retainFrame, entries = DEV_CHANNEL_ENTRIES, flagIgnoredEntries = FLAG_IGNORED_ENTRIES,
38
+ claudeVersion = "unknown", claudeVersionSource = "unknown", now = () => performance.now(), sleep = wait, expectedHomeIdentity }) {
26
39
  let identity;
27
40
  try {
28
41
  const st = lstatSync(home);
@@ -39,21 +52,17 @@ export function createLaunchPromptController({ home, startId, harness, policy =
39
52
  const st = lstatSync(home);
40
53
  if (!st.isDirectory() || st.dev !== identity.dev || st.ino !== identity.ino || realpathSync(home) !== home) throw new Error("home identity changed");
41
54
  }
42
- function checkAuthority() {
43
- checkHome();
44
- if (validateExecutable && validateExecutable() !== true) throw new Error("launch executable changed");
45
- }
46
55
  function remaining() {
47
56
  const left = deadline - now();
48
57
  if (!(left > 0)) throw new Error("observation timeout");
49
58
  return Math.max(1, Math.ceil(left));
50
59
  }
51
60
  function capture(t) {
52
- checkAuthority();
61
+ checkHome();
53
62
  if (!validTarget(t)) throw new Error("invalid target");
54
63
  const screen = transport.snapshot(t, remaining());
55
64
  remaining();
56
- checkAuthority();
65
+ checkHome();
57
66
  if (!sameTarget(t, screen) || !Number.isInteger(screen.width) || screen.width < 1 || !Number.isInteger(screen.height) || screen.height < 1 || typeof screen.text !== "string") throw new Error("target or geometry changed");
58
67
  lastText = screen.text;
59
68
  return { ...screen };
@@ -63,7 +72,7 @@ export function createLaunchPromptController({ home, startId, harness, policy =
63
72
  try {
64
73
  checkHome();
65
74
  result = audit({ home, startId, socket: target?.socket, windowId: target?.windowId,
66
- paneId: target?.paneId, pid: target?.pid, consentSource: consent.consentSource ?? null, ...data });
75
+ paneId: target?.paneId, pid: target?.pid, claudeVersion, claudeVersionSource, ...data });
67
76
  } catch { auditFailed = true; return false; }
68
77
  // Preserve actual appendEvent paths, including partial-log availability.
69
78
  if (result && Array.isArray(result.results)) receipts.push({ ok: result.ok === true, ...(result.row ? { row: structuredClone(result.row) } : {}), results: result.results.map(r => ({ ...r })) });
@@ -81,20 +90,14 @@ export function createLaunchPromptController({ home, startId, harness, policy =
81
90
  status = "incomplete";
82
91
  reason = "launch prompt audit failed";
83
92
  }
84
- terminal = { status, answers: answers.map(a => ({ ...a })), reason, receipt: receipts };
93
+ // A blocked result carries what differed, and whether Claude's session UI was
94
+ // shown, for the readiness warning (R2).
95
+ terminal = { status, answers: answers.map(a => ({ ...a })), reason, receipt: receipts,
96
+ ...(status === "flag-ignored" ? { signatureId: extra.signatureId } : {}),
97
+ ...(status === "blocked" && extra.differed ? { differed: extra.differed } : {}),
98
+ ...(status === "blocked" && extra.claudeSessionShown ? { claudeSessionShown: true } : {}) };
85
99
  return terminal;
86
100
  }
87
- function matching(screen) {
88
- const candidates = [];
89
- for (const fixture of accepted) {
90
- if (!fixture.id || fixture.home !== home || fixture.harness !== selectedHarness.name || !fixture.version || fixture.version !== selectedHarness.version || !fixture.platform || fixture.platform !== selectedHarness.platform) continue;
91
- for (const frame of fixture.frames ?? []) {
92
- if (frame.text === screen.text && frame.width === screen.width && frame.height === screen.height
93
- && JSON.stringify(frame.after) === JSON.stringify(answers.map(a => a.class))) candidates.push({ fixture, frame });
94
- }
95
- }
96
- return candidates.length === 1 ? candidates[0] : null;
97
- }
98
101
  const exact = (a, b) => sameTarget(a, b) && a.width === b.width && a.height === b.height && a.text === b.text;
99
102
  function retain(screen, outcome, recognition) {
100
103
  try {
@@ -102,82 +105,87 @@ export function createLaunchPromptController({ home, startId, harness, policy =
102
105
  screen: { text: screen.text, width: screen.width, height: screen.height }, outcome, recognition })?.ok === true;
103
106
  } catch { return false; } // No raw text, OS diagnostic or private receipt escapes.
104
107
  }
108
+ // A loud miss: the receipt row says what differed; private evidence holds the
109
+ // exact compared screen, never the row.
110
+ // Before any Enter, Claude's running-session banner on the blocked screen says
111
+ // the session may already be up with the flag ignored and its notice hidden.
112
+ function blocked(screen, reason, beforeEnter = false) {
113
+ const sessionShown = beforeEnter && showsClaudeSession(screen.text);
114
+ if (!retain(screen, "blocked", "unmatched")) reason += "; private launch evidence retention failed";
115
+ return finish("blocked", reason, { differed: devChannelDifference(screen.text, entries), ...(sessionShown ? { claudeSessionShown: true } : {}) });
116
+ }
105
117
  function observe(t, before) {
106
118
  if (used) return terminal ?? { status: "blocked", answers: [], reason: "blocked: launch authority already used", receipt: [] };
107
119
  used = true;
108
120
  target = { ...t };
109
- let fresh = before === undefined, resizeToken;
110
- const wantsGeometry = geometry && Number.isInteger(geometry.width) && geometry.width > 0 && Number.isInteger(geometry.height) && geometry.height > 0
111
- && consent.awebDevelopmentChannel === true
112
- && accepted.some(f => f.home === home && f.harness === selectedHarness.name && f.version === selectedHarness.version && f.platform === selectedHarness.platform
113
- && f.frames?.some(frame => frame.width === geometry.width && frame.height === geometry.height));
114
- let geometryHandled = !wantsGeometry;
115
- function incompleteCleanup() {
116
- if (!terminal) terminal = { answers: answers.map(a => ({ ...a })), receipt: receipts };
117
- terminal.status = "incomplete";
118
- terminal.reason = "launch prompt geometry restoration incomplete";
119
- }
121
+ // `unknown` is the last non-blank screen before the Enter that equalled no entry: a screen
122
+ // that never settles is an observation timeout at the bound, and says what differed.
123
+ // After the Enter: `clean` is when the current run of clean captures began, `left` whether the
124
+ // confirmation has been off screen since, and `last` the last non-blank screen.
125
+ let fresh = before === undefined, enteredAt, pending, unknown, clean, left = false, last;
126
+ const submitted = () => answers.length === 1 && answers[0].status === "submitted";
120
127
  try {
121
128
  checkHome();
122
129
  if (!validTarget(target)) return finish("blocked", "blocked: invalid target");
123
130
  if (before !== undefined && (!before || !sameTarget(target, before, false) || String(target.pid) === String(before.pid))) return finish("blocked", "blocked: respawn ownership not proven");
124
131
  // Hard iteration bound also protects against a broken injected clock.
125
132
  for (let observations = 0; observations <= LIMIT / INTERVAL; observations++) {
126
- let screen = capture(target);
133
+ const screen = capture(target);
127
134
  if (!fresh) {
128
- // A resize can reflow the *old* prompt into different bytes. Require
129
- // a fresh process screen at the original geometry before pinning.
135
+ // A resize can reflow the *old* prompt into different bytes that still
136
+ // normalize to an entry. Require a fresh process screen at the original geometry.
130
137
  if (screen.width !== before.width || screen.height !== before.height) return finish("blocked", "blocked: respawn geometry changed before fresh screen");
131
138
  if (screen.text !== before.text) fresh = true;
132
139
  }
133
- if (fresh && !geometryHandled) {
134
- geometryHandled = true;
135
- const fields = { action: "pin-geometry", width: geometry.width, height: geometry.height, signatureDigest: digest(screen.text) };
136
- if (!record({ ...fields, status: "attempted" })) return finish("incomplete", "launch prompt audit failed before geometry pin");
137
- checkAuthority();
138
- resizeToken = transport.pin(target, { ...geometry }, remaining());
139
- if (!resizeToken) return finish("incomplete", "launch prompt geometry pin failed");
140
- if (!record({ ...fields, status: "submitted" })) return finish("incomplete", "launch prompt audit failed after geometry pin");
140
+ const reading = normalizeScreen(screen.text);
141
+ if (!fresh || reading === "") {
142
+ // A blank screen restarts any window; after the Enter it also means the confirmation left.
143
+ pending = undefined;
144
+ if (submitted()) { clean = undefined; left = true; }
141
145
  sleep(Math.min(INTERVAL, remaining()));
142
- screen = capture(target);
143
- if (screen.width !== geometry.width || screen.height !== geometry.height) return finish("blocked", "blocked: launch geometry not pinned");
146
+ continue;
144
147
  }
145
- if (!fresh || screen.text.trim() === "") {
148
+ const entry = matchDevChannelEntry(screen.text, entries);
149
+ if (submitted()) {
150
+ // Completion reporting only, never input authority: no key follows.
151
+ last = screen;
152
+ if (entry) {
153
+ // Still painted just after the Enter is waited out; back after leaving, or still there
154
+ // after RETURN, it came back.
155
+ if (left || now() - enteredAt >= RETURN) return blocked(screen, "blocked: repeated or unsupported prompt");
156
+ clean = undefined;
157
+ } else if (hasClaudeQuestionMarker(screen.text)) {
158
+ return blocked(screen, "blocked: unexpected prompt");
159
+ } else {
160
+ left = true;
161
+ clean ??= now();
162
+ if (now() - clean >= SETTLE) {
163
+ if (!retain(screen, "completed", "stable-screen")) return finish("incomplete", "private launch evidence retention failed");
164
+ return finish("completed", "recognized launch boundary", { signatureId: answers[0].signatureId });
165
+ }
166
+ }
146
167
  sleep(Math.min(INTERVAL, remaining()));
147
168
  continue;
148
169
  }
149
- const submitted = answers.length === 1 && answers[0].status === "submitted";
150
- // The initial exact question contains these same markers: completion
151
- // policy is reachable ONLY after its sole key was durably submitted.
152
- const completion = submitted ? classifyCompletion?.(screen) : null;
153
- const match = completion === "blocked" ? null : matching(screen);
154
- if (!match && completion === "completed") {
155
- if (!retain(screen, "completed", "structural")) return finish("incomplete", "private launch evidence retention failed");
156
- return finish("completed", "recognized launch boundary");
157
- }
158
- if (!match) {
159
- let reason = "blocked: unexpected prompt";
160
- if (submitted && screen.width === 110 && screen.height === 35 && retainFrame) {
161
- // This is the exact object just compared, not a later pane capture.
162
- // Private evidence cannot authorize input or change the launch outcome.
163
- if (!retain(screen, "blocked", "unmatched")) reason += "; private launch evidence retention failed";
170
+ if (!entry) {
171
+ // A question beside the notice means someone must answer: that screen is a miss.
172
+ const ignored = !hasClaudeQuestionMarker(screen.text) && matchFlagIgnoredEntry(screen.text, flagIgnoredEntries);
173
+ if (ignored) {
174
+ // Claude ignored the flag and asks nothing: no key, ever.
175
+ if (!retain(screen, "flag-ignored", "notice-block")) return finish("incomplete", "private launch evidence retention failed");
176
+ return finish("flag-ignored", "channels-unavailable", { signatureId: ignored.id });
164
177
  }
165
- return finish("blocked", reason);
166
- }
167
- const { fixture, frame } = match;
168
- const prior = answers.map(a => a.class);
169
- if (frame.kind === "completed") return finish("completed", "recognized launch boundary");
170
- if (frame.kind === "startup") {
178
+ // A screen still being painted keeps changing; an unknown one that
179
+ // holds still for the settle window is a miss, and blocks without any key.
180
+ unknown = screen;
181
+ if (pending?.reading === reading && now() - pending.at >= SETTLE) return blocked(screen, "blocked: unexpected prompt", true);
182
+ if (pending?.reading !== reading) pending = { reading, at: now() };
171
183
  sleep(Math.min(INTERVAL, remaining()));
172
184
  continue;
173
185
  }
174
- const klass = frame.class;
175
- if (frame.kind !== "prompt" || klass !== "awebDevelopmentChannel" || prior.length !== 0) return finish("blocked", "blocked: repeated or unsupported prompt");
176
- if (consent.awebDevelopmentChannel !== true || selectedHarness.name !== "claude" || selectedHarness.developmentChannelEligible !== true) return finish("blocked", "blocked: prompt consent absent");
177
186
  const expected = screen;
178
187
  if (!exact(capture(target), expected)) return finish("blocked", "blocked: prompt changed before input");
179
- const fields = { signatureId: fixture.id, version: fixture.version, platform: fixture.platform,
180
- signatureDigest: digest(expected.text), class: klass, key: "Enter" };
188
+ const fields = { signatureId: entry.id, signatureDigest: digest(expected.text), class: "awebDevelopmentChannel", key: "Enter" };
181
189
  if (!record({ ...fields, status: "attempted" })) {
182
190
  terminal = { status: "incomplete", answers: answers.map(a => ({ ...a })), reason: "launch prompt audit failed", receipt: receipts };
183
191
  return terminal;
@@ -187,7 +195,7 @@ export function createLaunchPromptController({ home, startId, harness, policy =
187
195
  if (!exact(capture(target), expected)) return finish("blocked", "blocked: prompt changed before input", fields);
188
196
  let outcome = "uncertain";
189
197
  try {
190
- checkAuthority();
198
+ checkHome();
191
199
  const sent = transport.send(target, "Enter", remaining());
192
200
  outcome = sent?.status === "submitted" ? "submitted" : sent?.status === "failed" ? "failed" : "uncertain";
193
201
  } catch { /* A thrown send might already have delivered the key. */ }
@@ -196,26 +204,20 @@ export function createLaunchPromptController({ home, startId, harness, policy =
196
204
  return terminal;
197
205
  }
198
206
  if (outcome !== "submitted") return finish("incomplete", `launch prompt input ${outcome}`, fields);
199
- answers.push({ class: klass, signatureId: fixture.id, status: "submitted" });
207
+ answers.push({ class: "awebDevelopmentChannel", signatureId: entry.id, status: "submitted" });
208
+ enteredAt = now();
209
+ pending = undefined;
200
210
  sleep(Math.min(INTERVAL, remaining()));
201
211
  }
202
- return finish("blocked", "blocked: observation timeout");
212
+ throw new Error("observation timeout");
203
213
  } catch (error) {
204
- if (error?.geometryRestored || error?.geometryRestoreFailed) record({ action: "restore-geometry", status: error.geometryRestored ? "submitted" : "failed", reason: "partial pin rollback", signatureDigest: digest(lastText) });
205
- if (error?.geometryRestoreFailed) return finish("incomplete", "launch prompt geometry restoration incomplete");
206
- return finish("blocked", error?.message === "observation timeout" ? "blocked: observation timeout" : "blocked: launch observation failed");
207
- } finally {
208
- if (resizeToken) {
209
- // Restoration is cleanup of our own bounded mutation. Attempt it even
210
- // when auditing failed or the observation deadline expired; the adapter
211
- // independently refuses a replaced process/window before touching it.
212
- const fields = { action: "restore-geometry", previous: resizeToken.previous, signatureDigest: digest(lastText) };
213
- let audited = record({ ...fields, status: "attempted" });
214
- let restored = false;
215
- try { restored = transport.restore(target, resizeToken, 3000)?.status === "restored"; } catch { /* retained incomplete below */ }
216
- audited = record({ ...fields, status: restored ? "submitted" : "failed" }) && audited;
217
- if (!restored || !audited) incompleteCleanup();
218
- }
214
+ if (error?.message !== "observation timeout") return finish("blocked", "blocked: launch observation failed");
215
+ // After the Enter, no complete clean window by the bound: an observation timeout, with the one
216
+ // Enter recorded in the answers.
217
+ if (submitted()) return last ? blocked(last, OBSERVATION_TIMEOUT) : finish("blocked", OBSERVATION_TIMEOUT);
218
+ // A screen still changing at the bound never settled into a prompt: an observation timeout,
219
+ // with what differed and the last screen kept as evidence.
220
+ return unknown ? blocked(unknown, OBSERVATION_TIMEOUT, true) : finish("blocked", OBSERVATION_TIMEOUT);
219
221
  }
220
222
  }
221
223
  return {
@@ -0,0 +1,118 @@
1
+ /**
2
+ * The one way a kernel command rewrites the deployment's oats-local.yaml in place: every command that
3
+ * does calls editLocal, and a new one does too (its callers are whatever imports it: no list is kept here).
4
+ * The file is read as it is NOW, edited (in the parsed document, comments and every other entry kept; or
5
+ * as text, by a command that has a writer of its own for its block), validated against the local schema
6
+ * and by the caller's own check, and renamed in, all under the deployment's local lock, so two writers
7
+ * never drop each other's change.
8
+ */
9
+ import { readFileSync, statSync } from "node:fs";
10
+ import { join } from "node:path";
11
+ import YAML from "yaml";
12
+ import { isJsonSource, parseConfigData } from "./config-data.mjs";
13
+ import { oatsError } from "./errors.mjs";
14
+ import { validateLocal } from "./workspace.mjs";
15
+ import { writeFileAtomic } from "./packages.mjs";
16
+ import { withDirLock } from "./dir-lock.mjs";
17
+
18
+ function fail(code, message, details) { const e = oatsError(code, message, details); e.details = details; return e; }
19
+
20
+ /** The lock every kernel writer of oats-local.yaml holds: in the deployment's kernel state tree, never
21
+ * beside the files. */
22
+ export const localLock = (deployment) => join(deployment, ".agents", "locks", "local.lock");
23
+
24
+ /** No line folding: a value past 80 columns stays on its line (the library's default width re-wraps it). */
25
+ const RENDER = { lineWidth: 0 };
26
+ /** `value` (a document's content, its mappings as Maps so that their keys keep the file's order: an object
27
+ * would move a key like "10" to the front) as two-space JSON. */
28
+ function jsonText(value, indent = "") {
29
+ const inner = `${indent} `;
30
+ const block = (open, close, rows) => (rows.length ? `${open}\n${rows.map((row) => `${inner}${row}`).join(",\n")}\n${indent}${close}` : `${open}${close}`);
31
+ if (value instanceof Map) return block("{", "}", [...value].map(([k, v]) => `${JSON.stringify(String(k))}: ${jsonText(v, inner)}`));
32
+ if (Array.isArray(value)) return block("[", "]", value.map((v) => jsonText(v, inner)));
33
+ return JSON.stringify(value ?? null);
34
+ }
35
+ /** The edited document as the text to write, in the syntax the file has. The kernel reader takes a file
36
+ * that opens with `{` as strict JSON (isJsonSource), and the library's rendering of an edited flow
37
+ * collection is not JSON (a new key comes out unquoted), so such a file is written as JSON. It has no
38
+ * comment to keep; it keeps the order of its keys and its final newline, or the absence of one, and its
39
+ * indentation becomes two spaces. */
40
+ const render = (doc, text) => (isJsonSource(text) ? `${jsonText(doc.toJS({ mapAsMap: true }))}${text.endsWith("\n") ? "\n" : ""}` : doc.toString(RENDER));
41
+
42
+ /** The kernel reader's value of `text`, or the reason it reads none: its decoder's refusals carry their own
43
+ * names, not an `E_` code, so they are caught here and never reach a command as a crash. */
44
+ function decode(text, localPath) {
45
+ try { return { value: parseConfigData(text, { origin: { kind: "local", path: localPath } }).value }; }
46
+ catch (e) { return { failure: String(e?.message ?? e) }; }
47
+ }
48
+
49
+ /** oats-local.yaml as it is now → { text, doc (the editable document), local (the kernel reader's value) }. */
50
+ export function readLocal(localPath) {
51
+ const text = readFileSync(localPath, "utf8");
52
+ const doc = YAML.parseDocument(text, { keepSourceTokens: true });
53
+ if (doc.errors?.length) throw fail("E_WORKSPACE_SCHEMA", `${localPath}: ${doc.errors[0].message}`, { path: localPath });
54
+ const read = decode(text, localPath);
55
+ if (read.failure) throw fail("E_WORKSPACE_SCHEMA", `cannot decode ${localPath}: ${read.failure}; nothing was written`, { path: localPath });
56
+ return { text, doc, local: read.value };
57
+ }
58
+
59
+ /**
60
+ * Rewrite oats-local.yaml. `edit({ text, doc, local })` gets the file AS IT IS NOW (re-read here, never the
61
+ * command's startup snapshot): it may throw a refusal, and it changes `doc` only where the verb's own
62
+ * entries are. It returns null when there is nothing to change, else `{ check? }`, where `check(next)`
63
+ * may refuse the rewritten value (`next`: the kernel reader's parse of the new text) before it is written.
64
+ * The write is compare-and-swap: when the file changed after this read, the edit is redone on the new
65
+ * content (a few times, then E_LOCAL_CHANGED). → { changed, local } (the value now, or as it would be).
66
+ * The edit runs with the lock held, and may run several times: it never ends the process, and what its
67
+ * caller keeps of it is what its last run left.
68
+ *
69
+ * `verb` names the command in the lock's owner record. `plan: true` runs every check and writes nothing:
70
+ * no lock is taken either, so a plan leaves no trace in the deployment.
71
+ *
72
+ * What is written is the YAML library's rendering of the edited document (RENDER): every entry the edit did
73
+ * not touch keeps its value and its comments. It is not a byte copy: the library pads a flow collection
74
+ * (`[a, b]` comes back `[ a, b ]`) and indents by two. A file written as JSON stays JSON (render).
75
+ * Text the kernel reader would not decode is never written: that is E_WORKSPACE_SCHEMA, as an invalid value is.
76
+ *
77
+ * An edit that has a writer of its own returns `{ text, check? }` instead, made from the `text` it was
78
+ * given: that text is written as it is and the document is not rendered, so every byte the edit left alone
79
+ * stays. It is held to the same loop (the kernel reader, the local schema, `check`, compare-and-swap, the
80
+ * rename), and the text it was given, returned, is nothing to write: `changed: false`.
81
+ *
82
+ * Without `plan` the whole read-compare-write runs under the deployment's local lock (localLock), so among
83
+ * its writers the compare and the rename are one step: a conditional write sees every earlier one.
84
+ *
85
+ * The write replaces the file (a sibling temporary file, renamed in): no reader sees half of it, and the
86
+ * new file has the permission bits of the one it replaces, from before its first byte is written. A link
87
+ * at that path is replaced too, by a regular file with its target's bits (writeFileAtomic never writes
88
+ * through one): the target is left as it was.
89
+ */
90
+ export function editLocal(ctx, { verb, plan = false }, edit) {
91
+ if (plan) return editLocalLocked(ctx, { plan }, edit);
92
+ const lock = localLock(ctx.deployment);
93
+ return withDirLock(lock, `${verb} on ${ctx.localPath}`, () => editLocalLocked(ctx, { plan }, edit), {
94
+ retryMs: 5000,
95
+ busy: (why) => fail("E_LOCAL_BUSY", `${ctx.localPath} is being edited by another oats process (the lock ${lock}: ${why}); if no oats command that edits this file is running, remove ${lock} and retry; nothing was written`, { path: ctx.localPath, lock }),
96
+ });
97
+ }
98
+ function editLocalLocked(ctx, { plan }, edit) {
99
+ for (let attempt = 0; attempt < 5; attempt++) {
100
+ const { text, doc, local: current } = readLocal(ctx.localPath);
101
+ const step = edit({ text, doc, local: current });
102
+ if (!step) return { changed: false, local: current };
103
+ const own = typeof step.text === "string";
104
+ const out = own ? step.text : render(doc, text);
105
+ const read = decode(out, ctx.localPath);
106
+ const local = read.value;
107
+ const problems = read.failure ? [{ path: "", message: `the kernel would not decode it: ${read.failure}` }] : validateLocal(local);
108
+ if (problems.length) throw fail("E_WORKSPACE_SCHEMA", `the rewritten oats-local.yaml would be invalid (${problems.map((p) => `${p.path || "/"}: ${p.message}`).join("; ")}); nothing was written`, { problems });
109
+ step.check?.(local);
110
+ if (own && out === text) return { changed: false, local: current };
111
+ if (plan) return { changed: true, local };
112
+ if (readFileSync(ctx.localPath, "utf8") !== text) continue; // changed under us: redo on the new content
113
+ // The file that replaces it keeps its permission bits: one its operator made private stays private.
114
+ writeFileAtomic(ctx.localPath, out, { mode: statSync(ctx.localPath).mode & 0o7777 });
115
+ return { changed: true, local };
116
+ }
117
+ throw fail("E_LOCAL_CHANGED", `${ctx.localPath} kept changing while this edit ran; nothing was written — run it again`, { path: ctx.localPath });
118
+ }
package/lib/packages.mjs CHANGED
@@ -41,7 +41,7 @@
41
41
  * is exported below as a thin function throwing E_REMOVED so nothing breaks at
42
42
  * import time; callers are deleted in the next phase.
43
43
  */
44
- import { existsSync, mkdirSync, mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync, lstatSync } from "node:fs";
44
+ import { closeSync, existsSync, fchmodSync, mkdirSync, mkdtempSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, lstatSync } from "node:fs";
45
45
  import { tmpdir } from "node:os";
46
46
  import { basename, dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
47
47
  import { recordLocalInput } from "./local-inputs.mjs";
@@ -99,12 +99,21 @@ export function assertNoSymlinkedParents(scopeDir, leafDir, what) {
99
99
  }
100
100
 
101
101
  /** Sibling temp + rename: replaces the directory entry itself, never writing
102
- * THROUGH a pre-planted symlink at `file`. */
103
- export function writeFileAtomic(file, contents) {
102
+ * THROUGH a pre-planted symlink at `file`. The new file's permission bits are the process's default
103
+ * (its umask) unless `mode` gives them: then they are exactly `mode`, and in force before a byte of
104
+ * `contents` is written, so a file kept private is never readable by others on the way. */
105
+ export function writeFileAtomic(file, contents, { mode } = {}) {
104
106
  mkdirSync(dirname(file), { recursive: true });
105
107
  const tmp = join(dirname(file), `.${basename(file)}.oats-tmp-${process.pid}`);
106
108
  try {
107
- writeFileSync(tmp, contents);
109
+ if (mode === undefined) writeFileSync(tmp, contents);
110
+ else {
111
+ // A new file (one left by a killed process of this pid goes first; "wx" opens nothing that is
112
+ // there), created with no more than `mode` (the umask only takes bits away), then set to it exactly.
113
+ rmSync(tmp, { force: true });
114
+ const fd = openSync(tmp, "wx", mode);
115
+ try { fchmodSync(fd, mode); writeFileSync(fd, contents); } finally { closeSync(fd); }
116
+ }
108
117
  renameSync(tmp, file);
109
118
  } finally { rmSync(tmp, { force: true }); }
110
119
  }