@shogo-ai/worker 1.9.7 → 1.9.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shogo-ai/worker",
-  "version": "1.9.7",
+  "version": "1.9.8",
   "description": "Shogo Cloud Agent Worker — run Shogo agents on your own machine (laptop, devbox, CI).",
   "license": "MIT",
   "author": "Shogo Technologies, Inc.",

package/src/lib/__tests__/worker-commands-greenfield.test.ts

@@ -0,0 +1,463 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Greenfield sweep for three never-loaded shogo-worker files:
+ *   lib/runtime-install.ts, commands/project-checkout.ts, commands/project-push.ts
+ * Shared mocks: node:fs / node:child_process / node:crypto / node:os /
+ * node:stream / node:stream/promises / ../config / ../paths / ../git-cloner /
+ * @shogo-ai/sdk/cloud-file-transport, plus a routable global fetch.
+ */
+import { describe, test, expect, beforeEach, afterEach, mock, afterAll } from 'bun:test'
+import { EventEmitter } from 'node:events'
+
+// ── routable global fetch ─────────────────────────────────────────────────────
+type FetchHandler = (url: string, init?: any) => any
+let fetchHandler: FetchHandler = () => { throw new Error('fetch not configured') }
+const origFetch = globalThis.fetch
+beforeEach(() => {
+  fetchHandler = () => { throw new Error('fetch not configured') }
+  ;(globalThis as any).fetch = (url: any, init?: any) => Promise.resolve(fetchHandler(String(url), init))
+})
+afterEach(() => { (globalThis as any).fetch = origFetch })
+
+// ── controllable node:fs ──────────────────────────────────────────────────────
+let existsPredicate: (p: string) => boolean = () => false
+let readFileImpl: (p: string) => any = () => ''
+const fsWrites: Array<{ path: string; data: string }> = []
+const fsRenames: Array<{ from: string; to: string }> = []
+const fsRemoves: string[] = []
+const fsMkdirs: string[] = []
+mock.module('node:fs', () => ({
+  existsSync: (p: string) => existsPredicate(String(p)),
+  readFileSync: (p: string) => readFileImpl(String(p)),
+  writeFileSync: (p: string, data: any) => { fsWrites.push({ path: String(p), data: String(data) }) },
+  mkdirSync: (p: string) => { fsMkdirs.push(String(p)) },
+  renameSync: (a: string, b: string) => { fsRenames.push({ from: String(a), to: String(b) }) },
+  rmSync: (p: string) => { fsRemoves.push(String(p)) },
+  chmodSync: () => {},
+  createWriteStream: () => ({ on: () => {}, end: () => {}, write: () => true }),
+}))
+
+// ── node:crypto (deterministic digest) ────────────────────────────────────────
+let computedDigest = 'a'.repeat(64)
+mock.module('node:crypto', () => ({
+  createHash: () => ({ update: () => ({ digest: () => computedDigest }) }),
+}))
+
+// ── node:os / node:stream / node:stream/promises ──────────────────────────────
+mock.module('node:os', () => ({ tmpdir: () => '/tmp' }))
+mock.module('node:stream', () => ({ Readable: { fromWeb: () => ({}) } }))
+let pipelineThrows = false
+mock.module('node:stream/promises', () => ({
+  pipeline: async () => { if (pipelineThrows) throw new Error('pipeline boom') },
+}))
+
+// ── fake child_process.spawn (tar) ────────────────────────────────────────────
+let tarExitCode = 0
+let tarEmitsError = false
+class FakeTar extends EventEmitter {
+  stderr = new EventEmitter()
+  constructor() {
+    super()
+    queueMicrotask(() => {
+      if (tarEmitsError) { this.emit('error', new Error('spawn failed')); return }
+      if (tarExitCode !== 0) this.stderr.emit('data', Buffer.from('tar failure'))
+      this.emit('exit', tarExitCode)
+    })
+  }
+}
+mock.module('node:child_process', () => ({
+  spawn: () => new FakeTar(),
+}))
+
+// ── ../config ─────────────────────────────────────────────────────────────────
+mock.module('../config.ts', () => ({
+  resolveConfig: (o: any = {}) => ({
+    apiKey: o.apiKey ?? 'key-123',
+    cloudUrl: o.cloudUrl ?? 'https://cloud.shogo.dev',
+    projectsDir: '/projects',
+  }),
+}))
+
+// ── ../paths (serves both runtime-install ./paths and commands ../lib/paths) ────
+mock.module('../paths.ts', () => ({
+  RUNTIME_BIN: '/runtime/agent-runtime',
+  RUNTIME_DIR: '/runtime',
+  RUNTIME_VERSION_FILE: '/runtime/version.json',
+  ensureRuntimeDir: () => {},
+  projectDirFor: (id: string) => `/projects/${id}`,
+}))
+
+// ── ../git-cloner ─────────────────────────────────────────────────────────────
+let isGitRepoVal = true
+let runGitImpl: (args: string[]) => any = async () => ({ stdout: '', stderr: '' })
+const gitCalls: { fetchReset: any[]; unshallow: any[] } = { fetchReset: [], unshallow: [] }
+let fetchResetImpl: (o: any) => any = async () => ({ commitSha: 'abcdef1234567890' })
+let unshallowImpl: (o: any) => any = async () => {}
+mock.module('../git-cloner.ts', () => ({
+  isGitRepo: () => isGitRepoVal,
+  runGit: (args: string[], opts: any) => runGitImpl(args),
+  gitFetchAndReset: (o: any) => { gitCalls.fetchReset.push(o); return fetchResetImpl(o) },
+  gitFetchUnshallow: (o: any) => { gitCalls.unshallow.push(o); return unshallowImpl(o) },
+}))
+
+// ── @shogo-ai/sdk/cloud-file-transport ────────────────────────────────────────
+let uploadAllImpl: (o: any) => any = async () => ({ uploaded: 3, deleted: 0, errors: [] })
+let lastTransportOpts: any = null
+mock.module('@shogo-ai/sdk/cloud-file-transport', () => ({
+  CloudFileTransport: class {
+    opts: any
+    constructor(o: any) { this.opts = o; lastTransportOpts = o }
+    uploadAll(args: any) { return uploadAllImpl({ ...args, ctor: this.opts }) }
+  },
+}))
+
+import {
+  detectTarget,
+  readInstalledVersion,
+  resolveLatestVersion,
+  installRuntime,
+  getRuntimePaths,
+} from '../runtime-install'
+import { runProjectCheckout } from '../../commands/project-checkout'
+import { runProjectPush } from '../../commands/project-push'
+
+const silentLogger = { log: () => {}, warn: () => {}, error: () => {} }
+
+beforeEach(() => {
+  existsPredicate = () => false
+  readFileImpl = () => ''
+  fsWrites.length = 0; fsRenames.length = 0; fsRemoves.length = 0; fsMkdirs.length = 0
+  computedDigest = 'a'.repeat(64)
+  pipelineThrows = false
+  tarExitCode = 0; tarEmitsError = false
+  isGitRepoVal = true
+  runGitImpl = async () => ({ stdout: '', stderr: '' })
+  fetchResetImpl = async () => ({ commitSha: 'abcdef1234567890' })
+  unshallowImpl = async () => {}
+  gitCalls.fetchReset.length = 0; gitCalls.unshallow.length = 0
+  uploadAllImpl = async () => ({ uploaded: 3, deleted: 0, errors: [] })
+  lastTransportOpts = null
+})
+
+// ════════════════════════════════════════════════════════════════════════════
+// runtime-install.ts
+// ════════════════════════════════════════════════════════════════════════════
+describe('runtime-install: detectTarget', () => {
+  const origPlatform = process.platform
+  const origArch = process.arch
+  function setEnv(platform: string, arch: string) {
+    Object.defineProperty(process, 'platform', { value: platform, configurable: true })
+    Object.defineProperty(process, 'arch', { value: arch, configurable: true })
+  }
+  afterEach(() => {
+    Object.defineProperty(process, 'platform', { value: origPlatform, configurable: true })
+    Object.defineProperty(process, 'arch', { value: origArch, configurable: true })
+  })
+
+  test('darwin/arm64', () => { setEnv('darwin', 'arm64'); expect(detectTarget()).toBe('darwin-arm64') })
+  test('linux/x64', () => { setEnv('linux', 'x64'); expect(detectTarget()).toBe('linux-x64') })
+  test('win32/x64', () => { setEnv('win32', 'x64'); expect(detectTarget()).toBe('windows-x64') })
+  test('unsupported platform throws', () => { setEnv('freebsd', 'x64'); expect(() => detectTarget()).toThrow(/Unsupported platform/) })
+  test('unsupported arch throws', () => { setEnv('linux', 'mips'); expect(() => detectTarget()).toThrow(/Unsupported arch/) })
+})
+
+describe('runtime-install: readInstalledVersion', () => {
+  test('returns null when version file absent', () => {
+    existsPredicate = () => false
+    expect(readInstalledVersion()).toBeNull()
+  })
+  test('parses installed version json', () => {
+    existsPredicate = () => true
+    readFileImpl = () => JSON.stringify({ version: '1.2.3', target: 'linux-x64' })
+    expect(readInstalledVersion()?.version).toBe('1.2.3')
+  })
+  test('returns null on malformed json', () => {
+    existsPredicate = () => true
+    readFileImpl = () => '{not-json'
+    expect(readInstalledVersion()).toBeNull()
+  })
+})
+
+describe('runtime-install: resolveLatestVersion', () => {
+  const ghBase = 'https://github.com/shogo-ai/shogo/releases/download'
+
+  test('non-github baseUrl throws', async () => {
+    await expect(resolveLatestVersion('stable', 'https://cdn.example.com/rt')).rejects.toThrow(/non-GitHub baseUrl/)
+  })
+  test('stable reads releases/latest tag_name', async () => {
+    fetchHandler = () => ({ ok: true, json: async () => ({ tag_name: 'v2.5.1' }) })
+    expect(await resolveLatestVersion('stable', ghBase)).toBe('2.5.1')
+  })
+  test('stable throws on API error', async () => {
+    fetchHandler = () => ({ ok: false, status: 503 })
+    await expect(resolveLatestVersion('stable', ghBase)).rejects.toThrow(/GitHub API 503/)
+  })
+  test('stable throws when tag_name missing', async () => {
+    fetchHandler = () => ({ ok: true, json: async () => ({}) })
+    await expect(resolveLatestVersion('stable', ghBase)).rejects.toThrow(/did not return tag_name/)
+  })
+  test('beta picks newest matching prerelease', async () => {
+    fetchHandler = () => ({ ok: true, json: async () => ([
+      { tag_name: 'v3.0.0', prerelease: false },
+      { tag_name: 'v3.1.0-beta.2', prerelease: true },
+    ]) })
+    expect(await resolveLatestVersion('beta', ghBase)).toBe('3.1.0-beta.2')
+  })
+  test('nightly matches -nightly tags', async () => {
+    fetchHandler = () => ({ ok: true, json: async () => ([
+      { tag_name: 'v4.0.0-nightly.7', prerelease: true },
+    ]) })
+    expect(await resolveLatestVersion('nightly', ghBase)).toBe('4.0.0-nightly.7')
+  })
+  test('prerelease list API error throws', async () => {
+    fetchHandler = () => ({ ok: false, status: 500 })
+    await expect(resolveLatestVersion('beta', ghBase)).rejects.toThrow(/GitHub API 500/)
+  })
+  test('no matching prerelease throws', async () => {
+    fetchHandler = () => ({ ok: true, json: async () => ([{ tag_name: 'v1.0.0', prerelease: false }]) })
+    await expect(resolveLatestVersion('beta', ghBase)).rejects.toThrow(/No beta runtime release/)
+  })
+  test('malformed tag throws via tagToVersion', async () => {
+    fetchHandler = () => ({ ok: true, json: async () => ({ tag_name: 'release-99' }) })
+    await expect(resolveLatestVersion('stable', ghBase)).rejects.toThrow(/Unexpected app tag/)
+  })
+})
+
+describe('runtime-install: installRuntime', () => {
+  const ghBase = 'https://github.com/shogo-ai/shogo/releases/download'
+
+  function wireDownload(sha = 'a'.repeat(64)) {
+    fetchHandler = (url: string) => {
+      if (url.endsWith('.sha256')) return { ok: true, text: async () => `${sha}  shogo-agent-runtime.tar.gz` }
+      return { ok: true, body: {} }
+    }
+  }
+
+  test('short-circuits when same version already installed', async () => {
+    existsPredicate = () => true
+    readFileImpl = () => JSON.stringify({ version: '1.0.0', target: 'linux-x64', source: 'src-url', sha256: 'dd' })
+    const res = await installRuntime({ version: '1.0.0', target: 'linux-x64', logger: silentLogger })
+    expect(res.version).toBe('1.0.0')
+    expect(res.source).toBe('src-url')
+    expect(gitCalls.fetchReset.length).toBe(0)
+  })
+
+  test('full install happy path verifies sha + writes version record', async () => {
+    // version file absent → no short circuit; staging bin present after extract
+    existsPredicate = (p) => p.endsWith('agent-runtime') || p.endsWith('.next') === false && p.includes('extract')
+    existsPredicate = (p) => p.includes('extract') && p.endsWith('agent-runtime')
+    computedDigest = 'b'.repeat(64)
+    wireDownload('b'.repeat(64))
+    const res = await installRuntime({ version: '2.0.0', target: 'linux-x64', logger: silentLogger })
+    expect(res.version).toBe('2.0.0')
+    expect(res.sha256).toBe('b'.repeat(64))
+    expect(fsWrites.some((w) => w.path.endsWith('version.json'))).toBe(true)
+  })
+
+  test('sha mismatch throws', async () => {
+    existsPredicate = (p) => p.includes('extract') && p.endsWith('agent-runtime')
+    computedDigest = 'c'.repeat(64)
+    wireDownload('d'.repeat(64))
+    await expect(installRuntime({ version: '2.0.0', target: 'linux-x64', logger: silentLogger }))
+      .rejects.toThrow(/SHA-256 mismatch/)
+  })
+
+  test('missing agent-runtime in tarball throws', async () => {
+    existsPredicate = () => false
+    computedDigest = 'e'.repeat(64)
+    wireDownload('e'.repeat(64))
+    await expect(installRuntime({ version: '2.0.0', target: 'linux-x64', logger: silentLogger }))
+      .rejects.toThrow(/did not contain .\/agent-runtime/)
+  })
+
+  test('download HTTP error throws', async () => {
+    fetchHandler = () => ({ ok: false, status: 404 })
+    await expect(installRuntime({ version: '2.0.0', target: 'linux-x64', logger: silentLogger }))
+      .rejects.toThrow(/Download failed: HTTP 404/)
+  })
+
+  test('tar exit non-zero throws', async () => {
+    existsPredicate = (p) => p.includes('extract') && p.endsWith('agent-runtime')
+    tarExitCode = 1
+    computedDigest = 'f'.repeat(64)
+    wireDownload('f'.repeat(64))
+    await expect(installRuntime({ version: '2.0.0', target: 'linux-x64', logger: silentLogger }))
+      .rejects.toThrow(/tar exited 1/)
+  })
+
+  test('resolves latest version when none provided', async () => {
+    existsPredicate = (p) => p.includes('extract') && p.endsWith('agent-runtime')
+    computedDigest = '0'.repeat(64)
+    fetchHandler = (url: string) => {
+      if (url.includes('releases/latest')) return { ok: true, json: async () => ({ tag_name: 'v9.9.9' }) }
+      if (url.endsWith('.sha256')) return { ok: true, text: async () => `${'0'.repeat(64)}  x` }
+      return { ok: true, body: {} }
+    }
+    const res = await installRuntime({ target: 'linux-x64', baseUrl: ghBase, logger: silentLogger })
+    expect(res.version).toBe('9.9.9')
+  })
+})
+
+describe('runtime-install: getRuntimePaths', () => {
+  test('returns the three runtime paths', () => {
+    const p = getRuntimePaths()
+    expect(p.runtimeBin).toBe('/runtime/agent-runtime')
+    expect(p.versionFile).toBe('/runtime/version.json')
+  })
+})
+
+// ════════════════════════════════════════════════════════════════════════════
+// commands/project-checkout.ts
+// ════════════════════════════════════════════════════════════════════════════
+describe('project-checkout', () => {
+  test('throws without projectId', async () => {
+    await expect(runProjectCheckout('', {})).rejects.toThrow(/projectId is required/)
+  })
+  test('throws when local dir missing', async () => {
+    existsPredicate = () => false
+    await expect(runProjectCheckout('p1', {})).rejects.toThrow(/does not exist/)
+  })
+  test('throws when not a git repo', async () => {
+    existsPredicate = () => true
+    isGitRepoVal = false
+    await expect(runProjectCheckout('p1', {})).rejects.toThrow(/not a git repo/)
+  })
+  test('no --at fast-forwards to remote HEAD', async () => {
+    existsPredicate = () => true
+    await runProjectCheckout('p1', {})
+    expect(gitCalls.fetchReset.length).toBe(1)
+    expect(gitCalls.fetchReset[0].branch).toBeUndefined()
+  })
+  test('--unshallow runs unshallow before reset', async () => {
+    existsPredicate = () => true
+    await runProjectCheckout('p1', { unshallow: true })
+    expect(gitCalls.unshallow.length).toBe(1)
+  })
+  test('--at as resolvable SHA fetches that commit', async () => {
+    existsPredicate = () => true
+    runGitImpl = async (args) => {
+      if (args[0] === 'rev-parse') return { stdout: 'deadbeefdeadbeef\n', stderr: '' }
+      return { stdout: '', stderr: '' }
+    }
+    await runProjectCheckout('p1', { at: 'deadbeef' })
+    expect(gitCalls.fetchReset[0].branch).toBe('deadbeefdeadbeef')
+  })
+  test('--at falls back to checkpoint-name lookup', async () => {
+    existsPredicate = () => true
+    runGitImpl = async (args) => {
+      if (args[0] === 'rev-parse') throw new Error('not a sha')
+      return { stdout: '', stderr: '' }
+    }
+    fetchHandler = () => ({ ok: true, json: async () => ({
+      checkpoints: [{ id: 'c1', commitSha: 'cafebabecafebabe', name: 'My Save', commitMessage: 'x', createdAt: 'now' }],
+      hasMore: false,
+    }) })
+    await runProjectCheckout('p1', { at: 'My Save' })
+    expect(gitCalls.fetchReset[0].branch).toBe('cafebabecafebabe')
+  })
+  test('--at fetch failure triggers unshallow retry', async () => {
+    existsPredicate = () => true
+    runGitImpl = async (args) => (args[0] === 'rev-parse' ? { stdout: 'aa11bb22\n', stderr: '' } : { stdout: '', stderr: '' })
+    let calls = 0
+    fetchResetImpl = async () => { calls++; if (calls === 1) throw new Error('outside shallow window'); return { commitSha: 'aa11bb22' } }
+    await runProjectCheckout('p1', { at: 'aa11bb22' })
+    expect(gitCalls.unshallow.length).toBe(1)
+  })
+  test('--at fetch failure with --unshallow set throws', async () => {
+    existsPredicate = () => true
+    runGitImpl = async (args) => (args[0] === 'rev-parse' ? { stdout: 'aa11bb22\n', stderr: '' } : { stdout: '', stderr: '' })
+    fetchResetImpl = async () => { throw new Error('nope') }
+    await expect(runProjectCheckout('p1', { at: 'aa11bb22', unshallow: true })).rejects.toThrow(/Cannot reach commit/)
+  })
+})
+
+describe('project-checkout: resolveCheckpointByName branches', () => {
+  test('checkpoint list HTTP error throws', async () => {
+    existsPredicate = () => true
+    runGitImpl = async () => { throw new Error('not a sha') }
+    fetchHandler = () => ({ ok: false, status: 403 })
+    await expect(runProjectCheckout('p1', { at: 'foo' })).rejects.toThrow(/Failed to list checkpoints: HTTP 403/)
+  })
+  test('no matching checkpoint throws', async () => {
+    existsPredicate = () => true
+    runGitImpl = async () => { throw new Error('not a sha') }
+    fetchHandler = () => ({ ok: true, json: async () => ({ checkpoints: [], hasMore: false }) })
+    await expect(runProjectCheckout('p1', { at: 'foo' })).rejects.toThrow(/No checkpoint matches/)
+  })
+  test('matches by commitSha prefix', async () => {
+    existsPredicate = () => true
+    runGitImpl = async (args) => { if (args[0] === 'rev-parse') throw new Error('not a sha'); return { stdout: '', stderr: '' } }
+    fetchHandler = () => ({ ok: true, json: async () => ({
+      checkpoints: [{ id: 'c', commitSha: 'feed00001111', name: null, commitMessage: null, createdAt: 'n' }],
+      hasMore: false,
+    }) })
+    await runProjectCheckout('p1', { at: 'feed0000' })
+    expect(gitCalls.fetchReset[0].branch).toBe('feed00001111')
+  })
+  test('matches by commitMessage substring', async () => {
+    existsPredicate = () => true
+    runGitImpl = async (args) => { if (args[0] === 'rev-parse') throw new Error('not a sha'); return { stdout: '', stderr: '' } }
+    fetchHandler = () => ({ ok: true, json: async () => ({
+      checkpoints: [{ id: 'c', commitSha: '99887766aabb', name: null, commitMessage: 'Fix the LOGIN bug', createdAt: 'n' }],
+      hasMore: false,
+    }) })
+    await runProjectCheckout('p1', { at: 'login' })
+    expect(gitCalls.fetchReset[0].branch).toBe('99887766aabb')
+  })
+})
+
+// ════════════════════════════════════════════════════════════════════════════
+// commands/project-push.ts
+// ════════════════════════════════════════════════════════════════════════════
+describe('project-push', () => {
+  test('throws without projectId', async () => {
+    await expect(runProjectPush('', {})).rejects.toThrow(/projectId is required/)
+  })
+  test('throws when source dir missing', async () => {
+    existsPredicate = () => false
+    await expect(runProjectPush('p1', {})).rejects.toThrow(/Source directory does not exist/)
+  })
+  test('happy path uploads and prints success summary', async () => {
+    existsPredicate = () => true
+    uploadAllImpl = async () => ({ uploaded: 5, deleted: 0, errors: [] })
+    await runProjectPush('p1', {})
+    expect(lastTransportOpts.projectId).toBe('p1')
+  })
+  test('deleteRemote flag forwarded to uploadAll', async () => {
+    existsPredicate = () => true
+    let seen: any = null
+    uploadAllImpl = async (o) => { seen = o; return { uploaded: 1, deleted: 2, errors: [] } }
+    await runProjectPush('p1', { deleteRemote: true })
+    expect(seen.deleteRemote).toBe(true)
+  })
+  test('include csv parsed into array', async () => {
+    existsPredicate = () => true
+    await runProjectPush('p1', { include: 'src, dist ,, README.md' })
+    expect(lastTransportOpts.include).toEqual(['src', 'dist', 'README.md'])
+  })
+  test('error summary prints first 5 + overflow note', async () => {
+    existsPredicate = () => true
+    const errors = Array.from({ length: 7 }, (_, i) => ({ path: `f${i}`, message: 'boom' }))
+    uploadAllImpl = async () => ({ uploaded: 0, deleted: 0, errors })
+    await runProjectPush('p1', {})
+    expect(lastTransportOpts.projectId).toBe('p1')
+  })
+  test('onProgress callback handles upload/delete/other + byte formats', async () => {
+    existsPredicate = () => true
+    uploadAllImpl = async (o) => {
+      const cb = o.ctor.onProgress
+      cb({ kind: 'upload', index: 0, total: 3, path: 'a', bytes: 512 })          // <1KB
+      cb({ kind: 'delete', index: 1, total: 3, path: 'b', bytes: 2048 })         // KB
+      cb({ kind: 'scan', index: 2, total: 0, path: 'c', bytes: 5 * 1024 * 1024 }) // MB, total 0
+      cb({ kind: 'upload', index: 2, total: 3, path: 'd', bytes: null })          // no bytes
+      return { uploaded: 1, deleted: 1, errors: [] }
+    }
+    await runProjectPush('p1', {})
+    expect(lastTransportOpts.projectId).toBe('p1')
+  })
+})
+
+afterAll(() => {
+  mock.restore()
+})

