vouchington-tooling 0.59.0 → 0.61.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 (141) hide show
  1. package/README.md +108 -0
  2. package/dist/cli/commands/hook.d.mts +2 -0
  3. package/dist/cli/commands/hook.mjs +19 -0
  4. package/dist/cli/commands/sandbox-command-audit.d.mts +7 -0
  5. package/dist/cli/commands/sandbox-command-audit.mjs +27 -0
  6. package/dist/cli/index.mjs +8 -0
  7. package/dist/cli/parse-forwarded-commands.d.mts +9 -0
  8. package/dist/cli/parse-forwarded-commands.mjs +6 -0
  9. package/dist/cli/parse.d.mts +9 -0
  10. package/dist/cli/usage-text.d.mts +1 -0
  11. package/dist/cli/usage-text.mjs +179 -0
  12. package/dist/cli/usage.d.mts +2 -1
  13. package/dist/cli/usage.mjs +2 -156
  14. package/dist/command-policy/engine.d.mts +7 -0
  15. package/dist/command-policy/engine.mjs +58 -0
  16. package/dist/command-policy/git-patterns.d.mts +20 -0
  17. package/dist/command-policy/git-patterns.mjs +82 -0
  18. package/dist/command-policy/git-process.d.mts +4 -0
  19. package/dist/command-policy/git-process.mjs +54 -0
  20. package/dist/command-policy/github-checkout-owners.d.mts +22 -0
  21. package/dist/command-policy/github-checkout-owners.mjs +122 -0
  22. package/dist/command-policy/github-command-context.d.mts +6 -0
  23. package/dist/command-policy/github-command-context.mjs +19 -0
  24. package/dist/command-policy/github-command-cwd.d.mts +8 -0
  25. package/dist/command-policy/github-command-cwd.mjs +130 -0
  26. package/dist/command-policy/github-command-position.d.mts +7 -0
  27. package/dist/command-policy/github-command-position.mjs +12 -0
  28. package/dist/command-policy/github-configured-base.d.mts +25 -0
  29. package/dist/command-policy/github-configured-base.mjs +59 -0
  30. package/dist/command-policy/github-invocation.d.mts +9 -0
  31. package/dist/command-policy/github-invocation.mjs +80 -0
  32. package/dist/command-policy/github-merge-authority.d.mts +21 -0
  33. package/dist/command-policy/github-merge-authority.mjs +86 -0
  34. package/dist/command-policy/github-option-flags.d.mts +3 -0
  35. package/dist/command-policy/github-option-flags.mjs +67 -0
  36. package/dist/command-policy/github-options.d.mts +12 -0
  37. package/dist/command-policy/github-options.mjs +73 -0
  38. package/dist/command-policy/github-stack-workflow.d.mts +9 -0
  39. package/dist/command-policy/github-stack-workflow.mjs +94 -0
  40. package/dist/command-policy/github-workflow.d.mts +7 -0
  41. package/dist/command-policy/github-workflow.mjs +50 -0
  42. package/dist/command-policy/hook/args.d.mts +11 -0
  43. package/dist/command-policy/hook/args.mjs +49 -0
  44. package/dist/command-policy/hook/harness.d.mts +26 -0
  45. package/dist/command-policy/hook/harness.mjs +119 -0
  46. package/dist/command-policy/hook/policy-module.d.mts +7 -0
  47. package/dist/command-policy/hook/policy-module.mjs +48 -0
  48. package/dist/command-policy/hook/post-tool-use.d.mts +9 -0
  49. package/dist/command-policy/hook/post-tool-use.mjs +51 -0
  50. package/dist/command-policy/hook/pre-tool-use.d.mts +21 -0
  51. package/dist/command-policy/hook/pre-tool-use.mjs +45 -0
  52. package/dist/command-policy/hook/run.d.mts +17 -0
  53. package/dist/command-policy/hook/run.mjs +69 -0
  54. package/dist/command-policy/hook/types.d.mts +33 -0
  55. package/dist/command-policy/hook/types.mjs +5 -0
  56. package/dist/command-policy/index.d.mts +29 -0
  57. package/dist/command-policy/index.mjs +23 -0
  58. package/dist/command-policy/path-references.d.mts +14 -0
  59. package/dist/command-policy/path-references.mjs +68 -0
  60. package/dist/command-policy/path-rules.d.mts +11 -0
  61. package/dist/command-policy/path-rules.mjs +37 -0
  62. package/dist/command-policy/payload.d.mts +8 -0
  63. package/dist/command-policy/payload.mjs +54 -0
  64. package/dist/command-policy/types.d.mts +77 -0
  65. package/dist/command-policy/types.mjs +1 -0
  66. package/dist/index.d.mts +2 -0
  67. package/dist/index.mjs +1 -0
  68. package/dist/sandbox-command-audit/args.d.mts +20 -0
  69. package/dist/sandbox-command-audit/args.mjs +64 -0
  70. package/dist/sandbox-command-audit/classify-prefixes.d.mts +23 -0
  71. package/dist/sandbox-command-audit/classify-prefixes.mjs +50 -0
  72. package/dist/sandbox-command-audit/classify.d.mts +46 -0
  73. package/dist/sandbox-command-audit/classify.mjs +74 -0
  74. package/dist/sandbox-command-audit/claude-extract.d.mts +23 -0
  75. package/dist/sandbox-command-audit/claude-extract.mjs +76 -0
  76. package/dist/sandbox-command-audit/claude-tool-uses.d.mts +15 -0
  77. package/dist/sandbox-command-audit/claude-tool-uses.mjs +53 -0
  78. package/dist/sandbox-command-audit/codex-extract.d.mts +21 -0
  79. package/dist/sandbox-command-audit/codex-extract.mjs +77 -0
  80. package/dist/sandbox-command-audit/codex-scan.d.mts +11 -0
  81. package/dist/sandbox-command-audit/codex-scan.mjs +98 -0
  82. package/dist/sandbox-command-audit/codex-spool.d.mts +14 -0
  83. package/dist/sandbox-command-audit/codex-spool.mjs +46 -0
  84. package/dist/sandbox-command-audit/discover-files.d.mts +44 -0
  85. package/dist/sandbox-command-audit/discover-files.mjs +85 -0
  86. package/dist/sandbox-command-audit/failure-text.d.mts +7 -0
  87. package/dist/sandbox-command-audit/failure-text.mjs +34 -0
  88. package/dist/sandbox-command-audit/fixtures.test-helpers.d.mts +34 -0
  89. package/dist/sandbox-command-audit/fixtures.test-helpers.mjs +41 -0
  90. package/dist/sandbox-command-audit/index.d.mts +26 -0
  91. package/dist/sandbox-command-audit/index.mjs +15 -0
  92. package/dist/sandbox-command-audit/json-record.d.mts +6 -0
  93. package/dist/sandbox-command-audit/json-record.mjs +16 -0
  94. package/dist/sandbox-command-audit/limits.d.mts +30 -0
  95. package/dist/sandbox-command-audit/limits.mjs +66 -0
  96. package/dist/sandbox-command-audit/repo-scope.d.mts +25 -0
  97. package/dist/sandbox-command-audit/repo-scope.mjs +79 -0
  98. package/dist/sandbox-command-audit/report-raw.d.mts +16 -0
  99. package/dist/sandbox-command-audit/report-raw.mjs +55 -0
  100. package/dist/sandbox-command-audit/report.d.mts +10 -0
  101. package/dist/sandbox-command-audit/report.mjs +61 -0
  102. package/dist/sandbox-command-audit/run.d.mts +36 -0
  103. package/dist/sandbox-command-audit/run.mjs +70 -0
  104. package/dist/sandbox-command-audit/scan.d.mts +10 -0
  105. package/dist/sandbox-command-audit/scan.mjs +79 -0
  106. package/dist/sandbox-command-audit/transcript-cwd.d.mts +14 -0
  107. package/dist/sandbox-command-audit/transcript-cwd.mjs +153 -0
  108. package/dist/sandbox-command-audit/types.d.mts +59 -0
  109. package/dist/sandbox-command-audit/types.mjs +23 -0
  110. package/dist/tmux/cli-shared.d.mts +18 -0
  111. package/dist/tmux/cli-shared.mjs +8 -0
  112. package/dist/tmux/cli.d.mts +3 -0
  113. package/dist/tmux/cli.mjs +34 -0
  114. package/dist/tmux/config.d.mts +24 -0
  115. package/dist/tmux/config.mjs +91 -0
  116. package/dist/tmux/fake-tmux.test-helpers.d.mts +46 -0
  117. package/dist/tmux/fake-tmux.test-helpers.mjs +105 -0
  118. package/dist/tmux/hook-payload.d.mts +8 -0
  119. package/dist/tmux/hook-payload.mjs +39 -0
  120. package/dist/tmux/index.d.mts +9 -0
  121. package/dist/tmux/index.mjs +7 -0
  122. package/dist/tmux/launcher.d.mts +11 -0
  123. package/dist/tmux/launcher.mjs +127 -0
  124. package/dist/tmux/reminder-post-tool.d.mts +21 -0
  125. package/dist/tmux/reminder-post-tool.mjs +88 -0
  126. package/dist/tmux/runner.d.mts +11 -0
  127. package/dist/tmux/runner.mjs +26 -0
  128. package/dist/tmux/session-name.d.mts +5 -0
  129. package/dist/tmux/session-name.mjs +10 -0
  130. package/dist/tmux/shell-quote.d.mts +9 -0
  131. package/dist/tmux/shell-quote.mjs +16 -0
  132. package/dist/tmux/up.d.mts +2 -0
  133. package/dist/tmux/up.mjs +73 -0
  134. package/dist/tmux/windows.d.mts +18 -0
  135. package/dist/tmux/windows.mjs +50 -0
  136. package/package.json +16 -1
  137. package/scripts/__pycache__/run_bounded_process.cpython-312.pyc +0 -0
  138. package/scripts/tmux/tmux-agent-reminder.sh +68 -0
  139. package/scripts/tmux/tmux-name.sh +34 -0
  140. package/scripts/tmux/tmux-read-title.sh +13 -0
  141. package/scripts/tmux/tmux-target.sh +130 -0
