start-command 0.31.0 → 0.32.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-command",
-  "version": "0.31.0",
+  "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/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,8 +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 (docker only)
- * --network-alias <alias>          Add a network-scoped alias (repeatable, 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)
@@ -181,7 +180,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
+    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)

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

@@ -8,14 +8,17 @@ function parseDockerNetworkOption(args, index, options) {
       throw new Error(`Option ${arg} requires a ${value} argument`);
     }
     if (arg === '--network') {
-      options.network = args[index + 1];
+      options.networks.push(args[index + 1]);
+      options.network ??= args[index + 1];
     } else {
       options.networkAliases.push(args[index + 1]);
     }
     return 2;
   }
   if (arg.startsWith('--network=')) {
-    options.network = arg.slice('--network='.length);
+    const network = arg.slice('--network='.length);
+    options.networks.push(network);
+    options.network ??= network;
     return 1;
   }
   if (arg.startsWith('--network-alias=')) {

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 =
@@ -519,8 +524,9 @@ function buildDockerRuntimeArgs(options = {}) {
   for (const mount of options.mounts || []) {
     args.push('--mount', mount);
   }
-  if (options.network) {
-    args.push('--network', options.network);
+  const [firstNetwork] = getDockerNetworks(options);
+  if (firstNetwork) {
+    args.push('--network', firstNetwork);
   }
   for (const alias of options.networkAliases || []) {
     args.push('--network-alias', alias);
@@ -532,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 = {}) {
@@ -549,8 +555,12 @@ function buildDockerRuntimeStatusLines(options = {}) {
   if (options.privileged) {
     lines.push(`[Isolation] Privileged: true`);
   }
-  if (options.network) {
-    lines.push(`[Isolation] Network: ${options.network}`);
+  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(
@@ -563,17 +573,19 @@ 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, network: ?string, networkAliases: ?string[]}}
+ * @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: options.network || null,
+    network: networks[0] || null,
+    networks: networks.length > 0 ? networks : null,
     networkAliases:
       options.networkAliases && options.networkAliases.length > 0
         ? options.networkAliases
@@ -644,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');
       }
@@ -704,6 +717,18 @@ function runInDocker(command, options = {}) {
 
       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,
@@ -735,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) {
@@ -769,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;

package/src/lib/usage.js

@@ -14,8 +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)
+  --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

@@ -1,5 +1,5 @@
 #!/usr/bin/env bun
-/** Real-daemon integration coverage for Docker network isolation (issue #154). */
+/** Real-daemon integration coverage for Docker network isolation (issues #154, #156, #158). */
 
 const { after, before, describe, it } = require('node:test');
 const assert = require('assert');
@@ -7,9 +7,15 @@ 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}`;
@@ -20,7 +26,36 @@ function docker(args) {
   return spawnSync('docker', args, { encoding: 'utf8' });
 }
 
-describe('Docker named network integration', { timeout: 60000 }, () => {
+/**
+ * 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;
@@ -28,93 +63,119 @@ describe('Docker named network integration', { timeout: 60000 }, () => {
       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);
+    createInternalNetworkWithSidecar(network, sidecar, 'formal-ai');
+    createInternalNetworkWithSidecar(secondNetwork, secondSidecar, 'formal-db');
   });
 
   after(() => {
     if (!dockerAvailable) {
       return;
     }
-    docker(['rm', '-f', sidecar, connected, control, missing, missingAttached]);
-    docker(['network', 'rm', network]);
+    docker([
+      'rm',
+      '-f',
+      sidecar,
+      secondSidecar,
+      connected,
+      control,
+      missing,
+      missingAttached,
+    ]);
+    docker(['network', 'rm', network, secondNetwork]);
   });
 
-  it('resolves an alias only from containers joined to the internal network', async () => {
-    if (!dockerAvailable) {
-      return;
-    }
+  it(
+    'reaches a private sidecar on each of two networks',
+    { timeout: TEST_TIMEOUT },
+    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);
-  });
+      // 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)}`
+      );
 
-  it('fails for a missing network without orphaning a container', async () => {
-    if (!dockerAvailable) {
-      return;
+      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);
     }
+  );
 
-    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);
-  });
+  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

@@ -91,12 +91,13 @@ describe('Docker runtime options parsing', () => {
     assert.strictEqual(result.wrapperOptions.privileged, true);
   });
 
-  it('should parse --network value and equals forms without consuming child args', () => {
+  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',
@@ -111,8 +112,13 @@ describe('Docker runtime options parsing', () => {
     ]);
 
     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', () => {
@@ -142,6 +148,7 @@ describe('Docker runtime options parsing', () => {
     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, []);
   });
 
@@ -228,6 +235,7 @@ describe('buildDockerRuntimeArgs', () => {
       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, [
@@ -264,6 +272,7 @@ describe('buildDockerRuntimeStatusLines', () => {
       env: ['FOO=bar'],
       privileged: true,
       network: 'hive-formal-ai',
+      networks: ['hive-formal-ai', 'public-egress'],
       networkAliases: ['formal-ai', 'checker'],
     });
     assert.deepStrictEqual(lines, [
@@ -272,6 +281,7 @@ describe('buildDockerRuntimeStatusLines', () => {
       '[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',
     ]);
   });
@@ -292,6 +302,7 @@ describe('buildDockerRuntimeMetadata', () => {
       env: null,
       privileged: null,
       network: null,
+      networks: null,
       networkAliases: null,
     });
   });
@@ -304,6 +315,7 @@ describe('buildDockerRuntimeMetadata', () => {
         env: ['FOO=bar'],
         privileged: true,
         network: 'hive-formal-ai',
+        networks: ['hive-formal-ai', 'public-egress'],
         networkAliases: ['formal-ai', 'checker'],
       }),
       {
@@ -312,6 +324,7 @@ describe('buildDockerRuntimeMetadata', () => {
         env: ['FOO=bar'],
         privileged: true,
         network: 'hive-formal-ai',
+        networks: ['hive-formal-ai', 'public-egress'],
         networkAliases: ['formal-ai', 'checker'],
       }
     );