Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix: defer finalize Chrome startup until pre-browser gates pass

Buffalo20245046183808e0
diff --git a/archify.zip b/archify.zip
index d3da6b28..d065d928 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/bin/finalize.mjs b/archify/bin/finalize.mjs
index d3b39f0f..8897045e 100644
--- a/archify/bin/finalize.mjs
+++ b/archify/bin/finalize.mjs
@@ -782,22 +782,12 @@ export async function runFinalize({
// update check in parallel instead of timing out on every delivery.
const updateCheck = startUpdateCheck({ env, deadlineMs: FINALIZE_UPDATE_DEADLINE_MS });
- // Only launch/attach the blank browser here. The normal browser gate still
- // verifies current delivery provenance before it consumes this one-shot factory.
- const chromePath = runBrowserCheck ? resolveChrome({ env }) : null;
+ // Resolve and launch Chrome only after delivery and strict artifact checks pass.
+ // Invalid candidates must not start a browser that cannot inspect an artifact.
+ let chromePath = null;
let browser;
let browserStartupError;
let browserTransferred = false;
- if (chromePath) {
- try {
- browser = createBrowser(chromePath, { env });
- // Deliver/check may fail before inspect() awaits startup. Handle the
- // rejection now while retaining the same promise for the browser gate.
- browser.sessionPromise.catch(() => {});
- } catch (error) {
- browserStartupError = error;
- }
- }
const browserFactory = () => {
if (browserStartupError) throw browserStartupError;
if (browserTransferred || !browser) throw new Error('The finalize browser is unavailable or already consumed.');
@@ -821,6 +811,17 @@ export async function runFinalize({
const inProcess = stage === 'browser-check' && runBrowserCheck;
let result;
if (inProcess) {
+ chromePath = resolveChrome({ env });
+ if (chromePath) {
+ try {
+ browser = createBrowser(chromePath, { env });
+ // Retain the startup rejection for the browser gate without emitting
+ // an unhandled rejection before inspect() awaits the same promise.
+ browser.sessionPromise.catch(() => {});
+ } catch (error) {
+ browserStartupError = error;
+ }
+ }
const checked = await runBrowserCheck({
artifactPath: resolvedOutput,
outDir: resolvedOutDir,
diff --git a/archify/references/delivery-contract.md b/archify/references/delivery-contract.md
index 8898da14..2673e01c 100644
--- a/archify/references/delivery-contract.md
+++ b/archify/references/delivery-contract.md
@@ -293,13 +293,16 @@ them directly for focused diagnosis, recovery, or when only one gate is
required. A finalize failure does not relax any gate and does not turn a
preserved older artifact into a current successful delivery.
-`finalize` overlaps private Chrome startup with delivery and strict checking.
-It loads the artifact only after those gates pass and current provenance is
-verified. The browser gate retains every viewport, theme, and stability check;
-the browser closes at completion or an earlier failure. Its full stage receipt
-records `execution: "in-process"` and the equivalent standalone `command` for
-replay. Use total finalize duration to compare performance because Chrome
-startup overlaps the earlier stages.
+`finalize` discovers and starts private Chrome only after delivery and strict
+checking pass. Failed input, repository-evidence, delivery, or artifact checks
+therefore do not launch a browser. It loads the artifact only after current
+provenance is verified. The browser gate retains every viewport, theme, and
+stability check; the browser closes at completion or a browser-stage failure.
+Its full stage receipt records `execution: "in-process"` and the equivalent
+standalone `command` for replay. Chrome startup no longer overlaps the earlier
+stages, so successful runs may take slightly longer. This avoids unnecessary
+startup on invalid candidates; it does not fix host sandbox restrictions on
+Chrome startup or relax a browser gate.
The pair commit is recoverable, not a claim that two filesystem paths change
atomically or are durable across power loss. Journal finalization is part of
diff --git a/test/finalize-browser-lifecycle.test.mjs b/test/finalize-browser-lifecycle.test.mjs
index 84d3b3ca..b4379966 100644
--- a/test/finalize-browser-lifecycle.test.mjs
+++ b/test/finalize-browser-lifecycle.test.mjs
@@ -149,7 +149,7 @@ function options({ input, output, outDir, runCommand, runBrowserCheck, resolveCh
};
}
-test('finalize prestarts Chrome during deliver without inspecting it before the browser gate consumes it', async t => {
+test('finalize launches Chrome only after delivery and strict artifact checks pass', async t => {
const { input, output, outDir, source } = inputs(t);
const events = [];
let delivered;
@@ -166,12 +166,12 @@ test('finalize prestarts Chrome during deliver without inspecting it before the
events.push(`run:${stage}`);
assert.deepEqual(events.filter((event) => event === 'inspect'), []);
if (stage === 'deliver') {
- assert.deepEqual(events, ['create', 'run:deliver']);
+ assert.deepEqual(events, ['run:deliver']);
await Promise.resolve();
delivered = delivery({ input, output, source });
return stageResult(delivered);
}
- assert.deepEqual(events, ['create', 'run:deliver', 'run:check']);
+ assert.deepEqual(events, ['run:deliver', 'run:check']);
return stageResult(check(output, delivered));
},
runBrowserCheck: async ({ artifactPath, outDir: receivedOutDir, chromePath, resolveChrome, browserFactory }) => {
@@ -189,17 +189,17 @@ test('finalize prestarts Chrome during deliver without inspecting it before the
assert.equal(finalized.exitCode, 0);
assert.equal(finalized.receipt.stages['browser-check'].execution, 'in-process');
- assert.deepEqual(events, ['create', 'run:deliver', 'run:check', 'inspect', 'close']);
+ assert.deepEqual(events, ['run:deliver', 'run:check', 'create', 'inspect', 'close']);
});
-test('finalize closes a prestarted browser without navigation when deliver or check fails', async t => {
+test('finalize does not discover or launch Chrome when delivery or strict checks fail', async t => {
for (const failedStage of ['deliver', 'check']) {
const { input, output, outDir, source } = inputs(t);
const events = [];
let delivered;
const finalized = await runFinalize(options({
input, output, outDir,
- resolveChrome: () => '/fake/chrome',
+ resolveChrome: () => { events.push('discover'); return '/fake/chrome'; },
createBrowser: () => { events.push('create'); return browser(events); },
runBrowserCheck: () => { throw new Error('browser gate must not run'); },
runCommand: ({ stage }) => {
@@ -212,11 +212,13 @@ test('finalize closes a prestarted browser without navigation when deliver or ch
assert.equal(finalized.exitCode, 1, failedStage);
assert.equal(finalized.receipt.failedStage, failedStage === 'deliver' ? 'deliver' : 'check', failedStage);
assert.equal(events.includes('inspect'), false, failedStage);
- assert.equal(events.filter((event) => event === 'close').length, 1, failedStage);
+ assert.equal(events.includes('discover'), false, failedStage);
+ assert.equal(events.includes('create'), false, failedStage);
+ assert.equal(events.includes('close'), false, failedStage);
}
});
-test('a rejected Chrome attach does not replace a delivery failure or emit an unhandled rejection', async t => {
+test('a delivery failure never invokes a Chrome factory whose attach would reject', async t => {
const { input, output, outDir } = inputs(t);
const events = [];
const unhandled = [];
@@ -226,7 +228,10 @@ test('a rejected Chrome attach does not replace a delivery failure or emit an un
const finalized = await runFinalize(options({
input, output, outDir,
resolveChrome: () => '/fake/chrome',
- createBrowser: () => browser(events, Promise.reject(new Error('attach failed'))),
+ createBrowser: () => {
+ events.push('create');
+ return browser(events, Promise.reject(new Error('attach failed')));
+ },
runBrowserCheck: () => { throw new Error('browser gate must not run'); },
runCommand: () => stageResult({ ok: false, command: 'deliver', diagnostics: [] }, 1),
}));
@@ -234,7 +239,7 @@ test('a rejected Chrome attach does not replace a delivery failure or emit an un
assert.equal(finalized.exitCode, 1);
assert.equal(finalized.receipt.failedStage, 'deliver');
assert.deepEqual(unhandled, []);
- assert.deepEqual(events, ['close']);
+ assert.deepEqual(events, []);
} finally {
process.off('unhandledRejection', onUnhandled);
}