start-command 0.30.4 → 0.31.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # start-command
 
+## 0.31.0
+
+### Minor Changes
+
+- b14f11c: Add `--network` and repeatable `--network-alias` options for Docker-isolated commands.
+
+## 0.30.5
+
+### Patch Changes
+
+- d0656c2: Stop `--status` from fabricating a detached session exit code out of the command's own output: the terminal exit code is now read from the anchored three-line footer `start` writes (separator / `Finished:` / `Exit Code:`) in the tail of the log only, and Docker's own `.State.ExitCode` takes precedence over the log text.
+
 ## 0.30.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.30.4",
+  "version": "0.31.0",
   "description": "Gamification of coding, execute any command with ability to auto-report issues on GitHub",
   "main": "src/bin/cli.js",
   "exports": {

package/src/bin/cli.js

@@ -581,10 +581,7 @@ async function runWithIsolation(
       alwaysCleanupContainer: options.alwaysCleanupContainer,
       keepContainer: options.keepContainer,
       keepContainerOnFail: options.keepContainerOnFail,
-      volumes: options.volumes,
-      mounts: options.mounts,
-      env: options.env,
-      privileged: options.privileged,
+      ...buildDockerRuntimeMetadata(options),
       shell: options.shell,
       logPath: logFilePath,
     });

package/src/lib/args-parser.js

@@ -15,6 +15,8 @@
  * --mount <mount-spec>             Docker --mount spec (repeatable, docker only)
  * --env, -e <KEY=VALUE>            Environment variable for docker container (repeatable, docker only)
  * --privileged                     Run docker container in privileged mode (docker only)
