start-command 0.30.5 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # start-command
 
+## 0.32.0
+
+### Minor Changes
+
+- Allow Docker isolation to join multiple networks before starting the command.
+
+  Make the Docker multi-network integration test hermetic and add opt-in
+  `START_DEBUG` tracing to the Docker network lifecycle helpers.
+
+## 0.31.0
+
+### Minor Changes
+
+- b14f11c: Add `--network` and repeatable `--network-alias` options for Docker-isolated commands.
+
 ## 0.30.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.30.5",
+  "version": "0.32.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

@@ -4,7 +4,6 @@
  * Supports two syntax patterns:
  * 1. $ [wrapper-options] -- [command-options]
  * 2. $ [wrapper-options] command [command-options]
- *
  * Wrapper Options:
  * --isolated, --isolation, -i <backend> Run in isolated environment (screen, tmux, docker, ssh)
  * --attached, -a                   Run in attached mode (foreground)
@@ -15,6 +14,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 (repeatable, docker only)
+ * --network-alias <alias>          Add an alias to the first network (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 +38,7 @@
  */
 
 const { getDefaultDockerImage } = require('./docker-utils');
+const dockerNetworkOptions = require('./docker-network-options');
 const { parseSequence, isSequence } = require('./sequence-parser');
 
 // Debug mode from environment
@@ -178,6 +180,9 @@ 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, // First Docker network name (compatibility accessor)
+    networks: [], // Ordered Docker network names
+    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-lifecycle.js

@@ -0,0 +1,68 @@
+/** Docker multi-network lifecycle helpers. */
+
+const { spawnSync } = require('child_process');
+
+// Opt-in tracing, off by default: the multi-network attachment sequence
+// (`docker create` -> `docker network connect` -> `docker start`) previously
+// failed in CI with nothing but an exit code to go on (issue #158). Enable with
+// START_DEBUG=1 to see every docker invocation, its status and its output.
+const DEBUG =
+  process.env.START_DEBUG === '1' || process.env.START_DEBUG === 'true';
+
+function debugLog(message) {
+  if (DEBUG) {
+    console.error(`[docker-network] ${message}`);
+  }
+}
+
+function getDockerNetworks(options = {}) {
+  return options.networks?.length
+    ? options.networks
+    : options.network
+      ? [options.network]
+      : [];
+}
+
+function runDockerCommand(args) {
+  debugLog(`$ docker ${args.join(' ')}`);
+  const result = spawnSync('docker', args, {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  if (result.error) {
+    debugLog(`spawn failed: ${result.error.message}`);
+    throw result.error;
+  }
+  debugLog(
+    `exit=${result.status} stdout=${JSON.stringify(
+      (result.stdout || '').trim()
+    )} stderr=${JSON.stringify((result.stderr || '').trim())}`
+  );
+  if (result.status !== 0) {
+    throw new Error(
+      result.stderr.trim() ||
+        result.stdout.trim() ||
+        `docker ${args[0]} exited with code ${result.status}`
+    );
+  }
+  return result.stdout.trim();
+}
+
+function connectAdditionalDockerNetworks(containerName, options = {}) {
+  const networks = getDockerNetworks(options);
+  debugLog(
+    `connecting ${containerName} to additional networks: ${
+      networks.slice(1).join(', ') || '<none>'
+    }`
+  );
+  for (const network of networks.slice(1)) {
+    runDockerCommand(['network', 'connect', network, containerName]);
+  }
+}
+
+module.exports = {
+  connectAdditionalDockerNetworks,
+  debugLog,
+  getDockerNetworks,
+  runDockerCommand,
+};

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

@@ -0,0 +1,47 @@
+/** 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.networks.push(args[index + 1]);
+      options.network ??= args[index + 1];
+    } else {
+      options.networkAliases.push(args[index + 1]);
+    }
+    return 2;
+  }
+  if (arg.startsWith('--network=')) {
+    const network = arg.slice('--network='.length);
+    options.networks.push(network);
+    options.network ??= network;
+    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

@@ -4,6 +4,11 @@ const { execSync, spawn, spawnSync } = require('child_process');
 const path = require('path');
 const { generateSessionName } = require('./args-parser');
 const outputBlocks = require('./output-blocks');
+const {
+  connectAdditionalDockerNetworks,
+  getDockerNetworks,
+  runDockerCommand,
+} = require('./docker-network-lifecycle');
 
 // Debug mode from environment
 const DEBUG =
@@ -28,6 +33,7 @@ const {
   getDockerContainerCleanupInstructions,
   appendDockerContainerCleanupPolicyMessage,
   readDockerContainerOomKilled,
+  readDockerContainerStatus,
   removeDockerContainer,
   startDetachedDockerCompletionWatcher,
   spawnAttachedDocker,
@@ -499,9 +505,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 +524,13 @@ function buildDockerRuntimeArgs(options = {}) {
   for (const mount of options.mounts || []) {
     args.push('--mount', mount);
   }
+  const [firstNetwork] = getDockerNetworks(options);
+  if (firstNetwork) {
+    args.push('--network', firstNetwork);
+  }
+  for (const alias of options.networkAliases || []) {
+    args.push('--network-alias', alias);
+  }
   return args;
 }
 
@@ -525,7 +538,7 @@ function buildDockerRuntimeArgs(options = {}) {
  * Build the human-readable `[Isolation]` status lines for docker runtime
  * options (volumes, mounts, env, privileged). Empty collections and a falsy
  * privileged flag contribute no lines.
- * @param {object} options - Options (volumes, mounts, env, privileged)
+ * @param {object} options - Options (volumes, mounts, env, privileged, network, networks, networkAliases)
  * @returns {string[]} Status lines for the start block / log header
  */
 function buildDockerRuntimeStatusLines(options = {}) {
@@ -542,22 +555,41 @@ function buildDockerRuntimeStatusLines(options = {}) {
   if (options.privileged) {
     lines.push(`[Isolation] Privileged: true`);
   }
+  const networks = getDockerNetworks(options);
+  if (networks.length > 0) {
+    lines.push(`[Isolation] Network: ${networks[0]}`);
+  }
+  if (networks.length > 1) {
+    lines.push(`[Isolation] Networks: ${networks.join(', ')}`);
+  }
+  if (options.networkAliases && options.networkAliases.length > 0) {
+    lines.push(
+      `[Isolation] Network aliases: ${options.networkAliases.join(', ')}`
+    );
+  }
   return lines;
 }
 
 /**
  * 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}}
+ * @param {object} options - Options (volumes, mounts, env, privileged, network, networks, networkAliases)
+ * @returns {{volumes: ?string[], mounts: ?string[], env: ?string[], privileged: ?boolean, network: ?string, networks: ?string[], networkAliases: ?string[]}}
  */
 function buildDockerRuntimeMetadata(options = {}) {
+  const networks = getDockerNetworks(options);
   return {
     volumes:
       options.volumes && options.volumes.length > 0 ? options.volumes : null,
     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: networks[0] || null,
+    networks: networks.length > 0 ? networks : null,
+    networkAliases:
+      options.networkAliases && options.networkAliases.length > 0
+        ? options.networkAliases
+        : null,
   };
 }
 
@@ -597,6 +629,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
@@ -622,8 +656,9 @@ function runInDocker(command, options = {}) {
   console.log();
 
   try {
+    const needsNetworkSetup = getDockerNetworks(options).length > 1;
     if (options.detached) {
-      const dockerArgs = ['run', '-d'];
+      const dockerArgs = needsNetworkSetup ? ['create'] : ['run', '-d'];
       if (options.keepAlive) {
         dockerArgs.push('-i', '-t');
       }
@@ -671,11 +706,29 @@ 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);
       }
 
       const containerId = dockerResult.stdout.trim();
 
+      if (needsNetworkSetup) {
+        try {
+          connectAdditionalDockerNetworks(containerName, options);
+          runDockerCommand(['start', containerName]);
+        } catch (error) {
+          if (!containerExistedBeforeLaunch) {
+            removeDockerContainer(containerName, options.logPath);
+          }
+          throw error;
+        }
+      }
+
       startDetachedDockerCompletionWatcher(
         containerName,
         cleanupPolicy,
@@ -707,7 +760,7 @@ function runInDocker(command, options = {}) {
         message,
       });
     } else {
-      const dockerArgs = ['run'];
+      const dockerArgs = [needsNetworkSetup ? 'create' : 'run'];
       dockerArgs.push(hasTTY() ? '-it' : '-i');
       dockerArgs.push('--name', containerName);
       if (options.user) {
@@ -741,9 +794,24 @@ function runInDocker(command, options = {}) {
         console.log(`[DEBUG] Running: docker ${dockerArgs.join(' ')}`);
       }
 
+      if (needsNetworkSetup) {
+        try {
+          runDockerCommand(dockerArgs);
+          connectAdditionalDockerNetworks(containerName, options);
+        } catch (error) {
+          if (!containerExistedBeforeLaunch) {
+            removeDockerContainer(containerName, options.logPath);
+          }
+          throw error;
+        }
+      }
+
       return new Promise((resolve) => {
         const startTime = Date.now();
-        const child = spawnAttachedDocker(dockerArgs, options.logPath);
+        const launchArgs = needsNetworkSetup
+          ? ['start', '-a', '-i', containerName]
+          : dockerArgs;
+        const child = spawnAttachedDocker(launchArgs, options.logPath);
 
         child.on('exit', (code) => {
           const durationMs = Date.now() - startTime;
@@ -760,8 +828,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/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 to a named network (repeatable, docker only)
+  --network-alias <alias> Add alias to the first network (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/check-js-coverage.mjs

@@ -0,0 +1,61 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  checkCoverage,
+  parseLineCoverage,
+} from '../../scripts/check-js-coverage.mjs';
+
+// Verbatim Bun 1.3 text reporter output: the totals row carries no `%` suffix,
+// which is why the previous CI grep never matched (issue #158).
+const BUN_REPORT = `bun test v1.3.14 (0d9b296a)
+-----------------|---------|---------|-------------------
+File             | % Funcs | % Lines | Uncovered Line #s
+-----------------|---------|---------|-------------------
+All files        |  100.00 |   83.33 |
+ test/version.js |  100.00 |   83.33 | 38-43,103,105-108
+-----------------|---------|---------|-------------------
+
+ 14 pass
+ 0 fail
+`;
+
+describe('check-js-coverage', () => {
+  it('parses line coverage from a real Bun text report', () => {
+    expect(parseLineCoverage(BUN_REPORT)).toBe(83.33);
+  });
+
+  it('reads the line column, not the function column', () => {
+    const report = 'All files | 92.60 | 88.09 |';
+    expect(parseLineCoverage(report)).toBe(88.09);
+  });
+
+  it('ignores the uncovered-lines column when picking numbers', () => {
+    const report = 'All files |  10.00 |  20.00 | 30-40,50';
+    expect(parseLineCoverage(report)).toBe(20);
+  });
+
+  it('returns null when no totals row is present', () => {
+    expect(parseLineCoverage('bun test v1.3.14\n 0 pass\n')).toBeNull();
+    expect(parseLineCoverage('')).toBeNull();
+    expect(parseLineCoverage(undefined)).toBeNull();
+  });
+
+  it('fails instead of skipping when coverage cannot be determined', () => {
+    const result = checkCoverage('no table here', 45);
+    expect(result.ok).toBe(false);
+    expect(result.coverage).toBeNull();
+    expect(result.message).toContain('Could not determine coverage');
+  });
+
+  it('passes when coverage meets the threshold', () => {
+    const result = checkCoverage(BUN_REPORT, 45);
+    expect(result.ok).toBe(true);
+    expect(result.coverage).toBe(83.33);
+  });
+
+  it('fails when coverage is below the threshold', () => {
+    const result = checkCoverage(BUN_REPORT, 90);
+    expect(result.ok).toBe(false);
+    expect(result.message).toContain('below the 90% threshold');
+  });
+});

package/test/ci-workflow-invariants.js

@@ -0,0 +1,274 @@
+#!/usr/bin/env bun
+/**
+ * Structural invariants for every GitHub Actions workflow (issue #158).
+ *
+ * These guard the CI/CD properties that silently regressed before: a job with
+ * no timeout, a workflow-level `concurrency` block that cancels a started
+ * release, a bare `always()` that keeps work running after cancellation, a
+ * missing aggregate status job that lets a red run look green, and coverage
+ * gates that swallow their own failures.
+ *
+ * The Rust suite mirrors these checks in `rust/tests/ci_workflow_invariants.rs`.
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const { readdirSync, readFileSync } = require('fs');
+const { join, resolve } = require('path');
+
+const workflowDir = resolve(__dirname, '..', '..', '.github', 'workflows');
+const repoRoot = resolve(__dirname, '..', '..');
+
+// Jobs that push commits, tags, releases or packages. They must share one
+// repository-wide concurrency group so two writers never run at once.
+const WRITER_JOBS = new Set([
+  'release',
+  'instant-release',
+  'changeset-pr',
+  'auto-release',
+  'manual-release',
+]);
+const MAIN_WRITER_GROUP = 'main-writer-${{ github.repository }}-main';
+
+function listWorkflows() {
+  return readdirSync(workflowDir)
+    .filter((name) => /\.ya?ml$/.test(name))
+    .sort();
+}
+
+function readWorkflow(name) {
+  return readFileSync(join(workflowDir, name), 'utf8').replaceAll('\r\n', '\n');
+}
+
+/** Split a workflow into `{ name, body }` job blocks using indentation. */
+function parseJobs(workflow) {
+  const lines = workflow.split('\n');
+  const jobsIndex = lines.findIndex((line) => line === 'jobs:');
+  assert.notStrictEqual(jobsIndex, -1, 'workflow has no jobs: block');
+
+  const jobs = [];
+  for (let index = jobsIndex + 1; index < lines.length; index++) {
+    const header = lines[index].match(/^ {2}([a-zA-Z0-9_-]+):\s*$/);
+    if (!header) {
+      continue;
+    }
+    const body = [];
+    for (let cursor = index + 1; cursor < lines.length; cursor++) {
+      const line = lines[cursor];
+      if (/^ {2}[a-zA-Z0-9_-]+:\s*$/.test(line) || /^[a-zA-Z]/.test(line)) {
+        break;
+      }
+      body.push(line);
+    }
+    jobs.push({ name: header[1], body: body.join('\n') });
+  }
+  return jobs;
+}
+
+/** Value of a key inside a job body, at any indentation depth. */
+function jobKey(body, key, indent = 4) {
+  const match = body.match(new RegExp(`^ {${indent}}${key}:[ \\t]*(.*)$`, 'm'));
+  return match ? match[1].trim() : null;
+}
+
+/** Value of a key inside the job's `concurrency:` block. */
+function concurrencyKey(body, key) {
+  return jobKey(body, key, 6);
+}
+
+const workflows = listWorkflows();
+
+describe('CI workflow invariants', () => {
+  it('finds every workflow file', () => {
+    assert.ok(workflows.length >= 4, `only found ${workflows.join(', ')}`);
+    for (const expected of [
+      'js.yml',
+      'rust.yml',
+      'security.yml',
+      'links.yml',
+    ]) {
+      assert.ok(workflows.includes(expected), `missing ${expected}`);
+    }
+  });
+
+  it('declares a least-privilege default permission set', () => {
+    for (const name of workflows) {
+      const workflow = readWorkflow(name);
+      assert.match(
+        workflow,
+        /^permissions:\n {2}contents: read$/m,
+        `${name} must default to read-only contents permission`
+      );
+    }
+  });
+
+  it('gives every job a timeout', () => {
+    for (const name of workflows) {
+      for (const job of parseJobs(readWorkflow(name))) {
+        assert.ok(
+          jobKey(job.body, 'timeout-minutes'),
+          `${name}: job "${job.name}" has no timeout-minutes`
+        );
+      }
+    }
+  });
+
+  it('never puts concurrency at workflow level', () => {
+    for (const name of workflows) {
+      assert.doesNotMatch(
+        readWorkflow(name),
+        /^concurrency:$/m,
+        `${name}: workflow-level concurrency would also cancel started writers`
+      );
+    }
+  });
+
+  it('gives every job its own concurrency group', () => {
+    for (const name of workflows) {
+      for (const job of parseJobs(readWorkflow(name))) {
+        if (job.name === 'pipeline-status') {
+          continue;
+        }
+        const group = concurrencyKey(job.body, 'group');
+        assert.ok(group, `${name}: job "${job.name}" has no concurrency group`);
+      }
+    }
+  });
+
+  it('makes writers non-cancellable and read-only checks cancellable', () => {
+    for (const name of workflows) {
+      for (const job of parseJobs(readWorkflow(name))) {
+        const group = concurrencyKey(job.body, 'group');
+        if (!group) {
+          continue;
+        }
+        const cancel = concurrencyKey(job.body, 'cancel-in-progress');
+        if (WRITER_JOBS.has(job.name)) {
+          assert.strictEqual(
+            group,
+            MAIN_WRITER_GROUP,
+            `${name}: writer "${job.name}" must use the shared main-writer group`
+          );
+          assert.strictEqual(
+            cancel,
+            'false',
+            `${name}: writer "${job.name}" must not be cancellable`
+          );
+        } else {
+          assert.ok(
+            group.startsWith('check-'),
+            `${name}: check "${job.name}" must use a check-* group, got ${group}`
+          );
+          assert.strictEqual(
+            cancel,
+            'true',
+            `${name}: superseded check "${job.name}" should be cancelled`
+          );
+        }
+      }
+    }
+  });
+
+  it('uses !cancelled() rather than always() outside the status job', () => {
+    for (const name of workflows) {
+      for (const job of parseJobs(readWorkflow(name))) {
+        if (job.name === 'pipeline-status') {
+          continue;
+        }
+        assert.doesNotMatch(
+          job.body,
+          /always\(\)/,
+          `${name}: job "${job.name}" uses always(); use !cancelled() so cancellation propagates`
+        );
+      }
+    }
+  });
+
+  it('aggregates every job into a pipeline-status gate', () => {
+    for (const name of workflows) {
+      const jobs = parseJobs(readWorkflow(name));
+      const status = jobs.find((job) => job.name === 'pipeline-status');
+      assert.ok(status, `${name}: no pipeline-status job`);
+      assert.match(
+        status.body,
+        /if: always\(\)/,
+        `${name}: pipeline-status must run even when jobs are cancelled`
+      );
+      for (const job of jobs) {
+        if (job.name === 'pipeline-status') {
+          continue;
+        }
+        assert.match(
+          status.body,
+          new RegExp(`(^|[\\s\\[,])${job.name}([\\s\\],]|$)`, 'm'),
+          `${name}: pipeline-status does not depend on "${job.name}"`
+        );
+      }
+    }
+  });
+
+  it('configures git before checkout so no init hints are printed', () => {
+    for (const name of workflows) {
+      const workflow = readWorkflow(name);
+      assert.match(workflow, /GIT_CONFIG_COUNT: '1'/, `${name}`);
+      assert.match(
+        workflow,
+        /GIT_CONFIG_KEY_0: init\.defaultBranch/,
+        `${name}`
+      );
+      assert.match(workflow, /GIT_CONFIG_VALUE_0: main/, `${name}`);
+    }
+  });
+
+  it('never swallows a failing command in a quality gate', () => {
+    for (const name of workflows) {
+      const workflow = readWorkflow(name);
+      for (const [index, line] of workflow.split('\n').entries()) {
+        // `|| true` on a `grep` that is allowed to find nothing is fine; the
+        // regression was `... | tee coverage.txt || true`, which hid failing
+        // tests from the coverage job.
+        const hidesAGate = /\btee\b|\bbun run\b|\bcargo\b|\bnpm run\b/.test(
+          line
+        );
+        if (
+          line.includes('|| true') &&
+          hidesAGate &&
+          !line.trimStart().startsWith('#')
+        ) {
+          assert.fail(
+            `${name}:${index + 1} uses "|| true", which hides failures: ${line.trim()}`
+          );
+        }
+      }
+    }
+  });
+
+  it('references only helper scripts that exist', () => {
+    const pattern = /(?:bash|node|bun)\s+(scripts\/[A-Za-z0-9._/-]+)/g;
+    for (const name of workflows) {
+      const workflow = readWorkflow(name);
+      for (const match of workflow.matchAll(pattern)) {
+        const scriptPath = join(repoRoot, match[1]);
+        assert.doesNotThrow(
+          () => readFileSync(scriptPath),
+          `${name} references missing ${match[1]}`
+        );
+      }
+    }
+  });
+
+  it('parses coverage through the tested helper, not an inline grep', () => {
+    const js = readWorkflow('js.yml');
+    assert.doesNotMatch(
+      js,
+      /grep -oP '\\d\+\\\.\\d\+\(\?=%\)'/,
+      'the inline coverage grep never matched Bun output (issue #158)'
+    );
+    assert.match(js, /scripts\/check-js-coverage\.mjs/);
+    assert.doesNotMatch(
+      js,
+      /Could not determine coverage, skipping check/,
+      'an unparsable coverage report must fail, not skip'
+    );
+  });
+});

package/test/docker-network-integration.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env bun
+/** Real-daemon integration coverage for Docker network isolation (issues #154, #156, #158). */
+
+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');
+
+// Bun's `node:test` shim ignores a `describe`-level timeout, so every `it`
+// declares its own budget explicitly (issue #158).
+const TEST_TIMEOUT = 120000;
+
+const suffix = randomUUID().slice(0, 8);
+const network = `start-network-${suffix}`;
+const secondNetwork = `start-network-b-${suffix}`;
+const sidecar = `start-sidecar-${suffix}`;
+const secondSidecar = `start-sidecar-b-${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' });
+}
+
+/**
+ * Container output, folded into assertion messages so a CI failure carries the
+ * evidence needed to diagnose it instead of only reporting the exit code.
+ */
+function containerDiagnostics(name) {
+  const logs = docker(['logs', name]);
+  const output = `${logs.stdout || ''}${logs.stderr || ''}`.trim();
+  return `\n--- docker logs ${name} ---\n${output || '<no output>'}\n---`;
+}
+
+function createInternalNetworkWithSidecar(networkName, containerName, alias) {
+  const created = docker(['network', 'create', '--internal', networkName]);
+  assert.strictEqual(created.status, 0, created.stderr);
+  const started = docker([
+    'run',
+    '-d',
+    '--name',
+    containerName,
+    '--network',
+    networkName,
+    '--network-alias',
+    alias,
+    'alpine:3.23',
+    'sleep',
+    '300',
+  ]);
+  assert.strictEqual(started.status, 0, started.stderr);
+}
+
+describe('Docker named network integration', () => {
+  before(() => {
+    dockerAvailable =
+      process.platform === 'linux' && docker(['info']).status === 0;
+    if (!dockerAvailable) {
+      return;
+    }
+
+    createInternalNetworkWithSidecar(network, sidecar, 'formal-ai');
+    createInternalNetworkWithSidecar(secondNetwork, secondSidecar, 'formal-db');
+  });
+
+  after(() => {
+    if (!dockerAvailable) {
+      return;
+    }
+    docker([
+      'rm',
+      '-f',
+      sidecar,
+      secondSidecar,
+      connected,
+      control,
+      missing,
+      missingAttached,
+    ]);
+    docker(['network', 'rm', network, secondNetwork]);
+  });
+
+  it(
+    'reaches a private sidecar on each of two networks',
+    { timeout: TEST_TIMEOUT },
+    async () => {
+      if (!dockerAvailable) {
+        return;
+      }
+
+      // Both endpoints are local, user-defined networks on purpose: probing a
+      // public endpoint (previously `https://api.github.com`) made this test
+      // fail whenever the shared runner IP hit the 60 requests/hour
+      // unauthenticated GitHub API rate limit (issue #158).
+      const joined = await runInDocker(
+        'ping -c 1 formal-ai && ping -c 1 formal-db',
+        {
+          image: 'alpine:3.23',
+          session: connected,
+          network,
+          networks: [network, secondNetwork],
+          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',
+        `container did not exit cleanly${containerDiagnostics(connected)}`
+      );
+
+      const unconnected = await runInDocker('ping -c 1 formal-ai', {
+        image: 'alpine:3.23',
+        session: control,
+        shell: 'sh',
+        alwaysCleanupContainer: true,
+      });
+      assert.strictEqual(unconnected.success, false, unconnected.message);
+    }
+  );
+
+  it(
+    'fails for a missing network without orphaning a container',
+    { timeout: TEST_TIMEOUT },
+    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 missingSecond = await runInDocker('echo should-not-run', {
+        image: 'alpine:3.23',
+        session: missing,
+        network,
+        networks: [network, `${network}-absent`],
+        detached: true,
+        shell: 'sh',
+      });
+      assert.strictEqual(missingSecond.success, false);
+      assert.match(missingSecond.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-network-lifecycle.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env bun
+/**
+ * Unit coverage for the Docker multi-network lifecycle helpers (issue #158).
+ *
+ * The verbose mode added here exists because the failing CI run gave nothing
+ * but an exit code for the `docker create` -> `network connect` -> `start`
+ * sequence. It must stay OFF unless START_DEBUG is explicitly set.
+ */
+
+const { describe, it } = require('node:test');
+const assert = require('assert');
+const {
+  debugLog,
+  getDockerNetworks,
+} = require('../src/lib/docker-network-lifecycle');
+
+/** Capture everything written to console.error while `run` executes. */
+function captureStderr(run) {
+  const original = console.error;
+  const lines = [];
+  console.error = (...args) => lines.push(args.join(' '));
+  try {
+    run();
+  } finally {
+    console.error = original;
+  }
+  return lines;
+}
+
+describe('docker network lifecycle helpers', () => {
+  it('returns an empty list when no network is requested', () => {
+    assert.deepStrictEqual(getDockerNetworks({}), []);
+    assert.deepStrictEqual(getDockerNetworks(), []);
+  });
+
+  it('wraps a single network into a list', () => {
+    assert.deepStrictEqual(getDockerNetworks({ network: 'bridge' }), [
+      'bridge',
+    ]);
+  });
+
+  it('prefers the explicit networks list over the single network', () => {
+    assert.deepStrictEqual(
+      getDockerNetworks({ network: 'bridge', networks: ['a', 'b'] }),
+      ['a', 'b']
+    );
+  });
+
+  it('ignores an empty networks list and falls back to network', () => {
+    assert.deepStrictEqual(
+      getDockerNetworks({ network: 'bridge', networks: [] }),
+      ['bridge']
+    );
+  });
+
+  it('keeps verbose output switched off by default', () => {
+    const previous = process.env.START_DEBUG;
+    delete process.env.START_DEBUG;
+    try {
+      // The module reads START_DEBUG once at load time, and the test process
+      // never sets it, so nothing may be printed.
+      assert.deepStrictEqual(
+        captureStderr(() => debugLog('should not appear')),
+        []
+      );
+    } finally {
+      if (previous !== undefined) {
+        process.env.START_DEBUG = previous;
+      }
+    }
+  });
+});

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,65 @@ describe('Docker runtime options parsing', () => {
     assert.strictEqual(result.wrapperOptions.privileged, true);
   });
 
+  it('should parse repeatable --network forms without consuming child args', () => {
+    const spaced = parseArgs([
+      '-i',
+      'docker',
+      '--network',
+      'hive-formal-ai',
+      '--network=public-egress',
+      '--',
+      '--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.wrapperOptions.networks, [
+      'hive-formal-ai',
+      'public-egress',
+    ]);
+    assert.deepStrictEqual(spaced.rawCommand, ['--network', 'child-network']);
+    assert.strictEqual(equals.wrapperOptions.network, 'hive-formal-ai');
+    assert.deepStrictEqual(equals.wrapperOptions.networks, ['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.networks, []);
+    assert.deepStrictEqual(result.wrapperOptions.networkAliases, []);
   });
 
   it('should throw when --volume requires an argument', () => {
@@ -136,6 +190,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 +234,9 @@ 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',
+      networks: ['hive-formal-ai', 'public-egress'],
+      networkAliases: ['formal-ai', 'checker'],
     });
     assert.deepStrictEqual(args, [
       '--privileged',
@@ -184,6 +250,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 +271,18 @@ describe('buildDockerRuntimeStatusLines', () => {
       mounts: ['type=bind,src=/h,dst=/c'],
       env: ['FOO=bar'],
       privileged: true,
+      network: 'hive-formal-ai',
+      networks: ['hive-formal-ai', 'public-egress'],
+      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] Networks: hive-formal-ai, public-egress',
+      '[Isolation] Network aliases: formal-ai, checker',
     ]);
   });
 
@@ -223,6 +301,9 @@ describe('buildDockerRuntimeMetadata', () => {
       mounts: null,
       env: null,
       privileged: null,
+      network: null,
+      networks: null,
+      networkAliases: null,
     });
   });
 
@@ -233,12 +314,18 @@ describe('buildDockerRuntimeMetadata', () => {
         mounts: ['type=bind,src=/h,dst=/c'],
         env: ['FOO=bar'],
         privileged: true,
+        network: 'hive-formal-ai',
+        networks: ['hive-formal-ai', 'public-egress'],
+        networkAliases: ['formal-ai', 'checker'],
       }),
       {
         volumes: ['/h:/c'],
         mounts: ['type=bind,src=/h,dst=/c'],
         env: ['FOO=bar'],
         privileged: true,
+        network: 'hive-formal-ai',
+        networks: ['hive-formal-ai', 'public-egress'],
+        networkAliases: ['formal-ai', 'checker'],
       }
     );
   });