@@ -0,0 +1,79 @@
1
+ import { tmpdir } from 'node:os';
2
+ import { openTranscriptLines } from "../retrospective-transcript/index.mjs";
3
+ import { createClaudeRecordExtractor } from "./claude-extract.mjs";
4
+ import { scanCodexFile } from "./codex-scan.mjs";
5
+ import { discoverTranscriptFiles } from "./discover-files.mjs";
6
+ import { appendBounded, resolveLimits } from "./limits.mjs";
7
+ import { emptyScanResult } from "./types.mjs";
8
+ async function scanClaudeFile(file, options) {
9
+ const opened = await openTranscriptLines(file);
10
+ if ('error' in opened)
11
+ return { error: opened.error };
12
+ const extractor = createClaudeRecordExtractor(options);
13
+ try {
14
+ for await (const line of opened.lines)
15
+ extractor.pushLine(line);
16
+ return extractor.result();
17
+ }
18
+ catch (err) {
19
+ return { error: err.message };
20
+ }
21
+ }
22
+ function mergeRetention(target, source) {
23
+ target.commandTextsTruncated += source.commandTextsTruncated;
24
+ target.errorTextsTruncated += source.errorTextsTruncated;
25
+ target.pendingToolUsesDropped += source.pendingToolUsesDropped;
26
+ target.pendingToolUseBytesDropped += source.pendingToolUseBytesDropped;
27
+ target.recordsDropped += source.recordsDropped;
28
+ target.rawBytesDropped += source.rawBytesDropped;
29
+ }
30
+ /**
31
+ * Discovers transcripts and folds their records into one bounded `ScanResult`. Files are read
32
+ * one at a time so only one stream is ever open and each file's result arrays are released at once.
33
+ */
34
+ export async function scanTranscripts(options) {
35
+ const limits = resolveLimits(options.limits);
36
+ const { classifyFailure } = options;
37
+ const discovered = await discoverTranscriptFiles(options);
38
+ const result = emptyScanResult();
39
+ result.repoRoots = options.repoRoots;
40
+ result.skippedOtherRepo = discovered.skippedOtherRepo;
41
+ result.skippedUnknownCwd = discovered.skippedUnknownCwd;
42
+ const keep = (records, record) => appendBounded(records, record, result.rawRetention, limits);
43
+ const readError = (file, error) => keep(result.readErrors, `${file}: ${error}`);
44
+ for (const file of discovered.claudeFiles) {
45
+ // oxlint-disable-next-line no-await-in-loop
46
+ const scanned = await scanClaudeFile(file, { classifyFailure, limits });
47
+ if ('error' in scanned) {
48
+ readError(file, scanned.error);
49
+ continue;
50
+ }
51
+ result.claudeFilesScanned++;
52
+ mergeRetention(result.rawRetention, scanned.rawRetention);
53
+ for (const record of scanned.escalations)
54
+ keep(result.claudeEscalations, record);
55
+ for (const record of scanned.denials)
56
+ keep(result.claudeDenials, record);
57
+ for (const record of scanned.sandboxFailures)
58
+ keep(result.claudeSandboxFailures, record);
59
+ }
60
+ const tempRoot = options.tempRoot ?? tmpdir();
61
+ // Codex output is only classified by the caller's rule, so without one the files are not read.
62
+ const codexFiles = classifyFailure === undefined ? [] : discovered.codexFiles;
63
+ for (const file of codexFiles) {
64
+ // oxlint-disable-next-line no-await-in-loop
65
+ const scanned = await scanCodexFile(file, tempRoot, {
66
+ classifyFailure,
67
+ limits,
68
+ });
69
+ if ('error' in scanned) {
70
+ readError(file, scanned.error);
71
+ continue;
72
+ }
73
+ result.codexFilesScanned++;
74
+ mergeRetention(result.rawRetention, scanned.rawRetention);
75
+ for (const record of scanned.sandboxFailures)
76
+ keep(result.codexSandboxFailures, record);
77
+ }
78
+ return result;
79
+ }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * The first `cwd` in a transcript, top-level (Claude records) or at `payload.cwd` (Codex
3
+ * `session_meta`). It reads a 64 KB prefix and streams the whole file only when that prefix is
4
+ * truncated and yielded nothing. First-cwd-wins: a session that later `cd`s into another repo is
5
+ * bucketed by its earliest cwd.
6
+ */
7
+ export declare function readTranscriptCwd(path: string): Promise<string | undefined>;
8
+ /**
9
+ * Resolves a Claude transcript's cwd from its own session file (or its subagent's owning session)
10
+ * and memoizes it per session file. A session whose owner is missing or unreadable rejects, which
11
+ * discovery counts as an unknown cwd rather than guessing from a sibling session. A rejected
12
+ * lookup is evicted so the next call retries.
13
+ */
14
+ export declare function claudeSessionCwdResolver(projectsDir: string): (path: string) => Promise<string | undefined>;
@@ -0,0 +1,153 @@
1
+ var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
2
+ if (value !== null && value !== void 0) {
3
+ if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
4
+ var dispose, inner;
5
+ if (async) {
6
+ if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
7
+ dispose = value[Symbol.asyncDispose];
8
+ }
9
+ if (dispose === void 0) {
10
+ if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
11
+ dispose = value[Symbol.dispose];
12
+ if (async) inner = dispose;
13
+ }
14
+ if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
15
+ if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
16
+ env.stack.push({ value: value, dispose: dispose, async: async });
17
+ }
18
+ else if (async) {
19
+ env.stack.push({ async: true });
20
+ }
21
+ return value;
22
+ };
23
+ var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
24
+ return function (env) {
25
+ function fail(e) {
26
+ env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
27
+ env.hasError = true;
28
+ }
29
+ var r, s = 0;
30
+ function next() {
31
+ while (r = env.stack.pop()) {
32
+ try {
33
+ if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
34
+ if (r.dispose) {
35
+ var result = r.dispose.call(r.value);
36
+ if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
37
+ }
38
+ else s |= 1;
39
+ }
40
+ catch (e) {
41
+ fail(e);
42
+ }
43
+ }
44
+ if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
45
+ if (env.hasError) throw env.error;
46
+ }
47
+ return next();
48
+ };
49
+ })(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
50
+ var e = new Error(message);
51
+ return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
52
+ });
53
+ import { open } from 'node:fs/promises';
54
+ import { join, relative, sep } from 'node:path';
55
+ import { openTranscriptLines } from "../retrospective-transcript/index.mjs";
56
+ const PREFIX_BYTES = 64 * 1024;
57
+ async function readPrefix(path, maxBytes) {
58
+ const env_1 = { stack: [], error: void 0, hasError: false };
59
+ try {
60
+ const handle = __addDisposableResource(env_1, await open(path, 'r'), true);
61
+ const buffer = Buffer.alloc(maxBytes);
62
+ const { bytesRead } = await handle.read(buffer, 0, maxBytes, 0);
63
+ return { text: buffer.toString('utf8', 0, bytesRead), truncated: bytesRead === maxBytes };
64
+ }
65
+ catch (e_1) {
66
+ env_1.error = e_1;
67
+ env_1.hasError = true;
68
+ }
69
+ finally {
70
+ const result_1 = __disposeResources(env_1);
71
+ if (result_1)
72
+ await result_1;
73
+ }
74
+ }
75
+ function nonEmptyString(value) {
76
+ return typeof value === 'string' && value.length > 0 ? value : undefined;
77
+ }
78
+ function cwdFromRecord(record) {
79
+ if (typeof record !== 'object' || record === null)
80
+ return undefined;
81
+ const top = nonEmptyString(record.cwd);
82
+ if (top !== undefined)
83
+ return top;
84
+ return nonEmptyString(record.payload?.cwd);
85
+ }
86
+ function cwdFromLine(line) {
87
+ if (line.length === 0)
88
+ return undefined;
89
+ try {
90
+ return cwdFromRecord(JSON.parse(line));
91
+ }
92
+ catch {
93
+ // A malformed or partial line is skipped: the cwd is read best-effort.
94
+ return undefined;
95
+ }
96
+ }
97
+ // A prefix read almost always cuts its final line mid-object, so that fragment is dropped.
98
+ function cwdFromText(text, dropLastLine) {
99
+ const lines = text.split('\n');
100
+ for (const line of dropLastLine ? lines.slice(0, -1) : lines) {
101
+ const cwd = cwdFromLine(line);
102
+ if (cwd !== undefined)
103
+ return cwd;
104
+ }
105
+ return undefined;
106
+ }
107
+ /**
108
+ * The first `cwd` in a transcript, top-level (Claude records) or at `payload.cwd` (Codex
109
+ * `session_meta`). It reads a 64 KB prefix and streams the whole file only when that prefix is
110
+ * truncated and yielded nothing. First-cwd-wins: a session that later `cd`s into another repo is
111
+ * bucketed by its earliest cwd.
112
+ */
113
+ export async function readTranscriptCwd(path) {
114
+ const prefix = await readPrefix(path, PREFIX_BYTES);
115
+ const fromPrefix = cwdFromText(prefix.text, prefix.truncated);
116
+ if (fromPrefix !== undefined || !prefix.truncated)
117
+ return fromPrefix;
118
+ const opened = await openTranscriptLines(path);
119
+ if ('error' in opened)
120
+ throw new Error(opened.error);
121
+ for await (const line of opened.lines) {
122
+ const cwd = cwdFromLine(line);
123
+ if (cwd !== undefined)
124
+ return cwd;
125
+ }
126
+ return undefined;
127
+ }
128
+ // A Claude project directory name is a lossy encoding of the cwd, so distinct checkouts can share
129
+ // one. The cwd is therefore read per session: a top-level session file carries its own, and a
130
+ // subagent transcript under <session>/subagents/ resolves through its owning session file.
131
+ function owningSessionFile(projectsDir, path) {
132
+ const [projectDir, session, folder] = relative(projectsDir, path).split(sep);
133
+ return folder === 'subagents' ? join(projectsDir, projectDir, `${session}.jsonl`) : path;
134
+ }
135
+ /**
136
+ * Resolves a Claude transcript's cwd from its own session file (or its subagent's owning session)
137
+ * and memoizes it per session file. A session whose owner is missing or unreadable rejects, which
138
+ * discovery counts as an unknown cwd rather than guessing from a sibling session. A rejected
139
+ * lookup is evicted so the next call retries.
140
+ */
141
+ export function claudeSessionCwdResolver(projectsDir) {
142
+ const cache = new Map();
143
+ return async (path) => {
144
+ const owner = owningSessionFile(projectsDir, path);
145
+ let resolved = cache.get(owner);
146
+ if (resolved === undefined) {
147
+ resolved = readTranscriptCwd(owner);
148
+ resolved.catch(() => cache.delete(owner));
149
+ cache.set(owner, resolved);
150
+ }
151
+ return resolved;
152
+ };
153
+ }
@@ -0,0 +1,59 @@
1
+ import type { AuditLimits, RawRetention } from './limits.mts';
2
+ export type ClaudeToolDenialKind = 'user-rejected' | 'permission-rule' | 'automode-blocked';
3
+ /** A failure bucket. `e2big` and `genuine` are built in; a rule may return any other label. */
4
+ export type FailureKind = string;
5
+ /** A Claude Bash tool_use with `input.dangerouslyDisableSandbox: true`. */
6
+ export type ClaudeEscalationRecord = {
7
+ source: 'claude';
8
+ command: string;
9
+ };
10
+ /** A Claude tool_result with a top-level `toolDenialKind`; `command` is unset when uncorrelated. */
11
+ export type ClaudeDenialRecord = {
12
+ source: 'claude';
13
+ kind: ClaudeToolDenialKind;
14
+ command?: string | undefined;
15
+ };
16
+ /** A Claude Bash tool_result with `is_error: true` whose text matched a failure signature. */
17
+ export type ClaudeSandboxFailureRecord = {
18
+ source: 'claude';
19
+ kind: FailureKind;
20
+ command?: string | undefined;
21
+ errorText: string;
22
+ };
23
+ /** A Codex CommandExecution whose output an injected rule classified. */
24
+ export type CodexSandboxFailureRecord = {
25
+ source: 'codex';
26
+ kind: FailureKind;
27
+ command?: string | undefined;
28
+ errorText: string;
29
+ };
30
+ /** Per-source counts of files dropped by repo scoping, so a cross-repo leak is never silent. */
31
+ export type SkipCounts = {
32
+ claude: number;
33
+ codex: number;
34
+ };
35
+ /**
36
+ * Failure classification supplied by the caller. It runs after the E2BIG check and before the
37
+ * built-in permission signatures, so a repository can claim a failure for its own bucket (for
38
+ * example a write-path denial that needs a sandbox config fix rather than an allow entry).
39
+ */
40
+ export type ClassifyFailure = (command: string | undefined, text: string, source: 'claude' | 'codex') => FailureKind | undefined;
41
+ export type ScanRules = {
42
+ classifyFailure?: ClassifyFailure | undefined;
43
+ limits?: Partial<AuditLimits>;
44
+ };
45
+ export type ScanResult = {
46
+ claudeEscalations: ClaudeEscalationRecord[];
47
+ claudeDenials: ClaudeDenialRecord[];
48
+ claudeSandboxFailures: ClaudeSandboxFailureRecord[];
49
+ codexSandboxFailures: CodexSandboxFailureRecord[];
50
+ claudeFilesScanned: number;
51
+ codexFilesScanned: number;
52
+ readErrors: string[];
53
+ repoRoots: string[];
54
+ skippedOtherRepo: SkipCounts;
55
+ skippedUnknownCwd: SkipCounts;
56
+ /** Raw values exist for `--raw`; every cap is reported so a bounded run never looks complete. */
57
+ rawRetention: RawRetention;
58
+ };
59
+ export declare function emptyScanResult(): ScanResult;
@@ -0,0 +1,23 @@
1
+ export function emptyScanResult() {
2
+ return {
3
+ claudeEscalations: [],
4
+ claudeDenials: [],
5
+ claudeSandboxFailures: [],
6
+ codexSandboxFailures: [],
7
+ claudeFilesScanned: 0,
8
+ codexFilesScanned: 0,
9
+ readErrors: [],
10
+ repoRoots: [],
11
+ skippedOtherRepo: { claude: 0, codex: 0 },
12
+ skippedUnknownCwd: { claude: 0, codex: 0 },
13
+ rawRetention: {
14
+ commandTextsTruncated: 0,
15
+ errorTextsTruncated: 0,
16
+ pendingToolUsesDropped: 0,
17
+ pendingToolUseBytesDropped: 0,
18
+ recordsDropped: 0,
19
+ rawBytesDropped: 0,
20
+ retainedRawBytes: 0,
21
+ },
22
+ };
23
+ }
@@ -0,0 +1,18 @@
1
+ import type { ScriptSpawn } from '../cli/commands/spawn-script.mts';
2
+ import type { PaneTitleSpawn } from './reminder-post-tool.mts';
3
+ import type { TmuxRun } from './runner.mts';
4
+ export declare const TMUX_USAGE = "tmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]\ntmux name [--socket PATH --pane %ID --worktree PATH] <name>\ntmux read-title\ntmux agent-reminder session-start|user-prompt\ntmux post-tool (hook payload on stdin)\n Environment: TMUX_TARGET_BIN (tmux binary), TMUX_TARGET_ROOT (worktree, default cwd),\n TMUX_NAME_COMMAND (rename command named in reminders), AGENT_TMUX_SOCKET/PANE/WORKTREE.\n";
5
+ export type TmuxCliDeps = {
6
+ env?: NodeJS.ProcessEnv;
7
+ cwd?: string;
8
+ spawn?: ScriptSpawn;
9
+ readStdin?: () => string;
10
+ tmux?: TmuxRun;
11
+ hasChildren?: (pid: string) => boolean;
12
+ sleep?: (milliseconds: number) => void;
13
+ spawnPaneTitle?: PaneTitleSpawn;
14
+ out?: (text: string) => void;
15
+ err?: (text: string) => void;
16
+ pid?: number;
17
+ isPidAlive?: (pid: number) => boolean;
18
+ };
@@ -0,0 +1,8 @@
1
+ export const TMUX_USAGE = `tmux up --config <file> [--root <dir>] [--no-attach] [-v|--verbose]
2
+ tmux name [--socket PATH --pane %ID --worktree PATH] <name>
3
+ tmux read-title
4
+ tmux agent-reminder session-start|user-prompt
5
+ tmux post-tool (hook payload on stdin)
6
+ Environment: TMUX_TARGET_BIN (tmux binary), TMUX_TARGET_ROOT (worktree, default cwd),
7
+ TMUX_NAME_COMMAND (rename command named in reminders), AGENT_TMUX_SOCKET/PANE/WORKTREE.
8
+ `;
@@ -0,0 +1,3 @@
1
+ import { TMUX_USAGE, type TmuxCliDeps } from './cli-shared.mts';
2
+ export { TMUX_USAGE, type TmuxCliDeps };
3
+ export declare function runTmuxCommand(args: readonly string[], deps?: TmuxCliDeps): number;
@@ -0,0 +1,34 @@
1
+ import { readFileSync } from 'node:fs';
2
+ import { runScript } from "../cli/commands/spawn-script.mjs";
3
+ import { packageScriptPath } from "../cli/script-path.mjs";
4
+ import { TMUX_USAGE } from "./cli-shared.mjs";
5
+ import { parseHookPayload } from "./hook-payload.mjs";
6
+ import { renderPostToolReminder } from "./reminder-post-tool.mjs";
7
+ import { runUp } from "./up.mjs";
8
+ export { TMUX_USAGE };
9
+ const SCRIPTS = {
10
+ name: 'scripts/tmux/tmux-name.sh',
11
+ 'read-title': 'scripts/tmux/tmux-read-title.sh',
12
+ 'agent-reminder': 'scripts/tmux/tmux-agent-reminder.sh',
13
+ };
14
+ export function runTmuxCommand(args, deps = {}) {
15
+ const [subcommand, ...rest] = args;
16
+ const script = subcommand === undefined ? undefined : SCRIPTS[subcommand];
17
+ if (script !== undefined)
18
+ return runScript('bash', packageScriptPath(script), rest, deps.spawn);
19
+ if (subcommand === 'up')
20
+ return runUp(rest, deps);
21
+ if (subcommand === 'post-tool' && rest.length === 0) {
22
+ const stdin = deps.readStdin ?? (() => readFileSync(0, 'utf8'));
23
+ const reminder = renderPostToolReminder(parseHookPayload(stdin()), {
24
+ env: deps.env,
25
+ spawnPaneTitle: deps.spawnPaneTitle,
26
+ });
27
+ if (reminder !== null)
28
+ (deps.out ?? ((text) => void process.stdout.write(text)))(`${reminder}\n`);
29
+ return 0;
30
+ }
31
+ ;
32
+ (deps.err ?? ((text) => void process.stderr.write(text)))(`vouchington: expected: up|name|read-title|agent-reminder|post-tool\n${TMUX_USAGE}`);
33
+ return 2;
34
+ }
@@ -0,0 +1,24 @@
1
+ export type TmuxWindowConfig = {
2
+ name: string;
3
+ /** Shell body run through `bash -lc`. */
4
+ command: string;
5
+ /** Working directory, relative to the worktree root unless absolute. */
6
+ cwd?: string;
7
+ env: Record<string, string>;
8
+ /** Keep the pane open after the command exits (appends `; read`). Default true. */
9
+ keepOpen: boolean;
10
+ };
11
+ export type TmuxSessionConfig = {
12
+ /** Prepended to the worktree hash to form the tmux session name. */
13
+ sessionPrefix: string;
14
+ /** Session option (without the leading `@`) set once every window exists. */
15
+ readyMarker: string;
16
+ /** Variable recorded in the tmux session environment to identify the launcher. */
17
+ launcherPidVar: string;
18
+ env: Record<string, string>;
19
+ windows: TmuxWindowConfig[];
20
+ /** Lines printed before a fresh session starts. */
21
+ summary: string[];
22
+ };
23
+ export declare function parseTmuxConfig(value: unknown): TmuxSessionConfig;
24
+ export declare function loadTmuxConfig(path: string): TmuxSessionConfig;
@@ -0,0 +1,91 @@
1
+ import { readFileSync } from 'node:fs';
2
+ const ENV_KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
3
+ const TMUX_NAME = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
4
+ // A purely numeric window name would be read by tmux as an index.
5
+ const WINDOW_NAME = /^(?![0-9]+$)[A-Za-z0-9][A-Za-z0-9_.-]*$/;
6
+ const OPTION_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
7
+ function isRecord(value) {
8
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
9
+ }
10
+ function text(value, label, pattern) {
11
+ if (typeof value !== 'string' ||
12
+ value === '' ||
13
+ (pattern !== undefined && !pattern.test(value))) {
14
+ throw new Error(`tmux config: ${label} must be a ${pattern ? 'valid ' : 'non-empty '}string`);
15
+ }
16
+ return value;
17
+ }
18
+ function envMap(value, label) {
19
+ if (value === undefined)
20
+ return {};
21
+ if (!isRecord(value))
22
+ throw new Error(`tmux config: ${label} must be an object`);
23
+ const result = {};
24
+ for (const [key, raw] of Object.entries(value)) {
25
+ if (!ENV_KEY.test(key))
26
+ throw new Error(`tmux config: ${label} has invalid name "${key}"`);
27
+ if (typeof raw !== 'string' && typeof raw !== 'number') {
28
+ throw new Error(`tmux config: ${label}.${key} must be a string or number`);
29
+ }
30
+ result[key] = String(raw);
31
+ }
32
+ return result;
33
+ }
34
+ function windowConfig(value, index) {
35
+ const label = `windows[${index}]`;
36
+ if (!isRecord(value))
37
+ throw new Error(`tmux config: ${label} must be an object`);
38
+ const cwd = value.cwd === undefined ? undefined : text(value.cwd, `${label}.cwd`);
39
+ if (value.keepOpen !== undefined && typeof value.keepOpen !== 'boolean') {
40
+ throw new Error(`tmux config: ${label}.keepOpen must be a boolean`);
41
+ }
42
+ return {
43
+ name: text(value.name, `${label}.name`, WINDOW_NAME),
44
+ command: text(value.command, `${label}.command`),
45
+ ...(cwd === undefined ? {} : { cwd }),
46
+ env: envMap(value.env, `${label}.env`),
47
+ keepOpen: value.keepOpen ?? true,
48
+ };
49
+ }
50
+ export function parseTmuxConfig(value) {
51
+ if (!isRecord(value))
52
+ throw new Error('tmux config: expected a JSON object');
53
+ if (!Array.isArray(value.windows) || value.windows.length === 0) {
54
+ throw new Error('tmux config: windows must be a non-empty array');
55
+ }
56
+ const windows = value.windows.map(windowConfig);
57
+ const names = new Set(windows.map((window) => window.name));
58
+ if (names.size !== windows.length)
59
+ throw new Error('tmux config: window names must be unique');
60
+ const summary = value.summary ?? [];
61
+ if (!Array.isArray(summary) || summary.some((line) => typeof line !== 'string')) {
62
+ throw new Error('tmux config: summary must be an array of strings');
63
+ }
64
+ return {
65
+ sessionPrefix: text(value.sessionPrefix ?? 'dev-', 'sessionPrefix', TMUX_NAME),
66
+ readyMarker: text(value.readyMarker ?? 'ready', 'readyMarker', OPTION_NAME),
67
+ launcherPidVar: text(value.launcherPidVar ?? 'TMUX_LAUNCHER_PID', 'launcherPidVar', ENV_KEY),
68
+ env: envMap(value.env, 'env'),
69
+ windows,
70
+ summary: summary,
71
+ };
72
+ }
73
+ export function loadTmuxConfig(path) {
74
+ let raw;
75
+ try {
76
+ raw = readFileSync(path, 'utf8');
77
+ }
78
+ catch (error) {
79
+ throw new Error(`tmux config: cannot read ${path}: ${error.message}`, {
80
+ cause: error,
81
+ });
82
+ }
83
+ try {
84
+ return parseTmuxConfig(JSON.parse(raw));
85
+ }
86
+ catch (error) {
87
+ if (error instanceof SyntaxError)
88
+ throw new Error(`tmux config: ${path} is not valid JSON`);
89
+ throw error;
90
+ }
91
+ }
@@ -0,0 +1,46 @@
1
+ import type { TmuxSessionConfig } from './config.mts';
2
+ import type { TmuxRun } from './runner.mts';
3
+ import type { SessionContext } from './windows.mts';
4
+ export type FakeTmuxOptions = {
5
+ exists?: boolean;
6
+ windows?: string[];
7
+ dead?: string[];
8
+ /** Polls of the ready option that report not-ready before it becomes `1`. */
9
+ readyAfter?: number;
10
+ /** Never ready. */
11
+ neverReady?: boolean;
12
+ /** The session vanishes after this many has-session calls. */
13
+ vanishAfterChecks?: number;
14
+ /** Subcommands (first argument) that exit 1. */
15
+ failOn?: string[];
16
+ /** Subcommand to fail only the first time it runs. */
17
+ failOnce?: string;
18
+ /** Environment value returned for the launcher pid variable. */
19
+ launcherPid?: string;
20
+ attachStatus?: number | null;
21
+ /** Whether `isPidAlive` reports the recorded launcher as running. Default true. */
22
+ ownerAlive?: boolean;
23
+ };
24
+ export declare function createFakeTmux(options?: FakeTmuxOptions): {
25
+ run: TmuxRun;
26
+ calls: string[][];
27
+ out: string[];
28
+ err: string[];
29
+ sleeps: number[];
30
+ state: {
31
+ exists: boolean;
32
+ windows: string[];
33
+ polls: number;
34
+ checks: number;
35
+ failedOnce: boolean;
36
+ };
37
+ context: (config?: TmuxSessionConfig) => SessionContext;
38
+ launch: (noAttach?: boolean) => {
39
+ noAttach: boolean;
40
+ pid: number;
41
+ sleep: (ms: number) => undefined;
42
+ isPidAlive: () => boolean;
43
+ };
44
+ };
45
+ /** Subcommand lines, e.g. `new-window -t =dev-dabc -n web ...`. */
46
+ export declare function lines(calls: readonly string[][]): string[];
@@ -0,0 +1,105 @@
1
+ const sampleConfig = {
2
+ sessionPrefix: 'dev-',
3
+ readyMarker: 'ready',
4
+ launcherPidVar: 'TMUX_LAUNCHER_PID',
5
+ env: { SHARED: '1' },
6
+ summary: ['Web: http://localhost:3000'],
7
+ windows: [
8
+ { name: 'web', command: 'serve web', cwd: 'web', env: { SERVICE: 'web' }, keepOpen: true },
9
+ { name: 'api', command: 'serve api', env: {}, keepOpen: false },
10
+ { name: 'jobs', command: 'serve jobs', env: {}, keepOpen: true },
11
+ ],
12
+ };
13
+ export function createFakeTmux(options = {}) {
14
+ const state = {
15
+ exists: options.exists ?? false,
16
+ windows: [...(options.windows ?? [])],
17
+ polls: 0,
18
+ checks: 0,
19
+ failedOnce: false,
20
+ };
21
+ const calls = [];
22
+ const pids = new Map();
23
+ const deadPids = new Set();
24
+ const pidFor = (name) => {
25
+ if (!pids.has(name)) {
26
+ pids.set(name, String(1000 + pids.size));
27
+ if (options.dead?.includes(name))
28
+ deadPids.add(pids.get(name));
29
+ }
30
+ return pids.get(name);
31
+ };
32
+ const ok = (stdout = '') => ({ status: 0, stdout });
33
+ const fail = { status: 1, stdout: '' };
34
+ const run = (args) => {
35
+ calls.push([...args]);
36
+ const [command = '', ...rest] = args;
37
+ if (options.failOn?.includes(command))
38
+ return fail;
39
+ if (options.failOnce === command && !state.failedOnce) {
40
+ state.failedOnce = true;
41
+ return fail;
42
+ }
43
+ switch (command) {
44
+ case '-V':
45
+ return ok('tmux 3.5\n');
46
+ case 'has-session':
47
+ state.checks += 1;
48
+ if (options.vanishAfterChecks !== undefined && state.checks > options.vanishAfterChecks) {
49
+ state.exists = false;
50
+ }
51
+ return state.exists ? ok() : fail;
52
+ case 'show-options': {
53
+ state.polls += 1;
54
+ const ready = !options.neverReady && state.polls > (options.readyAfter ?? 0);
55
+ return ok(ready ? '1\n' : '');
56
+ }
57
+ case 'show-environment':
58
+ return ok(`${rest[2]}=${options.launcherPid ?? ''}\n`);
59
+ case 'list-windows':
60
+ return ok(state.windows.join('\n'));
61
+ case 'list-panes': {
62
+ const name = rest[1].split(':')[1];
63
+ return ok(`${pidFor(name)}\nnot-a-pid\n`);
64
+ }
65
+ case 'new-session':
66
+ state.exists = true;
67
+ state.windows.push(rest[rest.indexOf('-n') + 1]);
68
+ return ok();
69
+ case 'new-window':
70
+ state.windows.push(rest[rest.indexOf('-n') + 1]);
71
+ return ok();
72
+ case 'kill-session':
73
+ state.exists = false;
74
+ return ok();
75
+ case 'attach':
76
+ return { status: options.attachStatus === undefined ? 0 : options.attachStatus, stdout: '' };
77
+ default:
78
+ return ok();
79
+ }
80
+ };
81
+ const out = [];
82
+ const err = [];
83
+ const sleeps = [];
84
+ const context = (config = sampleConfig) => ({
85
+ config,
86
+ root: '/work',
87
+ session: 'dev-dabc',
88
+ extraEnv: { TMUX_LOG_LEVEL: 'error' },
89
+ tmux: run,
90
+ hasChildren: (pid) => !deadPids.has(pid),
91
+ out: (text) => void out.push(text),
92
+ err: (text) => void err.push(text),
93
+ });
94
+ const launch = (noAttach = true) => ({
95
+ noAttach,
96
+ pid: 4242,
97
+ sleep: (ms) => void sleeps.push(ms),
98
+ isPidAlive: () => options.ownerAlive ?? true,
99
+ });
100
+ return { run, calls, out, err, sleeps, state, context, launch };
101
+ }
102
+ /** Subcommand lines, e.g. `new-window -t =dev-dabc -n web ...`. */
103
+ export function lines(calls) {
104
+ return calls.map((call) => call.join(' '));
105
+ }