+ * --network <name>                 Connect docker container to a named network (docker only)
+ * --network-alias <alias>          Add a network-scoped alias (repeatable, docker only)
  * --endpoint <endpoint>            SSH endpoint (required for ssh isolation, e.g., user@host)
  * --isolated-user, -u [username]   Create isolated user with same permissions (auto-generated name if not specified)
  * --keep-user                      Keep isolated user after command completes (don't delete)
@@ -37,6 +39,7 @@
  */
 
 const { getDefaultDockerImage } = require('./docker-utils');
+const dockerNetworkOptions = require('./docker-network-options');
 const { parseSequence, isSequence } = require('./sequence-parser');
 
 // Debug mode from environment
@@ -178,6 +181,8 @@ function parseArgs(args) {
     mounts: [], // Docker --mount specs, applied to docker levels
     env: [], // Docker environment variables (-e/--env, KEY=VALUE), applied to docker levels
     privileged: false, // Run docker container in privileged mode
+    network: null, // Docker network name
+    networkAliases: [], // Docker network-scoped aliases
     endpoint: null, // SSH endpoint (current level, e.g., user@host)
     endpointStack: null, // SSH endpoints for each level (with nulls for non-ssh levels)
     user: false, // Create isolated user
@@ -396,6 +401,11 @@ function parseOption(args, index, options) {
     return 1;
   }
 
+  const networkOption = dockerNetworkOptions.parse(args, index, options);
+  if (networkOption) {
+    return networkOption;
+  }
+
   // --endpoint (for ssh) - supports sequence for stacked isolation
   if (arg === '--endpoint') {
     if (index + 1 < args.length && !args[index + 1].startsWith('-')) {
@@ -645,8 +655,7 @@ function parseOption(args, index, options) {
 }
 
 /**
- * Throw if docker runtime options (--volume, --mount, --env, --privileged)
- * are present but the isolation configuration does not include docker.
+ * Throw if docker runtime options are present without docker isolation.
  * @param {object} options - Parsed options
  * @throws {Error} If a docker-only option is set without docker isolation
  */
@@ -671,6 +680,7 @@ function validateDockerRuntimeOptionsRequireDocker(options) {
       '--privileged option is only valid when isolation stack includes docker'
     );
   }
+  dockerNetworkOptions.validateRequireDocker(options);
 }
 
 function validateDockerCleanupOptions(options, hasDocker) {

package/src/lib/docker-cleanup.js

@@ -109,6 +109,22 @@ function readDockerContainerOomKilled(containerName) {
   return null;
 }
 
+function readDockerContainerStatus(containerName) {
+  const result = spawnSync(
+    getDockerCommand(),
+    ['inspect', '-f', '{{.State.Status}}', containerName],
+    getDockerSpawnOptions({
+      encoding: 'utf8',
+      env: process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+  );
+  if (result.error || result.status !== 0) {
+    return null;
+  }
+  return String(result.stdout || '').trim() || null;
+}
+
 function removeDockerContainer(containerName, logPath = null) {
   const result = spawnSync(
     getDockerCommand(),
@@ -237,6 +253,7 @@ module.exports = {
   getDockerContainerCleanupInstructions,
   appendDockerContainerCleanupPolicyMessage,
   readDockerContainerOomKilled,
+  readDockerContainerStatus,
   removeDockerContainer,
   buildDetachedDockerCompletionScript,
   startDetachedDockerCompletionWatcher,

package/src/lib/docker-network-options.js

@@ -0,0 +1,44 @@
+/** Parse and validate Docker network wrapper options. */
+
+function parseDockerNetworkOption(args, index, options) {
+  const arg = args[index];
+  if (arg === '--network' || arg === '--network-alias') {
+    if (index + 1 >= args.length || args[index + 1].startsWith('-')) {
+      const value = arg === '--network' ? 'network name' : 'alias';
+      throw new Error(`Option ${arg} requires a ${value} argument`);
+    }
+    if (arg === '--network') {
+      options.network = args[index + 1];
+    } else {
+      options.networkAliases.push(args[index + 1]);
+    }
+    return 2;
+  }
+  if (arg.startsWith('--network=')) {
+    options.network = arg.slice('--network='.length);
+    return 1;
+  }
+  if (arg.startsWith('--network-alias=')) {
+    options.networkAliases.push(arg.slice('--network-alias='.length));
+    return 1;
+  }
+  return 0;
+}
+
+function validateDockerNetworkOptionsRequireDocker(options) {
+  if (options.network) {
+    throw new Error(
+      '--network option is only valid when isolation stack includes docker'
+    );
+  }
+  if (options.networkAliases?.length > 0) {
+    throw new Error(
+      '--network-alias option is only valid when isolation stack includes docker'
+    );
+  }
+}
+
+module.exports = {
+  parse: parseDockerNetworkOption,
+  validateRequireDocker: validateDockerNetworkOptionsRequireDocker,
+};

package/src/lib/isolation.js

@@ -28,6 +28,7 @@ const {
   getDockerContainerCleanupInstructions,
   appendDockerContainerCleanupPolicyMessage,
   readDockerContainerOomKilled,
+  readDockerContainerStatus,
   removeDockerContainer,
   startDetachedDockerCompletionWatcher,
   spawnAttachedDocker,
@@ -499,9 +500,9 @@ const {
 /**
  * Build the docker run runtime argument list contributed by configurable
  * container options: privileged mode, environment variables, volumes/bind
- * mounts, and --mount specs. Returned in a stable order so they can be spliced
+ * mounts, --mount specs, and network configuration. Returned in a stable order so they can be spliced
  * into the `docker run` argv before the image name.
- * @param {object} options - Options (privileged, env, volumes, mounts)
+ * @param {object} options - Options (privileged, env, volumes, mounts, network, networkAliases)
  * @returns {string[]} Docker CLI arguments
  */
 function buildDockerRuntimeArgs(options = {}) {
@@ -518,6 +519,12 @@ function buildDockerRuntimeArgs(options = {}) {
   for (const mount of options.mounts || []) {
     args.push('--mount', mount);
   }
+  if (options.network) {
+    args.push('--network', options.network);
+  }
+  for (const alias of options.networkAliases || []) {
+    args.push('--network-alias', alias);
+  }
   return args;
 }
 
@@ -542,6 +549,14 @@ function buildDockerRuntimeStatusLines(options = {}) {
   if (options.privileged) {
     lines.push(`[Isolation] Privileged: true`);
   }
+  if (options.network) {
+    lines.push(`[Isolation] Network: ${options.network}`);
+  }
+  if (options.networkAliases && options.networkAliases.length > 0) {
+    lines.push(
+      `[Isolation] Network aliases: ${options.networkAliases.join(', ')}`
+    );
+  }
   return lines;
 }
 
@@ -549,7 +564,7 @@ function buildDockerRuntimeStatusLines(options = {}) {
  * Build the execution-record metadata for docker runtime options, normalizing
  * empty collections and a falsy privileged flag to `null`.
  * @param {object} options - Options (volumes, mounts, env, privileged)
- * @returns {{volumes: ?string[], mounts: ?string[], env: ?string[], privileged: ?boolean}}
+ * @returns {{volumes: ?string[], mounts: ?string[], env: ?string[], privileged: ?boolean, network: ?string, networkAliases: ?string[]}}
  */
 function buildDockerRuntimeMetadata(options = {}) {
   return {
@@ -558,6 +573,11 @@ function buildDockerRuntimeMetadata(options = {}) {
     mounts: options.mounts && options.mounts.length > 0 ? options.mounts : null,
     env: options.env && options.env.length > 0 ? options.env : null,
     privileged: options.privileged || null,
+    network: options.network || null,
+    networkAliases:
+      options.networkAliases && options.networkAliases.length > 0
+        ? options.networkAliases
+        : null,
   };
 }
 
@@ -597,6 +617,8 @@ function runInDocker(command, options = {}) {
   }
 
   const containerName = options.session || generateSessionName('docker');
+  const containerExistedBeforeLaunch =
+    readDockerContainerStatus(containerName) !== null;
   const cleanupPolicy = getDockerContainerCleanupPolicy(options);
   if (!dockerImageExists(options.image)) {
     // Pass logPath so the image-preparation phase (docker pull) is recorded in
@@ -671,6 +693,12 @@ function runInDocker(command, options = {}) {
           dockerResult.stderr.trim() ||
           dockerResult.stdout.trim() ||
           `docker exited with code ${dockerResult.status}`;
+        if (
+          !containerExistedBeforeLaunch &&
+          readDockerContainerStatus(containerName) === 'created'
+        ) {
+          removeDockerContainer(containerName, options.logPath);
+        }
         throw new Error(dockerError);
       }
 
@@ -760,8 +788,17 @@ function runInDocker(command, options = {}) {
           }
 
           const oomKilled = readDockerContainerOomKilled(containerName);
+          const launchFailed =
+            !containerExistedBeforeLaunch &&
+            readDockerContainerStatus(containerName) === 'created';
 
-          if (
+          if (launchFailed) {
+            if (removeDockerContainer(containerName, options.logPath)) {
+              message += `\nContainer removed after launch failure.`;
+            } else {
+              message += `\nWarning: failed to remove container after launch failure.`;
+            }
+          } else if (
             shouldCleanupDockerContainer(cleanupPolicy, exitCode, oomKilled)
           ) {
             if (removeDockerContainer(containerName, options.logPath)) {

package/src/lib/status-formatter.js

@@ -175,20 +175,88 @@ function isDetachedSessionAlive(record) {
   }
 }
 
+/**
+ * Number of trailing bytes scanned for the terminal log footer. The footer is
+ * always appended at the very end of the log, so there is no reason to read
+ * (potentially megabytes of) command output on every `--status` call.
+ */
+const LOG_TAIL_BYTES = 16 * 1024;
+
+/**
+ * The three-line terminal footer that `start` itself writes (see
+ * `createLogFooter()` and `createShellLogFooterSnippet()`):
+ *
+ *   ==================================================
+ *   Finished: 2026-07-30 23:36:20.295
+ *   Exit Code: 0
+ *
+ * The whole block is anchored at line starts so that a bare `Exit Code: N`
+ * substring emitted by the wrapped command (inside a JSON payload, a quoted
+ * log excerpt, an `rg` dump, ...) can no longer be mistaken for the footer
+ * `start` appends itself (issue #150).
+ */
+const LOG_FOOTER_PATTERN =
+  /^={10,}[ \t]*\r?\n^Finished:[^\r\n]*\r?\n^Exit Code:[ \t]*(-?\d+)[ \t]*(?![^\r\n])/gm;
+
+/**
+ * Read the last `bytes` bytes of a file as UTF-8 text.
+ *
+ * A partial first line is dropped: the slice can start in the middle of a line,
+ * and that fragment must not be treated as the beginning of a line by the
+ * anchored footer pattern.
+ *
+ * @param {string} logPath - Path to the log file
+ * @param {number} [bytes] - Maximum number of trailing bytes to read
+ * @returns {string|null} Tail content, or null when the file cannot be read
+ */
+function readLogTail(logPath, bytes = LOG_TAIL_BYTES) {
+  let fd;
+  try {
+    fd = fs.openSync(logPath, 'r');
+    const size = fs.fstatSync(fd).size;
+    const length = Math.min(size, bytes);
+    const buffer = Buffer.alloc(length);
+    fs.readSync(fd, buffer, 0, length, size - length);
+    const tail = buffer.toString('utf8');
+    if (size <= bytes) {
+      return tail;
+    }
+    const firstNewline = tail.indexOf('\n');
+    return firstNewline === -1 ? '' : tail.slice(firstNewline + 1);
+  } catch {
+    return null;
+  } finally {
+    if (fd !== undefined) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}
+
+/**
+ * Read the terminal exit code from the anchored footer at the end of a log.
+ * Returns null when the log has no footer yet (command still running, or the
+ * host-side watcher has not appended it yet) — never a number parsed out of the
+ * command's own output.
+ * @param {string} logPath - Path to the log file
+ * @returns {number|null}
+ */
 function readExitCodeFromLog(logPath) {
   if (!logPath) {
     return null;
   }
-  try {
-    const content = fs.readFileSync(logPath, 'utf8');
-    const matches = [...content.matchAll(/Exit Code:\s*(-?\d+)/g)];
-    if (matches.length === 0) {
-      return null;
-    }
-    return parseInt(matches[matches.length - 1][1], 10);
-  } catch {
+  const tail = readLogTail(logPath);
+  if (tail === null) {
     return null;
   }
+  const matches = [...tail.matchAll(LOG_FOOTER_PATTERN)];
+  if (matches.length === 0) {
+    return null;
+  }
+  return parseInt(matches[matches.length - 1][1], 10);
 }
 
 /**
@@ -280,15 +348,17 @@ function enrichDetachedStatus(record) {
     // Otherwise keep the recorded/footer exit code - the command has finished.
   } else if (!alive && enriched.status === 'executing') {
     // Session ended but record says executing - correct it. Resolve a real exit
-    // code: prefer the log footer, then the backend's own record (e.g.
-    // `docker inspect .State.ExitCode`), then `137` when the only evidence left
-    // is the OOM observation, and only fall back to the `-1` sentinel as a last
-    // resort when no real code can be obtained (issues #136, #151).
+    // code: prefer the backend's own record (e.g. `docker inspect
+    // .State.ExitCode`, which is authoritative and cannot be spoofed by command
+    // output — issue #150), then the anchored log footer, then `137` when the
+    // only evidence left is the OOM observation, and only fall back to the `-1`
+    // sentinel as a last resort when no real code can be obtained (issues #136,
+    // #151).
     enriched.status = 'executed';
     if (enriched.exitCode === null || enriched.exitCode === undefined) {
       enriched.exitCode =
-        footerExit ??
         backendExitCode(dockerState) ??
+        footerExit ??
         (oomKilled === true ? 137 : -1);
     }
     if (!enriched.endTime) {
@@ -638,6 +708,8 @@ module.exports = {
   listExecutions,
   isDetachedSessionAlive,
   enrichDetachedStatus,
+  readExitCodeFromLog,
+  readLogTail,
   attachCurrentTime,
   attachProcessIds,
 };

package/src/lib/usage.js

@@ -14,6 +14,8 @@ Options:
   --mount <spec>        Docker --mount spec (repeatable, docker only)
   --env, -e <KEY=VALUE> Environment variable for docker container (repeatable, docker only)
   --privileged          Run docker container in privileged mode (docker only)
+  --network <name>      Connect docker container to a named network (docker only)
+  --network-alias <alias> Add network-scoped alias (repeatable, docker only)
   --endpoint <endpoint> SSH endpoint (required for ssh isolation, e.g., user@host)
   --isolated-user, -u [name]  Create isolated user with same permissions
   --keep-user           Keep isolated user after command completes

package/test/docker-network-integration.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env bun
+/** Real-daemon integration coverage for Docker network isolation (issue #154). */
+
+const { after, before, describe, it } = require('node:test');
+const assert = require('assert');
+const { spawnSync } = require('child_process');
+const { randomUUID } = require('crypto');
+const { runInDocker } = require('../src/lib/isolation');
+
+const suffix = randomUUID().slice(0, 8);
+const network = `start-network-${suffix}`;
+const sidecar = `start-sidecar-${suffix}`;
+const connected = `start-connected-${suffix}`;
+const control = `start-control-${suffix}`;
+const missing = `start-missing-${suffix}`;
+const missingAttached = `start-missing-attached-${suffix}`;
+let dockerAvailable = false;
+
+function docker(args) {
+  return spawnSync('docker', args, { encoding: 'utf8' });
+}
+
+describe('Docker named network integration', { timeout: 60000 }, () => {
+  before(() => {
+    dockerAvailable =
+      process.platform === 'linux' && docker(['info']).status === 0;
+    if (!dockerAvailable) {
+      return;
+    }
+
+    const created = docker(['network', 'create', '--internal', network]);
+    assert.strictEqual(created.status, 0, created.stderr);
+    const started = docker([
+      'run',
+      '-d',
+      '--name',
+      sidecar,
+      '--network',
+      network,
+      '--network-alias',
+      'formal-ai',
+      'alpine:3.23',
+      'sleep',
+      '60',
+    ]);
+    assert.strictEqual(started.status, 0, started.stderr);
+  });
+
+  after(() => {
+    if (!dockerAvailable) {
+      return;
+    }
+    docker(['rm', '-f', sidecar, connected, control, missing, missingAttached]);
+    docker(['network', 'rm', network]);
+  });
+
+  it('resolves an alias only from containers joined to the internal network', async () => {
+    if (!dockerAvailable) {
+      return;
+    }
+
+    const joined = await runInDocker('ping -c 1 formal-ai', {
+      image: 'alpine:3.23',
+      session: connected,
+      network,
+      networkAliases: ['task'],
+      detached: true,
+      shell: 'sh',
+      keepContainer: true,
+    });
+    assert.strictEqual(joined.success, true, joined.message);
+    const joinedExit = docker(['wait', connected]);
+    assert.strictEqual(joinedExit.status, 0, joinedExit.stderr);
+    assert.strictEqual(joinedExit.stdout.trim(), '0');
+
+    const unconnected = await runInDocker('ping -c 1 formal-ai', {
+      image: 'alpine:3.23',
+      session: control,
+      shell: 'sh',
+      alwaysCleanupContainer: true,
+    });
+    assert.strictEqual(unconnected.success, false);
+  });
+
+  it('fails for a missing network without orphaning a container', async () => {
+    if (!dockerAvailable) {
+      return;
+    }
+
+    const result = await runInDocker('echo should-not-run', {
+      image: 'alpine:3.23',
+      session: missing,
+      network: `${network}-absent`,
+      detached: true,
+      shell: 'sh',
+    });
+    assert.strictEqual(result.success, false);
+    assert.match(result.message, /network .* not found/i);
+    assert.notStrictEqual(docker(['inspect', missing]).status, 0);
+
+    const attachedResult = await runInDocker('echo should-not-run', {
+      image: 'alpine:3.23',
+      session: missingAttached,
+      network: `${network}-absent`,
+      shell: 'sh',
+    });
+    assert.strictEqual(attachedResult.success, false);
+    assert.notStrictEqual(docker(['inspect', missingAttached]).status, 0);
+
+    const conflict = await runInDocker('echo should-not-run', {
+      image: 'alpine:3.23',
+      session: sidecar,
+      network: `${network}-absent`,
+      detached: true,
+      shell: 'sh',
+    });
+    assert.strictEqual(conflict.success, false);
+    assert.strictEqual(docker(['inspect', sidecar]).status, 0);
+  });
+});

package/test/docker-runtime-options.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 /**
- * Tests for Docker runtime options: --volume/-v, --mount, --env/-e, --privileged
+ * Tests for Docker runtime options: --volume/-v, --mount, --env/-e,
+ * --privileged, --network, and --network-alias
  *
  * Reproduces issue #132: callers need to configure bind mounts, volumes,
  * environment variables, and privileged mode for the docker isolation backend
@@ -90,12 +91,58 @@ describe('Docker runtime options parsing', () => {
     assert.strictEqual(result.wrapperOptions.privileged, true);
   });
 
+  it('should parse --network value and equals forms without consuming child args', () => {
+    const spaced = parseArgs([
+      '-i',
+      'docker',
+      '--network',
+      'hive-formal-ai',
+      '--',
+      '--network',
+      'child-network',
+    ]);
+    const equals = parseArgs([
+      '-i',
+      'docker',
+      '--network=hive-formal-ai',
+      '--',
+      'echo',
+      'ok',
+    ]);
+
+    assert.strictEqual(spaced.wrapperOptions.network, 'hive-formal-ai');
+    assert.deepStrictEqual(spaced.rawCommand, ['--network', 'child-network']);
+    assert.strictEqual(equals.wrapperOptions.network, 'hive-formal-ai');
+  });
+
+  it('should parse repeatable --network-alias value and equals forms', () => {
+    const result = parseArgs([
+      '-i',
+      'docker',
+      '--network',
+      'hive-formal-ai',
+      '--network-alias',
+      'formal-ai',
+      '--network-alias=checker',
+      '--',
+      'echo',
+      'ok',
+    ]);
+
+    assert.deepStrictEqual(result.wrapperOptions.networkAliases, [
+      'formal-ai',
+      'checker',
+    ]);
+  });
+
   it('should default runtime options to empty/false', () => {
     const result = parseArgs(['-i', 'docker', '--', 'ls']);
     assert.deepStrictEqual(result.wrapperOptions.volumes, []);
     assert.deepStrictEqual(result.wrapperOptions.mounts, []);
     assert.deepStrictEqual(result.wrapperOptions.env, []);
     assert.strictEqual(result.wrapperOptions.privileged, false);
+    assert.strictEqual(result.wrapperOptions.network, null);
+    assert.deepStrictEqual(result.wrapperOptions.networkAliases, []);
   });
 
   it('should throw when --volume requires an argument', () => {
@@ -136,6 +183,15 @@ describe('Docker runtime options validation', () => {
     }, /--privileged option is only valid when isolation stack includes docker/);
   });
 
+  it('should reject network options without docker', () => {
+    assert.throws(() => {
+      parseArgs(['-i', 'tmux', '--network', 'private', '--', 'ls']);
+    }, /--network option is only valid when isolation stack includes docker/);
+    assert.throws(() => {
+      parseArgs(['--network-alias', 'service', '--', 'ls']);
+    }, /--network-alias option is only valid when isolation stack includes docker/);
+  });
+
   it('should accept runtime options when stack includes docker', () => {
     const result = parseArgs([
       '-i',
@@ -171,6 +227,8 @@ describe('buildDockerRuntimeArgs', () => {
       env: ['FOO=bar', 'GH_TOKEN=secret'],
       volumes: ['/h/a:/c/a', '/h/b:/c/b:ro'],
       mounts: ['type=bind,src=/h,dst=/c'],
+      network: 'hive-formal-ai',
+      networkAliases: ['formal-ai', 'checker'],
     });
     assert.deepStrictEqual(args, [
       '--privileged',
@@ -184,6 +242,12 @@ describe('buildDockerRuntimeArgs', () => {
       '/h/b:/c/b:ro',
       '--mount',
       'type=bind,src=/h,dst=/c',
+      '--network',
+      'hive-formal-ai',
+      '--network-alias',
+      'formal-ai',
+      '--network-alias',
+      'checker',
     ]);
   });
 });
@@ -199,12 +263,16 @@ describe('buildDockerRuntimeStatusLines', () => {
       mounts: ['type=bind,src=/h,dst=/c'],
       env: ['FOO=bar'],
       privileged: true,
+      network: 'hive-formal-ai',
+      networkAliases: ['formal-ai', 'checker'],
     });
     assert.deepStrictEqual(lines, [
       '[Isolation] Volumes: /h:/c:ro',
       '[Isolation] Mounts: type=bind,src=/h,dst=/c',
       '[Isolation] Env: FOO=bar',
       '[Isolation] Privileged: true',
+      '[Isolation] Network: hive-formal-ai',
+      '[Isolation] Network aliases: formal-ai, checker',
     ]);
   });
 
@@ -223,6 +291,8 @@ describe('buildDockerRuntimeMetadata', () => {
       mounts: null,
       env: null,
       privileged: null,
+      network: null,
+      networkAliases: null,
     });
   });
 
@@ -233,12 +303,16 @@ describe('buildDockerRuntimeMetadata', () => {
         mounts: ['type=bind,src=/h,dst=/c'],
         env: ['FOO=bar'],
         privileged: true,
+        network: 'hive-formal-ai',
+        networkAliases: ['formal-ai', 'checker'],
       }),
       {
         volumes: ['/h:/c'],
         mounts: ['type=bind,src=/h,dst=/c'],
         env: ['FOO=bar'],
         privileged: true,
+        network: 'hive-formal-ai',
+        networkAliases: ['formal-ai', 'checker'],
       }
     );
   });

package/test/regression-150.js

@@ -0,0 +1,178 @@
+#!/usr/bin/env bun
+/**
+ * Regression tests for issue #150:
+ * "`$ --status` fabricates a detached session exit code from the command's own
+ *  output (unanchored `Exit Code:` scan over the whole log)"
+ *
+ * The exit code of a detached session used to be derived from an *unanchored*
+ * `Exit Code: N` scan over the *whole* session log. Any text the wrapped
+ * command printed that merely contained the substring `Exit Code: N` was
+ * indistinguishable from the terminal footer `start` appends itself, so
+ * `$ --status` could report an exit code the command never produced.
+ *
+ * The fix anchors the scan on the three-line footer block `start` writes
+ * (separator / `Finished:` / `Exit Code:`) and only reads the tail of the log,
+ * where the footer always is.
+ *
+ * Reference: https://github.com/link-foundation/start/issues/150
+ */
+
+const { describe, it, expect, beforeEach, afterEach } = require('bun:test');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { ExecutionRecord } = require('../src/lib/execution-store');
+const {
+  readExitCodeFromLog,
+  readLogTail,
+  enrichDetachedStatus,
+} = require('../src/lib/status-formatter');
+
+const SEPARATOR = '='.repeat(50);
+
+function realFooter(exitCode) {
+  return `\n${SEPARATOR}\nFinished: 2026-07-30 23:36:20.295\nExit Code: ${exitCode}\n`;
+}
+
+describe('anchored log footer parsing (issue #150)', () => {
+  let tempDir;
+  let logPath;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'start-150-'));
+    logPath = path.join(tempDir, 'session.log');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('ignores an `Exit Code:` substring inside the command output', () => {
+    // Exactly the payload from the incident: an older session log dumped by
+    // `rg -n` into the JSON output of the running command.
+    fs.writeFileSync(
+      logPath,
+      '{"type":"item.completed","item":{"aggregated_output":' +
+        '"40-==================================================\\n41-Finished: 2026-07-28 20:04:52.316\\n42-Exit Code: 1\\n",' +
+        '"exit_code":0,"status":"completed"}}\n'
+    );
+    expect(readExitCodeFromLog(logPath)).toBeNull();
+  });
+
+  it('ignores a bare `Exit Code:` line without the footer block around it', () => {
+    fs.writeFileSync(logPath, 'Exit Code: 1\nstill running\n');
+    expect(readExitCodeFromLog(logPath)).toBeNull();
+  });
+
+  it('ignores an `Exit Code:` substring in the middle of a line', () => {
+    fs.writeFileSync(
+      logPath,
+      `${SEPARATOR}\nFinished: now\nlog: Exit Code: 3\n`
+    );
+    expect(readExitCodeFromLog(logPath)).toBeNull();
+  });
+
+  it('reads the real footer that `start` appends', () => {
+    fs.writeFileSync(logPath, `hello\n${realFooter(0)}`);
+    expect(readExitCodeFromLog(logPath)).toBe(0);
+  });
+
+  it('reads the real footer even when the output forged one earlier', () => {
+    fs.writeFileSync(
+      logPath,
+      `${SEPARATOR}\nFinished: fake\nExit Code: 1\n${realFooter(0)}`
+    );
+    // The last anchored footer wins - here the genuine one, appended last.
+    expect(readExitCodeFromLog(logPath)).toBe(0);
+  });
+
+  it('reads negative and multi-digit codes, and tolerates CRLF logs', () => {
+    fs.writeFileSync(
+      logPath,
+      `${SEPARATOR}\r\nFinished: t\r\nExit Code: 137\r\n`
+    );
+    expect(readExitCodeFromLog(logPath)).toBe(137);
+    fs.writeFileSync(logPath, realFooter(-1));
+    expect(readExitCodeFromLog(logPath)).toBe(-1);
+  });
+
+  it('returns null for a log without a footer and for a missing file', () => {
+    fs.writeFileSync(logPath, 'still running, no footer yet\n');
+    expect(readExitCodeFromLog(logPath)).toBeNull();
+    expect(readExitCodeFromLog(path.join(tempDir, 'missing.log'))).toBeNull();
+    expect(readExitCodeFromLog(null)).toBeNull();
+  });
+
+  it('finds the footer at the end of a large log without reading it all', () => {
+    fs.writeFileSync(
+      logPath,
+      `${'x'.repeat(2 * 1024 * 1024)}\n${realFooter(42)}`
+    );
+    expect(readExitCodeFromLog(logPath)).toBe(42);
+    // Only the tail is read, so an `Exit Code:` far from the end is invisible.
+    const tail = readLogTail(logPath);
+    expect(tail.length).toBeLessThan(32 * 1024);
+  });
+
+  it('drops the partial first line of the tail so it cannot be a line start', () => {
+    const filler = 'y'.repeat(32 * 1024);
+    fs.writeFileSync(
+      logPath,
+      `${filler}${SEPARATOR}\nFinished: t\nExit Code: 7\n`
+    );
+    // The separator is a line *continuation* (the line starts with the filler),
+    // so it is not a footer even though the tail slice may begin mid-line.
+    expect(readExitCodeFromLog(logPath)).toBeNull();
+  });
+});
+
+describe('detached status is not derailed by forged output (issue #150)', () => {
+  let tempDir;
+  let logPath;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'start-150-enrich-'));
+    logPath = path.join(tempDir, 'session.log');
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function makeRecord() {
+    return new ExecutionRecord({
+      command: 'solve.mjs',
+      logPath,
+      options: {
+        // A container name that cannot be inspected: liveness is unknown, the
+        // exact window in which the incident happened.
+        sessionName: `issue150-absent-${process.pid}-${Date.now()}`,
+        isolated: 'docker',
+        isolationMode: 'detached',
+      },
+    });
+  }
+
+  it('keeps an executing record executing when only the output claims an exit code', () => {
+    fs.writeFileSync(
+      logPath,
+      '{"aggregated_output":"41-Finished: x\\n42-Exit Code: 1\\n","exit_code":0}\n'
+    );
+    const enriched = enrichDetachedStatus(makeRecord());
+    expect(enriched.status).toBe('executing');
+    expect(enriched.exitCode).toBeNull();
+    expect(enriched.endTime).toBeNull();
+  });
+
+  it('marks the record executed once the genuine footer is appended', () => {
+    fs.writeFileSync(
+      logPath,
+      `{"aggregated_output":"42-Exit Code: 1\\n"}\n${realFooter(0)}`
+    );
+    const enriched = enrichDetachedStatus(makeRecord());
+    expect(enriched.status).toBe('executed');
+    expect(enriched.exitCode).toBe(0);
+    expect(enriched.endTime).not.toBeNull();
+  });
+});

package/test/session-name-status.js

@@ -846,7 +846,12 @@ describe('Issue #151: OOMKilled is an observation, not a verdict', () => {
   });
 
   it('prefers the log footer exit code over the OOM fallback when the container is gone', () => {
-    fs.writeFileSync(logPath, 'Finished: now\nExit Code: 0\n', 'utf8');
+    // The anchored footer block `start` itself writes (issue #150).
+    fs.writeFileSync(
+      logPath,
+      `${'='.repeat(50)}\nFinished: now\nExit Code: 0\n`,
+      'utf8'
+    );
     const record = saveDockerRecord({ oomKilled: true });
 
     withFakeDockerMissingContainer(() => {