megalens-review 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -32,9 +32,11 @@ npx megalens-review install # downloads the pinned Codex CLI and checks
32
32
  MEGALENS_TOKEN=... npx megalens-review run --tier standard --target range --base <base-sha> --head <head-sha> --out findings.json
33
33
  ```
34
34
 
35
+ Size limit: one review takes at most 250 changed files, 40,000 changed lines (added plus removed), 3 MiB of changed text, and 512 KiB for any one file, for Standard and Deep alike, and for pull request, range and uncommitted targets. It is measured on the exact diff that is sent to the model (after the engine's own exclusions: agent config and credential-shaped files), so lock files, build and vendor folders and binary files all count, and no `.gitattributes` setting can lower the count. A bigger change is refused (exit 3) before any gateway call or model run, with 0 credits; a review the Action already opened is closed as failed with reason `too_large`. Message: "This change is too large for one review (N files, about M lines). Split it into smaller pull requests, or review one folder." The numbers live in `src/limits.mjs`.
36
+
35
37
  Commands: `run`, `status <review-id>`, `result <review-id>`, `cancel <review-id>`, `install`, `verify`.
36
38
 
37
- Exit codes: `0` complete (findings may be empty), `2` partial, `3` refused by the gateway (no credits, limits, sign-in), `4` local error or failed review. A failed or partial review is never reported as a clean one.
39
+ Exit codes: `0` complete (findings may be empty), `2` partial, `3` refused (no credits, limits, sign-in, change too large), `4` local error or failed review. A failed or partial review is never reported as a clean one.
38
40
 
39
41
  ## Support
40
42
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "megalens-review",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "MegaLens review engine: runs a pinned code review on your pull request diff in a sandbox and writes the findings as JSON. Used by the MegaLens GitHub Action.",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",
package/src/cli.mjs CHANGED
@@ -1,6 +1,6 @@
1
1
  import { parseArgs } from 'node:util'
2
2
  import { writeFileSync } from 'node:fs'
3
- import { EXIT, LocalError, RefusedError } from './exit-codes.mjs'
3
+ import { EXIT, LocalError, RefusedError, SANDBOX_UNUSABLE_TEXT, SandboxUnusableError } from './exit-codes.mjs'
4
4
  import { execute, failureDoc, prepare } from './engine.mjs'
5
5
  import { TIER_NAMES, TIERS, isTier } from './tiers.mjs'
6
6
  import { cancelReview, currentStatus, runWorker, startBackground } from './background.mjs'
@@ -17,7 +17,7 @@ megalens-review install # download and verify the pinned codex-cli (the onl
17
17
  megalens-review verify # re-check the installed codex-cli against PINNED.json
18
18
 
19
19
  Auth by environment: MEGALENS_TOKEN (a MegaLens token, or the review key the GitHub Action passes).
20
- Exit codes: 0 complete, 2 partial, 3 refused by the gateway, 4 local error or failed review.`
20
+ Exit codes: 0 complete, 2 partial, 3 refused (gateway, limits, change too large), 4 local error or failed review.`
21
21
 
22
22
  function emit(doc, out, io) {
23
23
  const text = JSON.stringify(doc, null, 2) + '\n'
@@ -29,8 +29,10 @@ function emit(doc, out, io) {
29
29
  * CLI entry. `io` and `env` are injectable for tests. Returns the exit code; never calls process.exit.
30
30
  * stdout carries the findings JSON only (unless --out is given); progress and errors go to stderr.
31
31
  */
32
- export async function main(argv, { tiers, codexBin, pinned, modes, unsafeNoIsolation = false, env = process.env, cwd = process.cwd(), io = { stdout: (s) => process.stdout.write(s), stderr: (s) => process.stderr.write(s) }, fetchImpl } = {}) {
32
+ export async function main(argv, { tiers, codexBin, pinned, modes, unsafeNoIsolation = false, nestedProbe, env = process.env, cwd = process.cwd(), io = { stdout: (s) => process.stdout.write(s), stderr: (s) => process.stderr.write(s) }, fetchImpl } = {}) {
33
33
  const [cmd, ...rest] = argv
34
+ let outPath = null
35
+ let runTier = null
34
36
  try {
35
37
  if (!cmd || cmd === '--help' || cmd === '-h') { io.stderr(USAGE + '\n'); return cmd ? EXIT.COMPLETE : EXIT.LOCAL_ERROR }
36
38
 
@@ -86,13 +88,15 @@ export async function main(argv, { tiers, codexBin, pinned, modes, unsafeNoIsola
86
88
  strict: true,
87
89
  })
88
90
  if (!isTier(values.tier)) throw new LocalError(`--tier is required: ${TIER_NAMES.join('|')}`)
91
+ outPath = values.out
92
+ runTier = values.tier
89
93
  const timeoutMin = values['timeout-min'] === undefined ? undefined : Number(values['timeout-min'])
90
94
  if (timeoutMin !== undefined && !(timeoutMin > 0 && timeoutMin <= 240)) throw new LocalError('--timeout-min must be between 1 and 240')
91
95
  if (values.background && !TIERS[values.tier].background) throw new LocalError('--background is for the deep tier')
92
96
 
93
97
  pruneOld(env)
94
98
  const prepared = await prepare({
95
- tiers, codexBin, pinned, modes, unsafeNoIsolation, cwd, tier: values.tier, targetKind: values.target, base: values.base, head: values.head,
99
+ tiers, codexBin, pinned, modes, unsafeNoIsolation, nestedProbe, cwd, tier: values.tier, targetKind: values.target, base: values.base, head: values.head,
96
100
  firstReviewPath: values['first-review'], quiet: values.quiet, timeoutMin, env, fetchImpl,
97
101
  })
98
102
  io.stderr(`megalens-review: ${values.tier} review ${prepared.job.review_id} (${prepared.job.mode})\n`)
@@ -124,9 +128,21 @@ export async function main(argv, { tiers, codexBin, pinned, modes, unsafeNoIsola
124
128
  return exit
125
129
  } catch (e) {
126
130
  if (e instanceof RefusedError) {
127
- io.stderr((e.code === 'mode_unavailable' || e.code === 'tier_unavailable') ? `${e.message}\n` : `refused by the MegaLens gateway: ${e.message}\n`)
131
+ if (e.code === 'too_large' && outPath) {
132
+ // refused:true so the Action treats it as a refusal; the message travels in notes.
133
+ try { writeFileSync(outPath, JSON.stringify(failureDoc({ reviewId: e.detail?.reviewId ?? undefined, tier: runTier, reason: 'too_large', refused: true, notes: [e.message], target: e.detail?.target ?? null }), null, 2) + '\n', { mode: 0o600 }) } catch { /* the exit code still says it */ }
134
+ }
135
+ io.stderr((e.code === 'mode_unavailable' || e.code === 'tier_unavailable' || e.code === 'too_large') ? `${e.message}\n` : `refused by the MegaLens gateway: ${e.message}\n`)
128
136
  return EXIT.REFUSED
129
137
  }
138
+ if (e instanceof SandboxUnusableError) {
139
+ io.stderr(`error: ${SANDBOX_UNUSABLE_TEXT}\n`)
140
+ // A findings document only when --out names a file: stdout stays empty, there is no review to print.
141
+ if (outPath) {
142
+ try { writeFileSync(outPath, JSON.stringify(failureDoc({ tier: runTier, reason: 'sandbox_unusable', notes: [SANDBOX_UNUSABLE_TEXT] }), null, 2) + '\n', { mode: 0o600 }) } catch { /* the exit code still says it */ }
143
+ }
144
+ return EXIT.LOCAL_ERROR
145
+ }
130
146
  io.stderr(`error: ${e instanceof LocalError ? e.message : String(e?.message ?? e).slice(0, 200)}\n`)
131
147
  return EXIT.LOCAL_ERROR
132
148
  }
package/src/codex-run.mjs CHANGED
@@ -65,13 +65,47 @@ function findRollouts(dir) {
65
65
  * Returns { models, rawReview } (rawReview is null when there is no review sub-agent log).
66
66
  */
67
67
  /** What a command that could not even start its sandbox prints (codex-cli 0.170.0 with no helper alias, or no user namespace). */
68
- const SANDBOX_FAIL = /bwrap: |codex-linux-sandbox|seccomp.*(fail|denied)|Operation not permitted.*(namespace|sandbox)/i
68
+ const SANDBOX_FAIL = /bwrap: No permissions to create a new namespace|bwrap: |codex-linux-sandbox|seccomp.*(fail|denied)|Operation not permitted.*(namespace|sandbox)/i
69
+
70
+ /** The environment blocks the nested sandbox: one such output is enough to make the pass unusable, however many other commands ran. */
71
+ const NAMESPACE_BLOCKED = /No permissions to creat(e|ing) (a )?new namespace/i
72
+
73
+ /** Every JSON object with an exit_code found in one tool output: real Codex 0.170.0 writes a text header ("Script completed\nWall time ...\nOutput:\n") then one or more JSON objects, in a string or in input_text parts. */
74
+ function execResults(output) {
75
+ const parts = typeof output === 'string' ? [output] : Array.isArray(output) ? output.map((c) => (typeof c?.text === 'string' ? c.text : '')) : [JSON.stringify(output ?? '')]
76
+ const found = []
77
+ const take = (j) => {
78
+ if (!j || typeof j !== 'object') return
79
+ if (Array.isArray(j)) { j.forEach(take); return }
80
+ const e = j.exit_code ?? j.metadata?.exit_code
81
+ if (typeof e === 'number') found.push({ exit: e, text: typeof j.output === 'string' ? j.output : '' })
82
+ else if (j.value && typeof j.value === 'object') take(j.value)
83
+ }
84
+ for (const part of parts) {
85
+ const t = part.trim()
86
+ let whole = false
87
+ if (t.startsWith('{') || t.startsWith('[')) { try { take(JSON.parse(t)); whole = true } catch { /* header + objects */ } }
88
+ if (whole) continue
89
+ for (const line of part.split('\n')) {
90
+ const l = line.trim()
91
+ if (!l.startsWith('{') && !l.startsWith('[')) continue
92
+ try { take(JSON.parse(l)) } catch { /* not JSON */ }
93
+ }
94
+ }
95
+ return found
96
+ }
97
+
98
+ /** Counts only a FAILED command (non-zero exit_code) whose own output STARTS with the error: a docs line or source file quoting it, or a failure that mentions it later, is not blocking. */
99
+ function isNamespaceBlock(output) {
100
+ return execResults(output).some((r) => r.exit !== 0 && /^(bwrap:\s*)?No permissions to creat(e|ing) (a )?new namespace/i.test(r.text.trimStart()))
101
+ }
69
102
 
70
103
  export function readSessionLogs(sessionsDir) {
71
104
  const models = new Set()
72
105
  let rawReview = null
73
106
  let toolCalls = 0
74
107
  let sandboxFailures = 0
108
+ let namespaceBlocked = 0
75
109
  let metrics = null // input and reasoning tokens of the review sub-agent's log (what the short-run check reads)
76
110
  for (const p of findRollouts(sessionsDir)) {
77
111
  let txt
@@ -92,7 +126,10 @@ export function readSessionLogs(sessionsDir) {
92
126
  const tu = pl?.type === 'token_count' ? pl.info?.total_token_usage : null
93
127
  if (tu) { inTok = Math.max(inTok ?? 0, Number(tu.input_tokens) || 0); reasTok = Math.max(reasTok ?? 0, Number(tu.reasoning_output_tokens) || 0) }
94
128
  if (d.type === 'response_item' && (pl?.type === 'custom_tool_call' || pl?.type === 'function_call')) toolCalls++
95
- if (d.type === 'response_item' && (pl?.type === 'custom_tool_call_output' || pl?.type === 'function_call_output') && SANDBOX_FAIL.test(JSON.stringify(pl.output ?? ''))) sandboxFailures++
129
+ if (d.type === 'response_item' && (pl?.type === 'custom_tool_call_output' || pl?.type === 'function_call_output') && SANDBOX_FAIL.test(JSON.stringify(pl.output ?? ''))) {
130
+ sandboxFailures++
131
+ if (isNamespaceBlock(pl.output)) namespaceBlocked++
132
+ }
96
133
  // Only a response item counts as the model's reply, and only when the sub-agent's turn completed.
97
134
  if (d.type === 'response_item' && pl?.type === 'message' && pl.role === 'assistant' && Array.isArray(pl.content)) {
98
135
  pending = pl.content.map((c) => (typeof c?.text === 'string' ? c.text : '')).join('')
@@ -103,7 +140,7 @@ export function readSessionLogs(sessionsDir) {
103
140
  if (isReview) metrics = { inTok, reasTok }
104
141
  }
105
142
  // Tokens and calls are only reported when the review sub-agent's own log was found (null = unknown: the short-run guard does not judge it).
106
- return { models: [...models].sort(), rawReview, toolCalls, sandboxFailures, reviewLog: metrics !== null, inputTokens: metrics ? metrics.inTok : null, reasoningTokens: metrics ? metrics.reasTok : null }
143
+ return { models: [...models].sort(), rawReview, toolCalls, sandboxFailures, namespaceBlocked, reviewLog: metrics !== null, inputTokens: metrics ? metrics.inTok : null, reasoningTokens: metrics ? metrics.reasTok : null }
107
144
  }
108
145
 
109
146
  /**
@@ -123,15 +160,15 @@ export async function runCodexPass({ codexBin = 'codex', workspace, codexHome, e
123
160
  let reason = null
124
161
  if (r.aborted) reason = 'cancelled'
125
162
  else if (r.timedOut) reason = 'timeout'
163
+ // The environment blocks the sandbox (one namespace failure), or every command the model tried failed to start its sandbox: the
164
+ // review saw nothing, so it is not a review, whatever the model then said or the exit code was.
165
+ else if (logs.namespaceBlocked > 0 || (logs.toolCalls > 0 && logs.sandboxFailures === logs.toolCalls)) reason = 'sandbox_unusable'
126
166
  else if (r.rc !== 0) reason = `codex exited ${r.rc}`
127
167
  else if (ev.failed) reason = 'codex_failed_turn'
128
168
  else if (!ev.text.trim()) reason = 'bad_output'
129
169
  // Every model the session log names must be the pinned one (a log naming both is a downgrade somewhere in the run).
130
170
  else if (served && pinnedModel && !served.every((m) => m === pinnedModel || m.startsWith(pinnedModel + '-'))) {
131
171
  reason = 'model_mismatch'
132
- } else if (logs.toolCalls > 0 && logs.sandboxFailures === logs.toolCalls) {
133
- // Every command the model tried failed to start its sandbox: the review saw nothing, so it is not a review.
134
- reason = 'sandbox_unusable'
135
172
  } else if (!served && requireServed) {
136
173
  // No session log, so nothing proves which model answered: not a clean review.
137
174
  reason = 'model_unverified'
package/src/engine.mjs CHANGED
@@ -8,15 +8,16 @@ import { runBase } from './state.mjs'
8
8
  import { codexEnv, createCodexHome, writeBackLogin } from './config.mjs'
9
9
  import { runCodexPass } from './codex-run.mjs'
10
10
  import { parseDiffRanges } from './diff-map.mjs'
11
- import { EXIT, LocalError, RefusedError, exitCodeForStatus } from './exit-codes.mjs'
11
+ import { EXIT, LocalError, RefusedError, SANDBOX_UNUSABLE_TEXT, SandboxUnusableError, exitCodeForStatus } from './exit-codes.mjs'
12
12
  import { SCHEMA, applyQuiet, buildFindings, overallStatus, readFirstReview, validateFindingsDoc } from './findings.mjs'
13
13
  import { createGatewayClient, DEFAULT_API_URL } from './gateway-client.mjs'
14
14
  import { parseReviewText, pickReviewText } from './parse.mjs'
15
15
  import { redactSecrets } from './redact.mjs'
16
- import { resolveIsolation, wrapCommand } from './isolation.mjs'
16
+ import { nestedSandboxWorks, resolveIsolation, wrapCommand } from './isolation.mjs'
17
17
  import { judgeShortRun } from './short-run.mjs'
18
18
  import { BRIDGE_PORT, CHILD_PREFIX, startCredentialProxy } from './credential-proxy.mjs'
19
19
  import { DOUBLE_TIER_ENABLED, TIERS, ctxPrompt, isTier, planPasses } from './tiers.mjs'
20
+ import { measureDiff, overLimit, tooLargeMessage } from './limits.mjs'
20
21
  import { buildWorkspace, closeTarget, collectChanges, resolveTarget, snapshotHash } from './workspace.mjs'
21
22
 
22
23
  const round2 = (n) => Math.round(n * 100) / 100
@@ -52,12 +53,21 @@ export function repoIdentity(repoRoot) {
52
53
  * Everything that must happen before any model is called: auth, target, snapshot, sandboxed workspace, and (gateway)
53
54
  * the server-owned review. Returns a plain object that can be written to a job file (no secrets in it).
54
55
  */
55
- export async function prepare({ tiers, codexBin, pinned, modes, unsafeNoIsolation = false, cwd, tier, targetKind = 'uncommitted', base, head, firstReviewPath, quiet = false, timeoutMin, env, fetchImpl }) {
56
+ export async function prepare({ tiers, codexBin, pinned, modes, unsafeNoIsolation = false, nestedProbe = nestedSandboxWorks, cwd, tier, targetKind = 'uncommitted', base, head, firstReviewPath, quiet = false, timeoutMin, env, fetchImpl }) {
56
57
  if (!isTier(tier)) throw new LocalError(`--tier must be one of standard, double, deep`)
57
58
  // Checked first: a tier that is switched off is a refusal (exit 3), before auth, git or any network.
58
59
  if (tier === 'double' && !(tiers?.double ?? DOUBLE_TIER_ENABLED)) throw new RefusedError('The Double tier is not available yet', 'tier_unavailable')
59
60
  const auth = resolveAuth(env, modes)
60
61
  const isolation = resolveIsolation(env, { unsafeNoIsolation })
62
+ // Preflight, before any gateway call or model call: Codex starts its own sandbox inside ours, and some runners (Ubuntu AppArmor)
63
+ // block that. Found out here it costs nothing; found out mid-review it was a blind review that was charged.
64
+ if (isolation === 'bwrap' && !nestedProbe(env)) {
65
+ if (auth.mode === 'gateway' && auth.preReview) {
66
+ // The Action already opened a review for this run: close it as failed so it is charged 0 credits.
67
+ try { await createGatewayClient({ apiUrl: env.MEGALENS_API_URL || DEFAULT_API_URL, token: auth.token, fetchImpl, env }).complete(auth.preReview.id, 'failed', 'sandbox_unusable') } catch { /* the server also closes on expiry */ }
68
+ }
69
+ throw new SandboxUnusableError()
70
+ }
61
71
  // The Codex binary is the pinned, re-verified install (exit 4 if it is missing or was changed). `codexBin` is the library/test
62
72
  // injection; there is no environment variable or flag for it.
63
73
  const codexPath = codexBin ?? resolvePinnedCodex({ pinned, env })
@@ -71,14 +81,32 @@ export async function prepare({ tiers, codexBin, pinned, modes, unsafeNoIsolatio
71
81
  }
72
82
  }
73
83
  const target = resolveTarget({ cwd, kind: targetKind, base, head })
84
+ // Read the target once, build the workspace from that one read, and measure the diff that is actually sent. All local: nothing
85
+ // has been created at the gateway and no model has run, so a change that is too big ends here for 0 credits.
74
86
  let changes
75
87
  let snapshot
88
+ let ws
76
89
  try {
77
90
  changes = collectChanges(target)
78
91
  snapshot = snapshotHash(target, changes)
92
+ ws = buildWorkspace(target, changes)
79
93
  } catch (e) {
80
94
  closeTarget(target)
81
95
  throw e
96
+ } finally {
97
+ closeTarget(target) // the scratch repo has done its job
98
+ }
99
+ const size = measureDiff(ws.diffText)
100
+ if (overLimit(size)) {
101
+ ws.cleanup()
102
+ if (auth.mode === 'gateway' && auth.preReview) {
103
+ // The Action already opened a review for this run: close it as failed so it is charged 0 credits.
104
+ try { await createGatewayClient({ apiUrl: env.MEGALENS_API_URL || DEFAULT_API_URL, token: auth.token, fetchImpl, env }).complete(auth.preReview.id, 'failed', 'too_large') } catch { /* the server also closes on expiry */ }
105
+ }
106
+ throw new RefusedError(tooLargeMessage(size.files, size.lines), 'too_large', {
107
+ reviewId: auth.mode === 'gateway' && auth.preReview ? auth.preReview.id : null,
108
+ target: { kind: target.kind, base: target.base, head: target.head, snapshot_sha256: snapshot },
109
+ })
82
110
  }
83
111
  const plan = planPasses(tier, { hasFirstReview: !!firstReview })
84
112
  const jobTimeout = Number.isFinite(timeoutMin) && timeoutMin > 0 ? timeoutMin : TIERS[tier].timeoutMin
@@ -108,17 +136,11 @@ export async function prepare({ tiers, codexBin, pinned, modes, unsafeNoIsolatio
108
136
  reviewId = `rv_${randomBytes(9).toString('base64url')}`
109
137
  }
110
138
  } catch (e) {
111
- // A refused or failed create must not leave the scratch repository (it holds every changed file) in the temp dir.
112
- closeTarget(target)
139
+ // A refused or failed create must not leave the workspace (it holds every changed file) in the temp dir.
140
+ ws.cleanup()
113
141
  throw e
114
142
  }
115
143
 
116
- let ws
117
- try {
118
- ws = buildWorkspace(target, changes)
119
- } finally {
120
- closeTarget(target) // the scratch repo has done its job
121
- }
122
144
  const notes = []
123
145
  if (changes.excluded.length) notes.push(`${changes.excluded.length} changed file(s) were not sent for review (agent config or credential-shaped)`)
124
146
  if (changes.baseSkipped) notes.push(`${changes.baseSkipped} unchanged file(s) too large to copy were left out of the snapshot`)
@@ -179,6 +201,8 @@ async function executeInner({ job, reviewKey, auth, env, fetchImpl, signal }) {
179
201
  let usage = { requests: 0, input_tokens: 0, cached_input_tokens: 0, output_tokens: 0 }
180
202
  let firstFindings = job.first_review
181
203
  let cancelled = false
204
+ let sandboxUnusable = false
205
+ let blindPass = null
182
206
  let proxy = null
183
207
 
184
208
  const runOne = async (pass, prompt) => {
@@ -218,6 +242,7 @@ async function executeInner({ job, reviewKey, auth, env, fetchImpl, signal }) {
218
242
  : null,
219
243
  })
220
244
  if (r.reason === 'cancelled') cancelled = true
245
+ if (r.reason === 'sandbox_unusable') { sandboxUnusable = true; blindPass ??= pass.name }
221
246
  return r
222
247
  } finally {
223
248
  if (job.mode === 'byo-login') writeBackLogin(home.home, auth.loginAuthPath)
@@ -268,7 +293,7 @@ async function executeInner({ job, reviewKey, auth, env, fetchImpl, signal }) {
268
293
  // Nothing to review: complete, no passes, and the note says so.
269
294
  } else {
270
295
  for (const pass of job.plan) {
271
- if (cancelled) break
296
+ if (cancelled || sandboxUnusable) break
272
297
  let prompt = null
273
298
  if (pass.kind === 'ctx') {
274
299
  const fs = (firstFindings ?? [])
@@ -331,6 +356,14 @@ async function executeInner({ job, reviewKey, auth, env, fetchImpl, signal }) {
331
356
  let droppedFindings = []
332
357
  if (job.quiet) ({ findings, dropped, droppedFindings } = applyQuiet(findings, { diffRanges }))
333
358
  if (cancelled && status === 'complete') status = 'failed'
359
+ // The environment, not the customer's work, made the review blind: the review ends failed (0 credits on the server) whatever else ran.
360
+ if (sandboxUnusable) {
361
+ status = 'failed'
362
+ findings = []
363
+ dropped = 0
364
+ droppedFindings = []
365
+ notes.push(SANDBOX_UNUSABLE_TEXT)
366
+ }
334
367
 
335
368
  const doc = {
336
369
  schema: SCHEMA,
@@ -353,24 +386,28 @@ async function executeInner({ job, reviewKey, auth, env, fetchImpl, signal }) {
353
386
  if (problems.length) throw new LocalError(`internal error: invalid findings document (${problems[0]})`)
354
387
 
355
388
  if (client) {
356
- try { await client.complete(job.review_id, cancelled ? 'cancelled' : status) } catch { /* the server also closes on expiry */ }
389
+ // The server's reason never changes a charge, so the blind pass is waived (the server caps what it accepts: small, once per review).
390
+ if (sandboxUnusable && blindPass) { try { await client.waive(job.review_id, blindPass) } catch { /* refused: the server's caps decide */ } }
391
+ try { await (sandboxUnusable ? client.complete(job.review_id, 'failed', 'sandbox_unusable') : client.complete(job.review_id, cancelled ? 'cancelled' : status)) } catch { /* the server also closes on expiry */ }
357
392
  }
358
393
  return { doc, exit: exitCodeForStatus(status, refused) }
359
394
  }
360
395
 
361
396
  /** The document for a run that could not start or was refused before any pass. Never `complete`. */
362
- export function failureDoc({ reviewId = 'rv_none', tier, reason, refused = false }) {
397
+ export function failureDoc({ reviewId = 'rv_none', tier, reason, refused = false, notes = null, target = null }) {
363
398
  return {
364
399
  schema: SCHEMA,
365
400
  review_id: reviewId,
366
401
  tier,
367
402
  status: 'failed',
368
- target: { kind: 'uncommitted', base: null, head: null, snapshot_sha256: '0'.repeat(64) },
403
+ ...(reason === 'too_large' ? { reason } : {}),
404
+ target: target ?? { kind: 'uncommitted', base: null, head: null, snapshot_sha256: '0'.repeat(64) },
369
405
  passes: [{ name: refused ? 'gateway' : 'engine', model: '-', effort: '-', status: 'failed', minutes: 0, reason }],
370
406
  findings: [],
371
407
  dropped_by_quiet_mode: 0,
372
408
  dropped_findings: [],
373
409
  usage: { requests: 0, input_tokens: 0, cached_input_tokens: 0, output_tokens: 0 },
410
+ ...(notes ? { notes } : {}),
374
411
  ...(refused ? { refused: true } : {}),
375
412
  }
376
413
  }
@@ -16,10 +16,11 @@ export function exitCodeForStatus(status, refused = false) {
16
16
 
17
17
  /** Thrown for any refusal by the gateway (auth, quota, spend cap, concurrency). */
18
18
  export class RefusedError extends Error {
19
- constructor(message, code = 'refused') {
19
+ constructor(message, code = 'refused', detail = null) {
20
20
  super(message)
21
21
  this.name = 'RefusedError'
22
22
  this.code = code
23
+ this.detail = detail // e.g. { reviewId, target } for a too_large refusal, so the findings document can name them
23
24
  }
24
25
  }
25
26
 
@@ -30,3 +31,14 @@ export class LocalError extends Error {
30
31
  this.name = 'LocalError'
31
32
  }
32
33
  }
34
+
35
+ /** The runner blocks the sandbox Codex starts inside the engine's own (Ubuntu AppArmor). Local error, exit 4, nothing charged. */
36
+ export class SandboxUnusableError extends LocalError {
37
+ constructor(message = SANDBOX_UNUSABLE_TEXT) {
38
+ super(message)
39
+ this.name = 'SandboxUnusableError'
40
+ this.reason = 'sandbox_unusable'
41
+ }
42
+ }
43
+
44
+ export const SANDBOX_UNUSABLE_TEXT = 'Your runner blocks nested sandboxes (Ubuntu AppArmor). Add this to the workflow step that installs bubblewrap: sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 || true; for p in /etc/apparmor.d/bwrap-userns-restrict /etc/apparmor.d/unprivileged_userns; do [ -f $p ] && sudo apparmor_parser -R $p || true; done'
@@ -49,7 +49,7 @@ export function createGatewayClient({ apiUrl = DEFAULT_API_URL, token, fetchImpl
49
49
  create: (body) => call(fetchImpl, 'POST', join(apiUrl, '/api/v2/reviews'), { token, body }),
50
50
  get: (id) => call(fetchImpl, 'GET', join(apiUrl, `/api/v2/reviews/${encodeURIComponent(id)}`), { token }),
51
51
  cancel: (id) => call(fetchImpl, 'POST', join(apiUrl, `/api/v2/reviews/${encodeURIComponent(id)}/cancel`), { token, body: {} }),
52
- complete: (id, outcome) => call(fetchImpl, 'POST', join(apiUrl, `/api/v2/reviews/${encodeURIComponent(id)}/complete`), { token, body: { outcome } }),
52
+ complete: (id, outcome, reason) => call(fetchImpl, 'POST', join(apiUrl, `/api/v2/reviews/${encodeURIComponent(id)}/complete`), { token, body: reason ? { outcome, reason } : { outcome } }),
53
53
  /** A short run is not charged to the customer: the server waives that pass (once per review, and only a small one). */
54
54
  waive: (id, pass) => call(fetchImpl, 'POST', join(apiUrl, `/api/v2/reviews/${encodeURIComponent(id)}/waive`), { token, body: { pass } }),
55
55
  baseUrlFor: (id) => join(apiUrl, `/api/v2/gw/${encodeURIComponent(id)}`),
package/src/isolation.mjs CHANGED
@@ -1,6 +1,7 @@
1
1
  import { spawnSync } from 'node:child_process'
2
- import { existsSync, lstatSync, readlinkSync, realpathSync } from 'node:fs'
3
- import { dirname } from 'node:path'
2
+ import { existsSync, lstatSync, mkdtempSync, readlinkSync, realpathSync, rmSync } from 'node:fs'
3
+ import { tmpdir } from 'node:os'
4
+ import { dirname, join } from 'node:path'
4
5
  import { fileURLToPath } from 'node:url'
5
6
  import { LocalError } from './exit-codes.mjs'
6
7
 
@@ -95,3 +96,20 @@ export function wrapCommand(isolation, bin, args, ctx) {
95
96
  }
96
97
  return { bin: 'bwrap', args: [...buildBwrapArgs({ ...ctx, codexBin: bin }), '--', bin, ...args] }
97
98
  }
99
+
100
+ /**
101
+ * Preflight: can the sandbox Codex starts for its own commands start INSIDE the engine's sandbox? Runs the same nested shape once:
102
+ * the outer bwrap exactly as the engine builds it, then `bwrap --unshare-user ... true` inside. On a runner whose AppArmor blocks
103
+ * unprivileged user namespaces the nested one fails, and every command the model would try fails with it.
104
+ * Returns true when the nested sandbox starts. `run` is injectable for tests: (bin, args, env) => exit status.
105
+ */
106
+ export function nestedSandboxWorks(env = process.env, run = (bin, args, e) => spawnSync(bin, args, { stdio: 'ignore', env: e, timeout: 30000 }).status) {
107
+ const dir = mkdtempSync(join(tmpdir(), 'mlr-preflight-'))
108
+ try {
109
+ const outer = buildBwrapArgs({ workspace: dir, codexHome: dir, homeDir: dir, codexBin: 'bwrap', pathVar: env.PATH, network: 'none' })
110
+ const args = [...outer, '--', 'bwrap', '--unshare-user', '--ro-bind', '/', '/', '--', 'true']
111
+ return run('bwrap', args, { PATH: env.PATH ?? '' }) === 0
112
+ } finally {
113
+ rmSync(dir, { recursive: true, force: true })
114
+ }
115
+ }
package/src/limits.mjs ADDED
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Size limits for one review. The ONE place they are set (README documents them).
3
+ * Measured 21 Nov 2026: 136-138 files / 22-30K lines worked (partial) on Standard; 263+ files / 42K+ lines (1.1-1.4M input tokens) failed.
4
+ * Deep runs the same limits: the code pins no larger context for Deep (tiers.mjs), so it gets no larger allowance.
5
+ *
6
+ * The count is taken from the diff that is SENT to the model (the review workspace's own diff, after the engine's real exclusions),
7
+ * never from a separate git listing, so no repo attribute (.gitattributes, linguist, -diff) can lower it.
8
+ *
9
+ * Bytes: a minified one-line file is 1 line but megabytes. 40,000 lines at the observed 50-80 bytes a line is 2-3 MB, and the
10
+ * failed runs were about 4+ MB of changed text, so the total cap is 3 MiB (above the measured working range, below the failing one).
11
+ * One file may not be more than 512 KiB of diff (a normal source file is far smaller; the engine copies up to 2 MiB per file).
12
+ */
13
+ export const MAX_CHANGED_FILES = 250
14
+ export const MAX_CHANGED_LINES = 40_000
15
+ export const MAX_CHANGED_BYTES = 3 * 1024 * 1024
16
+ export const MAX_FILE_DIFF_BYTES = 512 * 1024
17
+
18
+ /**
19
+ * Measure the unified diff the model is given. Every `diff --git` section is a file (binary files too); lines are the
20
+ * added and removed lines inside hunks; bytes are the diff text itself, in total and for the biggest single file.
21
+ * @returns {{files:number, lines:number, bytes:number, maxFileBytes:number}}
22
+ */
23
+ export function measureDiff(diffText) {
24
+ const text = String(diffText ?? '')
25
+ let files = 0
26
+ let lines = 0
27
+ let maxFileBytes = 0
28
+ let inHunk = false
29
+ let sectionBytes = 0
30
+ const close = () => { if (sectionBytes > maxFileBytes) maxFileBytes = sectionBytes }
31
+ let pos = 0
32
+ while (pos < text.length) {
33
+ let nl = text.indexOf('\n', pos)
34
+ if (nl < 0) nl = text.length
35
+ const len = nl - pos + 1
36
+ if (text.startsWith('diff --git ', pos)) {
37
+ close()
38
+ files += 1
39
+ sectionBytes = 0
40
+ inHunk = false
41
+ } else if (text.startsWith('@@', pos)) {
42
+ inHunk = true
43
+ } else if (inHunk) {
44
+ const c = text.charCodeAt(pos)
45
+ if (c === 43 || c === 45) lines += 1 // '+' or '-'
46
+ }
47
+ sectionBytes += Buffer.byteLength(text.slice(pos, nl)) + 1
48
+ pos += len
49
+ }
50
+ close()
51
+ return { files, lines, bytes: Buffer.byteLength(text), maxFileBytes }
52
+ }
53
+
54
+ /** True when a measured change is over any limit. */
55
+ export function overLimit(m) {
56
+ return m.files > MAX_CHANGED_FILES || m.lines > MAX_CHANGED_LINES || m.bytes > MAX_CHANGED_BYTES || m.maxFileBytes > MAX_FILE_DIFF_BYTES
57
+ }
58
+
59
+ export function tooLargeMessage(files, lines) {
60
+ return `This change is too large for one review (${files} files, about ${lines} lines). Split it into smaller pull requests, or review one folder.`
61
+ }