package/src/lib/__tests__/worker-libs-greenfield.test.ts

@@ -0,0 +1,355 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Greenfield sweep for three never-loaded shogo-worker libs:
+ *   api-discovery.ts, process-manager.ts, preflight.ts
+ * Shared mocks: node:fs (controllable), node:child_process (fake spawn),
+ * ./paths, ./transport.
+ */
+import { describe, test, expect, beforeEach, afterEach, mock, afterAll } from 'bun:test'
+import { EventEmitter } from 'node:events'
+
+// ── controllable node:fs ──────────────────────────────────────────────────────
+let existsMap: Record<string, boolean> = {}
+let existsPredicate: ((p: string) => boolean) | null = null
+let pidFileContent: string | null = null
+const fsWrites: Array<{ path: string; data: string }> = []
+const fsUnlinks: string[] = []
+let unlinkThrows = false
+
+mock.module('node:fs', () => ({
+  existsSync: (p: string) => {
+    const s = String(p)
+    if (existsPredicate) return existsPredicate(s)
+    if (s in existsMap) return existsMap[s]
+    // PID file existence keyed off pidFileContent
+    if (s.endsWith('worker.pid')) return pidFileContent !== null
+    return false
+  },
+  readFileSync: (p: string) => {
+    if (String(p).endsWith('worker.pid')) return pidFileContent ?? ''
+    return ''
+  },
+  writeFileSync: (p: string, data: string) => { fsWrites.push({ path: String(p), data: String(data) }) },
+  unlinkSync: (p: string) => { if (unlinkThrows) throw new Error('ENOENT'); fsUnlinks.push(String(p)) },
+  openSync: () => 7,
+}))
+
+// ── fake child_process.spawn ──────────────────────────────────────────────────
+let spawnPid: number | undefined = 4242
+let lastSpawn: { cmd: string; args: string[]; opts: any; child: any } | null = null
+class FakeChild extends EventEmitter {
+  pid: number | undefined
+  killed: string | null = null
+  unrefed = false
+  constructor(pid: number | undefined) { super(); this.pid = pid }
+  kill(sig: string) { this.killed = sig }
+  unref() { this.unrefed = true }
+}
+mock.module('node:child_process', () => ({
+  spawn: (cmd: string, args: string[], opts: any) => {
+    const child = new FakeChild(spawnPid)
+    lastSpawn = { cmd, args, opts, child }
+    return child
+  },
+}))
+
+// ── ./paths ───────────────────────────────────────────────────────────────────
+let ensureHomeCalls = 0
+mock.module('../paths.ts', () => ({
+  PID_FILE: '/home/.shogo/worker.pid',
+  WORKER_LOG: '/home/.shogo/logs/worker.log',
+  WORKER_ERR: '/home/.shogo/logs/worker.err.log',
+  ensureHome: () => { ensureHomeCalls++ },
+}))
+
+// ── ./transport (for preflight) ────────────────────────────────────────────────
+// Delegate to the REAL transport by default so sibling files that import the
+// genuine module (e.g. worker-transport-greenfield.test.ts) are not shadowed by
+// this file's process-global mock. Individual tests below override the impls.
+const _realTransport = require('../transport')
+const _defaultAllowlist = _realTransport.deriveAllowlist
+const _defaultProbeProxy = _realTransport.probeProxy
+let allowlistImpl: (cloudUrl: string) => any[] = _defaultAllowlist
+let probeProxyImpl: (...a: any[]) => Promise<{ ok: boolean; detail?: string }> = _defaultProbeProxy
+mock.module('../transport.ts', () => ({
+  ..._realTransport,
+  deriveAllowlist: (u: string) => allowlistImpl(u),
+  probeProxy: (...a: any[]) => probeProxyImpl(...a),
+}))
+
+import { findApiEntry } from '../api-discovery'
+import { readPid, isRunning, clearPid, spawnWorker, installShutdownHooks, stopWorker } from '../process-manager'
+import { makeChecks, runPreflight, type Check } from '../preflight'
+
+beforeEach(() => {
+  existsMap = {}; pidFileContent = null; unlinkThrows = false
+  fsWrites.length = 0; fsUnlinks.length = 0
+  spawnPid = 4242; lastSpawn = null; ensureHomeCalls = 0
+  existsPredicate = null
+})
+
+function mockExists(fn: (p: string) => boolean) { existsPredicate = fn }
+
+// ════════════════════════════════════════════════════════════════════════════
+describe('api-discovery.findApiEntry', () => {
+  test('prefers bundled dist entry (node runner) when present', () => {
+    mockExists((p) => p.endsWith('entry.js'))
+    const r = findApiEntry()
+    expect(r.mode).toBe('bundled')
+    expect(r.runner).toBe('node')
+    expect(r.entry).toContain('entry.js')
+  })
+  test('falls back to monorepo entry (bun runner)', () => {
+    mockExists((p) => p.endsWith('entry.ts'))
+    const r = findApiEntry()
+    expect(r.mode).toBe('monorepo')
+    expect(r.runner).toBe('bun')
+    expect(r.entry).toContain('entry.ts')
+  })
+  test('throws when neither entry exists', () => {
+    mockExists(() => false)
+    expect(() => findApiEntry()).toThrow('Cannot locate apps/api entry')
+  })
+})
+
+// ════════════════════════════════════════════════════════════════════════════
+describe('process-manager', () => {
+  test('readPid returns null when no pid file, parses int when present', () => {
+    pidFileContent = null
+    expect(readPid()).toBe(null)
+    pidFileContent = '  12345 \n'
+    expect(readPid()).toBe(12345)
+    pidFileContent = 'not-a-number'
+    expect(readPid()).toBe(null)
+  })
+
+  test('isRunning reflects process.kill(pid,0)', () => {
+    const realKill = process.kill
+    ;(process as any).kill = (_pid: number, _sig: number) => true
+    expect(isRunning(999)).toBe(true)
+    ;(process as any).kill = () => { throw new Error('ESRCH') }
+    expect(isRunning(999)).toBe(false)
+    process.kill = realKill
+  })
+
+  test('clearPid swallows unlink errors', () => {
+    unlinkThrows = true
+    expect(() => clearPid()).not.toThrow()
+    unlinkThrows = false
+    clearPid()
+    expect(fsUnlinks).toContain('/home/.shogo/worker.pid')
+  })
+
+  test('spawnWorker spawns, writes pid file, returns pid', () => {
+    const realKill = process.kill
+    ;(process as any).kill = () => { throw new Error('ESRCH') } // no existing process
+    pidFileContent = null
+    const { pid, child } = spawnWorker({ entry: '/e.ts', runner: 'bun', env: {}, cwd: '/w' })
+    expect(pid).toBe(4242)
+    expect(ensureHomeCalls).toBe(1)
+    expect(lastSpawn!.cmd).toBe('bun')
+    expect(fsWrites.some((w) => w.path.endsWith('worker.pid') && w.data === '4242')).toBe(true)
+    expect((child as any).unrefed).toBe(false)
+    process.kill = realKill
+  })
+
+  test('spawnWorker detached unrefs the child + inheritStdio path', () => {
+    const realKill = process.kill
+    ;(process as any).kill = () => { throw new Error('ESRCH') }
+    pidFileContent = null
+    const { child } = spawnWorker({ entry: '/e', runner: 'node', env: {}, cwd: '/w', detach: true, inheritStdio: true })
+    expect((child as any).unrefed).toBe(true)
+    expect(lastSpawn!.opts.detached).toBe(true)
+    process.kill = realKill
+  })
+
+  test('spawnWorker throws when a live worker already holds the pid file', () => {
+    const realKill = process.kill
+    pidFileContent = '777'
+    ;(process as any).kill = () => true // existing pid is alive
+    expect(() => spawnWorker({ entry: '/e', runner: 'bun', env: {}, cwd: '/w' })).toThrow('already running')
+    process.kill = realKill
+  })
+
+  test('spawnWorker clears a stale pid file then spawns', () => {
+    const realKill = process.kill
+    pidFileContent = '888'
+    let calls = 0
+    ;(process as any).kill = () => { calls++; throw new Error('ESRCH') } // stale
+    const { pid } = spawnWorker({ entry: '/e', runner: 'bun', env: {}, cwd: '/w' })
+    expect(pid).toBe(4242)
+    expect(fsUnlinks).toContain('/home/.shogo/worker.pid') // stale cleared
+    process.kill = realKill
+  })
+
+  test('spawnWorker throws when spawn yields no pid', () => {
+    const realKill = process.kill
+    ;(process as any).kill = () => { throw new Error('ESRCH') }
+    spawnPid = undefined
+    pidFileContent = null
+    expect(() => spawnWorker({ entry: '/e', runner: 'bun', env: {}, cwd: '/w' })).toThrow('Failed to spawn')
+    process.kill = realKill
+  })
+
+  test('stopWorker: null when no pid; clears stale; kills live', () => {
+    const realKill = process.kill
+    pidFileContent = null
+    expect(stopWorker().killedPid).toBe(null)
+    // stale
+    pidFileContent = '321'
+    ;(process as any).kill = (_p: number, sig: any) => { if (sig === 0) throw new Error('ESRCH'); return true }
+    expect(stopWorker().killedPid).toBe(null)
+    expect(fsUnlinks).toContain('/home/.shogo/worker.pid')
+    // live
+    pidFileContent = '654'
+    ;(process as any).kill = () => true
+    expect(stopWorker('SIGKILL').killedPid).toBe(654)
+    process.kill = realKill
+  })
+
+  test('installShutdownHooks forwards signal to child + clears pid; child exit triggers process.exit', () => {
+    const realKill = process.kill
+    const realExit = process.exit
+    const onceHandlers: Record<string, Function> = {}
+    const realOnce = process.once
+    ;(process as any).once = (evt: string, fn: Function) => { onceHandlers[evt] = fn; return process }
+    let exitCode: number | undefined
+    ;(process as any).exit = (c?: number) => { exitCode = c; throw new Error('__exit__') }
+
+    const child = new FakeChild(111)
+    installShutdownHooks(child as any)
+    // trigger SIGINT
+    onceHandlers['SIGINT']?.()
+    expect(child.killed).toBe('SIGINT')
+    expect(fsUnlinks).toContain('/home/.shogo/worker.pid')
+    // second invocation is a no-op (shutdownStarted guard)
+    onceHandlers['SIGTERM']?.()
+    // child 'exit' with a code → process.exit(code)
+    expect(() => child.emit('exit', 3, null)).toThrow('__exit__')
+    expect(exitCode).toBe(3)
+
+    process.once = realOnce; process.exit = realExit; process.kill = realKill
+  })
+
+  test('installShutdownHooks exit handler with signal maps to 128+n', () => {
+    const realExit = process.exit
+    const onceHandlers: Record<string, Function> = {}
+    const realOnce = process.once
+    ;(process as any).once = (evt: string, fn: Function) => { onceHandlers[evt] = fn; return process }
+    let exitCode: number | undefined
+    ;(process as any).exit = (c?: number) => { exitCode = c; throw new Error('__exit__') }
+    const child = new FakeChild(222)
+    installShutdownHooks(child as any)
+    expect(() => child.emit('exit', null, 'SIGTERM')).toThrow('__exit__')
+    expect(exitCode).toBe(128 + 15)
+    // 'exit' process handler clears pid when no shutdown started
+    onceHandlers['exit']?.()
+    process.once = realOnce; process.exit = realExit
+  })
+})
+
+// ════════════════════════════════════════════════════════════════════════════
+describe('preflight', () => {
+  const baseOpts = { cloudUrl: 'https://api.shogo.dev', apiKey: 'K', workerDir: '/worker' }
+  const ORIGINAL_FETCH = globalThis.fetch
+  afterEach(() => { globalThis.fetch = ORIGINAL_FETCH })
+
+  test('makeChecks: node-version + worker-dir + allowlist + api-key checks; proxy added when set', async () => {
+    existsMap = { '/worker': true }
+    const checks = makeChecks(baseOpts)
+    const names = checks.map((c) => c.name)
+    expect(names[0]).toContain('Runtime')
+    expect(names.some((n) => n.includes('Worker directory'))).toBe(true)
+    expect(names.some((n) => n.includes('Reach api.shogo.dev'))).toBe(true)
+    expect(names.some((n) => n.includes('API key valid'))).toBe(true)
+    expect(names.some((n) => n.includes('Proxy'))).toBe(false)
+
+    const withProxy = makeChecks({ ...baseOpts, proxy: { url: 'http://proxy:3128' } as any })
+    expect(withProxy.some((c) => c.name.includes('Proxy reachable (proxy:3128)'))).toBe(true)
+  })
+
+  test('node-version check passes on >=20, worker-dir reflects existsSync', async () => {
+    existsMap = { '/worker': true }
+    const checks = makeChecks(baseOpts)
+    const node = await checks[0].run()
+    expect(node.ok).toBe(true) // test runner is node>=20
+    const dirOk = await checks[1].run()
+    expect(dirOk.ok).toBe(true)
+    existsMap = { '/worker': false }
+    const dirBad = await makeChecks(baseOpts)[1].run()
+    expect(dirBad.ok).toBe(false)
+    expect(dirBad.detail).toContain('does not exist')
+  })
+
+  test('allowlist health probe: ok, no-response, and abort/error paths', async () => {
+    existsMap = { '/worker': true }
+    // ok
+    globalThis.fetch = (async () => ({ status: 200 })) as any
+    let checks = makeChecks(baseOpts)
+    const reach = checks.find((c) => c.name.includes('Reach api.shogo.dev'))!
+    expect(await reach.run()).toMatchObject({ ok: true, detail: 'HTTP 200' })
+    // no response (fetch resolves null via .catch)
+    globalThis.fetch = (async () => { throw new Error('conn refused') }) as any
+    checks = makeChecks(baseOpts)
+    const reach2 = checks.find((c) => c.name.includes('Reach api.shogo.dev'))!
+    expect((await reach2.run()).ok).toBe(false)
+  })
+
+  test('api-key check: 401 rejected, ok, and thrown error', async () => {
+    existsMap = { '/worker': true }
+    globalThis.fetch = (async () => ({ status: 401, ok: false })) as any
+    let key = makeChecks(baseOpts).find((c) => c.name.includes('API key'))!
+    expect(await key.run()).toMatchObject({ ok: false })
+    globalThis.fetch = (async () => ({ status: 200, ok: true })) as any
+    key = makeChecks(baseOpts).find((c) => c.name.includes('API key'))!
+    expect(await key.run()).toMatchObject({ ok: true })
+    globalThis.fetch = (async () => ({ status: 500, ok: false })) as any
+    key = makeChecks(baseOpts).find((c) => c.name.includes('API key'))!
+    expect((await key.run()).ok).toBe(false)
+    globalThis.fetch = (async () => { throw new Error('network') }) as any
+    key = makeChecks(baseOpts).find((c) => c.name.includes('API key'))!
+    expect(await key.run()).toMatchObject({ ok: false, detail: 'network' })
+  })
+
+  test('proxy check delegates to probeProxy', async () => {
+    existsMap = { '/worker': true }
+    probeProxyImpl = async () => ({ ok: false, detail: 'proxy down' })
+    const checks = makeChecks({ ...baseOpts, proxy: { url: 'http://p:1' } as any })
+    const proxy = checks.find((c) => c.name.includes('Proxy'))!
+    expect(await proxy.run()).toMatchObject({ ok: false, detail: 'proxy down' })
+    probeProxyImpl = _defaultProbeProxy
+  })
+
+  test('makeChecks safeHost falls back to raw on bad proxy URL', () => {
+    const checks = makeChecks({ ...baseOpts, proxy: { url: 'not a url' } as any })
+    expect(checks.some((c) => c.name.includes('not a url'))).toBe(true)
+  })
+
+  test('runPreflight: all-pass returns true', async () => {
+    const checks: Check[] = [
+      { name: 'a', criticality: 'fatal', run: async () => ({ ok: true, detail: 'd' }) },
+      { name: 'b', criticality: 'graceful', run: async () => ({ ok: true }) },
+    ]
+    expect(await runPreflight(checks)).toBe(true)
+  })
+
+  test('runPreflight: graceful failure still returns true', async () => {
+    const checks: Check[] = [
+      { name: 'a', criticality: 'fatal', run: async () => ({ ok: true }) },
+      { name: 'b', criticality: 'graceful', run: async () => ({ ok: false, detail: 'optional down' }) },
+    ]
+    expect(await runPreflight(checks)).toBe(true)
+  })
+
+  test('runPreflight: fatal failure returns false', async () => {
+    const checks: Check[] = [
+      { name: 'a', criticality: 'fatal', run: async () => ({ ok: false, detail: 'boom' }) },
+    ]
+    expect(await runPreflight(checks)).toBe(false)
+  })
+})
+
+afterAll(() => {
+  mock.restore()
+})

package/src/lib/__tests__/worker-transport-greenfield.test.ts

@@ -0,0 +1,176 @@
+// SPDX-License-Identifier: MIT
+// Copyright (C) 2026 Shogo Technologies, Inc.
+/**
+ * Greenfield coverage for lib/transport.ts — corporate proxy resolution,
+ * env injection, CONNECT-based reachability probe, and allowlist derivation.
+ * node:http is mocked with a scriptable fake CONNECT request emitter.
+ */
+import { describe, test, expect, beforeEach, afterEach, afterAll, mock } from 'bun:test'
+import { EventEmitter } from 'node:events'
+
+// ── scriptable node:http request mock ─────────────────────────────────────────
+type ConnectScript =
+  | { kind: 'connect'; statusCode: number }
+  | { kind: 'timeout' }
+  | { kind: 'error'; code?: string; message?: string }
+  | { kind: 'throw'; message: string }
+let connectScript: ConnectScript = { kind: 'connect', statusCode: 200 }
+let lastRequestOpts: any = null
+const _realHttp = require('node:http')
+
+class FakeClientRequest extends EventEmitter {
+  destroyed = false
+  destroy() { this.destroyed = true }
+  end() {
+    queueMicrotask(() => {
+      if (connectScript.kind === 'connect') {
+        this.emit('connect', { statusCode: connectScript.statusCode }, {}, Buffer.from(''))
+      } else if (connectScript.kind === 'timeout') {
+        this.emit('timeout')
+      } else if (connectScript.kind === 'error') {
+        const e: NodeJS.ErrnoException = new Error(connectScript.message ?? 'socket error')
+        if (connectScript.code) e.code = connectScript.code
+        this.emit('error', e)
+      }
+    })
+  }
+}
+mock.module('node:http', () => ({
+  ..._realHttp,
+  request: (opts: any) => {
+    lastRequestOpts = opts
+    if (connectScript.kind === 'throw') throw new Error(connectScript.message)
+    return new FakeClientRequest()
+  },
+}))
+
+import { resolveProxy, applyProxyToEnv, probeProxy, deriveAllowlist } from '../transport'
+
+beforeEach(() => {
+  connectScript = { kind: 'connect', statusCode: 200 }
+  lastRequestOpts = null
+})
+afterAll(() => {
+  mock.module('node:http', () => _realHttp)
+})
+
+// ════════════════════════════════════════════════════════════════════════════
+describe('resolveProxy', () => {
+  test('flag wins over every env var', () => {
+    const r = resolveProxy('proxy.corp:8080', { HTTPS_PROXY: 'http://env:1' })
+    expect(r).toEqual({ url: 'http://proxy.corp:8080', source: 'flag' })
+  })
+  test('already-schemed flag is preserved', () => {
+    expect(resolveProxy('https://p.corp:443')?.url).toBe('https://p.corp:443')
+  })
+  test('env precedence: HTTPS_PROXY > https_proxy > HTTP_PROXY > http_proxy', () => {
+    expect(resolveProxy(undefined, { HTTPS_PROXY: 'a:1', https_proxy: 'b:2' })?.source).toBe('HTTPS_PROXY')
+    expect(resolveProxy(undefined, { https_proxy: 'b:2', HTTP_PROXY: 'c:3' })?.source).toBe('https_proxy')
+    expect(resolveProxy(undefined, { HTTP_PROXY: 'c:3', http_proxy: 'd:4' })?.source).toBe('HTTP_PROXY')
+    expect(resolveProxy(undefined, { http_proxy: 'd:4' })?.source).toBe('http_proxy')
+  })
+  test('normalizes bare host:port to http://', () => {
+    expect(resolveProxy(undefined, { HTTPS_PROXY: 'host:3128' })?.url).toBe('http://host:3128')
+  })
+  test('whitespace-only and empty values are ignored', () => {
+    expect(resolveProxy('   ', { HTTPS_PROXY: '  ', http_proxy: 'real:9' })?.source).toBe('http_proxy')
+  })
+  test('returns null when nothing is set', () => {
+    expect(resolveProxy(undefined, {})).toBeNull()
+  })
+})
+
+describe('applyProxyToEnv', () => {
+  test('returns env unchanged when proxy is null', () => {
+    const env = { FOO: 'bar' }
+    expect(applyProxyToEnv(env, null)).toBe(env)
+  })
+  test('injects all four variants when unset', () => {
+    const out = applyProxyToEnv({ PATH: '/x' }, { url: 'http://p:8080', source: 'flag' })
+    expect(out.HTTPS_PROXY).toBe('http://p:8080')
+    expect(out.https_proxy).toBe('http://p:8080')
+    expect(out.HTTP_PROXY).toBe('http://p:8080')
+    expect(out.http_proxy).toBe('http://p:8080')
+    expect(out.PATH).toBe('/x')
+  })
+  test('does not overwrite pre-existing proxy vars', () => {
+    const out = applyProxyToEnv({ HTTPS_PROXY: 'http://keep:1' }, { url: 'http://new:2', source: 'flag' })
+    expect(out.HTTPS_PROXY).toBe('http://keep:1')
+    expect(out.http_proxy).toBe('http://new:2')
+  })
+})
+
+describe('probeProxy', () => {
+  const proxy = { url: 'http://proxy.corp:3128', source: 'flag' as const }
+
+  test('CONNECT 200 → ok with detail', async () => {
+    connectScript = { kind: 'connect', statusCode: 200 }
+    const r = await probeProxy(proxy, 'api.shogo.ai')
+    expect(r.ok).toBe(true)
+    expect(r.detail).toContain('200')
+    expect(lastRequestOpts.method).toBe('CONNECT')
+    expect(lastRequestOpts.path).toBe('api.shogo.ai:443')
+  })
+  test('407 → not ok, surfaces auth hint with source', async () => {
+    connectScript = { kind: 'connect', statusCode: 407 }
+    const r = await probeProxy(proxy)
+    expect(r.ok).toBe(false)
+    expect(r.detail).toContain('407')
+    expect(r.detail).toContain('flag')
+  })
+  test('other status → not ok', async () => {
+    connectScript = { kind: 'connect', statusCode: 502 }
+    const r = await probeProxy(proxy)
+    expect(r.ok).toBe(false)
+    expect(r.detail).toContain('HTTP 502')
+  })
+  test('timeout → not ok', async () => {
+    connectScript = { kind: 'timeout' }
+    const r = await probeProxy(proxy, 'api.shogo.ai', 1234)
+    expect(r.ok).toBe(false)
+    expect(r.detail).toContain('1234ms')
+  })
+  test('socket error with code → not ok with code', async () => {
+    connectScript = { kind: 'error', code: 'ECONNREFUSED', message: 'refused' }
+    const r = await probeProxy(proxy)
+    expect(r.ok).toBe(false)
+    expect(r.detail).toContain('ECONNREFUSED')
+  })
+  test('https proxy url with no port defaults to 443', async () => {
+    connectScript = { kind: 'connect', statusCode: 200 }
+    await probeProxy({ url: 'https://secure.proxy', source: 'HTTPS_PROXY' })
+    expect(lastRequestOpts.port).toBe(443)
+  })
+  test('http proxy url with no port defaults to 80', async () => {
+    await probeProxy({ url: 'http://plain.proxy', source: 'HTTP_PROXY' })
+    expect(lastRequestOpts.port).toBe(80)
+  })
+  test('synchronous throw (bad URL) is caught', async () => {
+    connectScript = { kind: 'throw', message: 'boom' }
+    const r = await probeProxy(proxy)
+    expect(r.ok).toBe(false)
+    expect(r.detail).toBe('boom')
+  })
+})
+
+describe('deriveAllowlist', () => {
+  test('three-label host → control + tunnel + artifacts', () => {
+    const list = deriveAllowlist('https://studio.shogo.ai')
+    expect(list.map((h) => h.purpose)).toEqual(['control', 'tunnel-direct', 'artifacts'])
+    expect(list[0]).toMatchObject({ host: 'studio.shogo.ai', criticality: 'fatal' })
+    expect(list[1].host).toBe('api-direct.shogo.ai')
+    expect(list[2].host).toBe('artifacts.shogo.ai')
+  })
+  test('two-label root domain kept as-is', () => {
+    const list = deriveAllowlist('https://shogo.ai')
+    expect(list[1].host).toBe('api-direct.shogo.ai')
+  })
+  test('preserves non-https scheme', () => {
+    const list = deriveAllowlist('http://eu.shogo.dev:8443')
+    expect(list[0].url).toBe('http://eu.shogo.dev:8443')
+    expect(list[2].url).toBe('http://artifacts.shogo.dev')
+  })
+  test('invalid URL → empty list', () => {
+    expect(deriveAllowlist('not a url')).toEqual([])
+  })
+})