harmoniqs · jack-champagne · Jun 18, 2026 · Jun 10, 2026 · Jun 10, 2026 · Jun 10, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,16 @@
+name: ci
+on:
+ push: { branches: [main] }
+ pull_request:
+jobs:
+ fast:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: pnpm/action-setup@v4 # version pinned by packageManager in package.json
+ - uses: actions/setup-node@v4
+ with: { node-version: 20, cache: pnpm }
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm -r run build
+ - run: pnpm -r run typecheck
+ - run: pnpm --filter @amicode/amico-run test # includes the S31 grep-rule test
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -5,8 +5,8 @@
  "name": "Run Extension (amicode-v2)",
  "type": "extensionHost",
  "request": "launch",
- "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
- "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+ "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/extension"],
+ "outFiles": ["${workspaceFolder}/packages/extension/dist/**/*.js"]
  }
  ]
 }
diff --git a/bin/amico-run b/bin/amico-run
diff --git a/package.json b/package.json
@@ -1,85 +1,10 @@
 {
- "name": "amicode-v2",
- "displayName": "Amicode v2",
- "description": "Amico research IDE — opencode-backed chat + native VS Code surfaces for vault, catalog, and live solve inspection.",
- "version": "0.0.1",
- "publisher": "harmoniqs",
- "license": "Apache-2.0",
+ "name": "amicode-workspace",
  "private": true,
- "engines": {
- "vscode": "^1.95.0"
- },
- "categories": ["Other"],
- "activationEvents": [
- "onCommand:amicode.openChat",
- "onCommand:amicode.openInspector",
- "onView:amicode.runInspector",
- "onView:amicode.vault",
- "onStartupFinished"
- ],
- "main": "./dist/extension.js",
- "contributes": {
- "viewsContainers": {
- "activitybar": [
- {
- "id": "amicode",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ],
- "panel": [
- {
- "id": "amicode-panel",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ]
- },
- "views": {
- "amicode": [
- { "id": "amicode.vault", "name": "Vault", "type": "tree" },
- { "id": "amicode.catalog", "name": "Catalog", "type": "tree" },
- { "id": "amicode.armonia", "name": "Armonia", "type": "tree" }
- ],
- "amicode-panel": [
- { "id": "amicode.runInspector", "name": "Run Inspector", "type": "webview" }
- ]
- },
- "commands": [
- { "command": "amicode.openChat", "title": "Amicode: Open Chat" },
- { "command": "amicode.openInspector", "title": "Amicode: Open Run Inspector" },
- { "command": "amicode.restartServer", "title": "Amicode: Restart opencode server" }
- ],
- "configuration": {
- "title": "Amicode",
- "properties": {
- "amicode.opencodeBinary": {
- "type": "string",
- "default": "opencode",
- "description": "Path or command name for the opencode CLI."
- },
- "amicode.juliaProject": {
- "type": "string",
- "default": "/tmp/amicode-spike-julia",
- "description": "Julia project root (--project=...) the run_julia tool will use."
- },
- "amicode.juliaScript": {
- "type": "string",
- "default": "",
- "description": "Absolute path to spike_solve.jl. If empty, looks up via the extensionPath/../amicode/julia/spike_solve.jl convention."
- }
- }
- }
- },
  "scripts": {
- "build":  "node esbuild.config.mjs",
- "watch":  "node esbuild.config.mjs --watch",
- "typecheck": "tsc --noEmit"
+ "build": "pnpm -r run build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test"
  },
- "devDependencies": {
- "@types/node": "^22.0.0",
- "@types/vscode": "^1.95.0",
- "esbuild": "^0.24.0",
- "typescript": "^5.6.0"
- }
+ "packageManager": "pnpm@9.15.9"
 }
diff --git a/packages/amico-run/esbuild.config.mjs b/packages/amico-run/esbuild.config.mjs
@@ -0,0 +1,17 @@
+import { build } from 'esbuild'
+import { chmodSync } from 'node:fs'
+
+await build({
+ entryPoints: ['src/cli.ts'],
+ bundle: true,
+ platform: 'node',
+ target: 'node20',
+ // ESM, not CJS: the package is "type": "module", so node executes dist/amico-run.js
+ // as ESM — a CJS bundle would die on `require is not defined in ES module scope`.
+ format: 'esm',
+ outfile: 'dist/amico-run.js',
+ banner: { js: '#!/usr/bin/env node' },
+ sourcemap: true,
+ logLevel: 'info',
+})
+chmodSync('dist/amico-run.js', 0o755)
diff --git a/packages/amico-run/launcher/amico-run b/packages/amico-run/launcher/amico-run
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Thin launcher: resolve node, exec the bundled orchestrator. No logic lives here.
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve symlink chains (node_modules/.bin)
+ DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+ SOURCE="$(readlink "$SOURCE")"
+ [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+if ! command -v node >/dev/null 2>&1; then
+ echo "amico-run: node >= 20 not found on PATH (install node or fix PATH; see provisioning runbook)" >&2
+ exit 64
+fi
+exec node "$DIR/../dist/amico-run.js" "$@"
diff --git a/packages/amico-run/package.json b/packages/amico-run/package.json
@@ -0,0 +1,23 @@
+{
+ "name": "@amicode/amico-run",
+ "version": "0.1.0",
+ "license": "Apache-2.0",
+ "type": "module",
+ "main": "./src/index.ts",
+ "types": "./src/index.ts",
+ "bin": { "amico-run": "./launcher/amico-run" },
+ "engines": { "node": ">=20" },
+ "scripts": {
+ "build": "node esbuild.config.mjs",
+ "typecheck": "tsc --noEmit",
+ "test": "vitest run --passWithNoTests --exclude '**/slow/**'",
+ "test:slow": "vitest run test/slow"
+ },
+ "devDependencies": {
+ "@types/node": "^22.0.0",
+ "esbuild": "^0.24.0",
+ "smol-toml": "^1.3.0",
+ "typescript": "^5.6.0",
+ "vitest": "^2.1.0"
+ }
+}
diff --git a/packages/amico-run/src/cli.ts b/packages/amico-run/src/cli.ts
@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { LocalExecutor } from './local_executor.js'
+import { ConfigError, type Finished, type SubmitOpts } from './types.js'
+
+const USAGE = `usage: amico-run <script.jl> [--executor local] [--lab <id-or-path>]
+ [--runs-root <path>] [--julia <path>] [--project <path>] [--sysimage <path>]`
+
+export async function main(argv: string[]): Promise<number> {
+ let script: string | undefined
+ let executor = 'local'
+ const opts: SubmitOpts = { julia: {} }
+
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i]
+ const next = (): string => {
+ const v = argv[++i]
+ if (v === undefined) throw new ConfigError(`flag ${a} requires a value`)
+ return v
+ }
+ try {
+ switch (a) {
+ case '--help': case '-h': console.log(USAGE); return 0
+ case '--executor': executor = next(); break
+ case '--lab': opts.lab = next(); break
+ case '--runs-root': opts.runsRoot = next(); break
+ case '--julia': opts.julia!.julia = next(); break
+ case '--project': opts.julia!.project = next(); break
+ case '--sysimage': opts.julia!.sysimage = next(); break
+ default:
+ if (a.startsWith('-')) { console.error(`amico-run: unknown flag ${a}\n${USAGE}`); return 64 }
+ if (script) { console.error(`amico-run: multiple scripts given`); return 64 }
+ script = a
+ }
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+ }
+ if (!script) { console.error(`amico-run: no script given\n${USAGE}`); return 64 }
+ if (executor !== 'local') { console.error(`amico-run: only --executor local is supported in β`); return 64 }
+
+ let handle
+ try {
+ handle = await new LocalExecutor().submit(script, opts)
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+
+ const onSignal = (): void => { void handle.abort() }
+ process.on('SIGINT', onSignal)
+ process.on('SIGTERM', onSignal)
+
+ let fin: Finished | undefined
+ for await (const ev of handle.events) {
+ if (ev.kind === 'iter' || ev.kind === 'done') console.log(ev.raw)
+ else if (ev.kind === 'log') console.log(ev.line)
+ else fin = { status: ev.status, exitCode: ev.exitCode }
+ }
+ const f = fin ?? await handle.finished
+
+ // FINISHED-write failure lane (spec §6 last row): verdict file must exist on disk
+ if (!existsSync(join(handle.runDir, 'FINISHED'))) {
+ console.error(`amico-run: FINISHED missing in ${handle.runDir} (write fault)`)
+ return 64
+ }
+ // stdout protocol line — camelCase by design (spec §4)
+ console.log(`AMICODE_FINISHED status=${f.status} exitCode=${f.exitCode} runDir=${handle.runDir}`)
+ if (f.status === 'aborted') return 130
+ if (f.status === 'completed') return 0
+ return f.exitCode === 0 ? 1 : f.exitCode
+}
+
+main(process.argv.slice(2)).then(
+ c => { process.exitCode = c },
+ e => {
+ // Any unexpected throw is an orchestrator fault, not a solve failure → 64.
+ console.error(`amico-run: unexpected error: ${e instanceof Error ? e.stack ?? e.message : e}`)
+ process.exitCode = 64
+ },
+)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,16 @@
+name: ci
+on:
+ push: { branches: [main] }
+ pull_request:
+jobs:
+ fast:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: pnpm/action-setup@v4 # version pinned by packageManager in package.json
+ - uses: actions/setup-node@v4
+ with: { node-version: 20, cache: pnpm }
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm -r run build
+ - run: pnpm -r run typecheck
+ - run: pnpm --filter @amicode/amico-run test # includes the S31 grep-rule test
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -5,8 +5,8 @@
  "name": "Run Extension (amicode-v2)",
  "type": "extensionHost",
  "request": "launch",
- "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
- "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+ "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/extension"],
+ "outFiles": ["${workspaceFolder}/packages/extension/dist/**/*.js"]
  }
  ]
 }
diff --git a/bin/amico-run b/bin/amico-run
diff --git a/package.json b/package.json
@@ -1,85 +1,10 @@
 {
- "name": "amicode-v2",
- "displayName": "Amicode v2",
- "description": "Amico research IDE — opencode-backed chat + native VS Code surfaces for vault, catalog, and live solve inspection.",
- "version": "0.0.1",
- "publisher": "harmoniqs",
- "license": "Apache-2.0",
+ "name": "amicode-workspace",
  "private": true,
- "engines": {
- "vscode": "^1.95.0"
- },
- "categories": ["Other"],
- "activationEvents": [
- "onCommand:amicode.openChat",
- "onCommand:amicode.openInspector",
- "onView:amicode.runInspector",
- "onView:amicode.vault",
- "onStartupFinished"
- ],
- "main": "./dist/extension.js",
- "contributes": {
- "viewsContainers": {
- "activitybar": [
- {
- "id": "amicode",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ],
- "panel": [
- {
- "id": "amicode-panel",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ]
- },
- "views": {
- "amicode": [
- { "id": "amicode.vault", "name": "Vault", "type": "tree" },
- { "id": "amicode.catalog", "name": "Catalog", "type": "tree" },
- { "id": "amicode.armonia", "name": "Armonia", "type": "tree" }
- ],
- "amicode-panel": [
- { "id": "amicode.runInspector", "name": "Run Inspector", "type": "webview" }
- ]
- },
- "commands": [
- { "command": "amicode.openChat", "title": "Amicode: Open Chat" },
- { "command": "amicode.openInspector", "title": "Amicode: Open Run Inspector" },
- { "command": "amicode.restartServer", "title": "Amicode: Restart opencode server" }
- ],
- "configuration": {
- "title": "Amicode",
- "properties": {
- "amicode.opencodeBinary": {
- "type": "string",
- "default": "opencode",
- "description": "Path or command name for the opencode CLI."
- },
- "amicode.juliaProject": {
- "type": "string",
- "default": "/tmp/amicode-spike-julia",
- "description": "Julia project root (--project=...) the run_julia tool will use."
- },
- "amicode.juliaScript": {
- "type": "string",
- "default": "",
- "description": "Absolute path to spike_solve.jl. If empty, looks up via the extensionPath/../amicode/julia/spike_solve.jl convention."
- }
- }
- }
- },
  "scripts": {
- "build":  "node esbuild.config.mjs",
- "watch":  "node esbuild.config.mjs --watch",
- "typecheck": "tsc --noEmit"
+ "build": "pnpm -r run build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test"
  },
- "devDependencies": {
- "@types/node": "^22.0.0",
- "@types/vscode": "^1.95.0",
- "esbuild": "^0.24.0",
- "typescript": "^5.6.0"
- }
+ "packageManager": "pnpm@9.15.9"
 }
diff --git a/packages/amico-run/esbuild.config.mjs b/packages/amico-run/esbuild.config.mjs
@@ -0,0 +1,17 @@
+import { build } from 'esbuild'
+import { chmodSync } from 'node:fs'
+
+await build({
+ entryPoints: ['src/cli.ts'],
+ bundle: true,
+ platform: 'node',
+ target: 'node20',
+ // ESM, not CJS: the package is "type": "module", so node executes dist/amico-run.js
+ // as ESM — a CJS bundle would die on `require is not defined in ES module scope`.
+ format: 'esm',
+ outfile: 'dist/amico-run.js',
+ banner: { js: '#!/usr/bin/env node' },
+ sourcemap: true,
+ logLevel: 'info',
+})
+chmodSync('dist/amico-run.js', 0o755)
diff --git a/packages/amico-run/launcher/amico-run b/packages/amico-run/launcher/amico-run
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Thin launcher: resolve node, exec the bundled orchestrator. No logic lives here.
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve symlink chains (node_modules/.bin)
+ DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+ SOURCE="$(readlink "$SOURCE")"
+ [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+if ! command -v node >/dev/null 2>&1; then
+ echo "amico-run: node >= 20 not found on PATH (install node or fix PATH; see provisioning runbook)" >&2
+ exit 64
+fi
+exec node "$DIR/../dist/amico-run.js" "$@"
diff --git a/packages/amico-run/package.json b/packages/amico-run/package.json
@@ -0,0 +1,23 @@
+{
+ "name": "@amicode/amico-run",
+ "version": "0.1.0",
+ "license": "Apache-2.0",
+ "type": "module",
+ "main": "./src/index.ts",
+ "types": "./src/index.ts",
+ "bin": { "amico-run": "./launcher/amico-run" },
+ "engines": { "node": ">=20" },
+ "scripts": {
+ "build": "node esbuild.config.mjs",
+ "typecheck": "tsc --noEmit",
+ "test": "vitest run --passWithNoTests --exclude '**/slow/**'",
+ "test:slow": "vitest run test/slow"
+ },
+ "devDependencies": {
+ "@types/node": "^22.0.0",
+ "esbuild": "^0.24.0",
+ "smol-toml": "^1.3.0",
+ "typescript": "^5.6.0",
+ "vitest": "^2.1.0"
+ }
+}
diff --git a/packages/amico-run/src/cli.ts b/packages/amico-run/src/cli.ts
@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { LocalExecutor } from './local_executor.js'
+import { ConfigError, type Finished, type SubmitOpts } from './types.js'
+
+const USAGE = `usage: amico-run <script.jl> [--executor local] [--lab <id-or-path>]
+ [--runs-root <path>] [--julia <path>] [--project <path>] [--sysimage <path>]`
+
+export async function main(argv: string[]): Promise<number> {
+ let script: string | undefined
+ let executor = 'local'
+ const opts: SubmitOpts = { julia: {} }
+
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i]
+ const next = (): string => {
+ const v = argv[++i]
+ if (v === undefined) throw new ConfigError(`flag ${a} requires a value`)
+ return v
+ }
+ try {
+ switch (a) {
+ case '--help': case '-h': console.log(USAGE); return 0
+ case '--executor': executor = next(); break
+ case '--lab': opts.lab = next(); break
+ case '--runs-root': opts.runsRoot = next(); break
+ case '--julia': opts.julia!.julia = next(); break
+ case '--project': opts.julia!.project = next(); break
+ case '--sysimage': opts.julia!.sysimage = next(); break
+ default:
+ if (a.startsWith('-')) { console.error(`amico-run: unknown flag ${a}\n${USAGE}`); return 64 }
+ if (script) { console.error(`amico-run: multiple scripts given`); return 64 }
+ script = a
+ }
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+ }
+ if (!script) { console.error(`amico-run: no script given\n${USAGE}`); return 64 }
+ if (executor !== 'local') { console.error(`amico-run: only --executor local is supported in β`); return 64 }
+
+ let handle
+ try {
+ handle = await new LocalExecutor().submit(script, opts)
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+
+ const onSignal = (): void => { void handle.abort() }
+ process.on('SIGINT', onSignal)
+ process.on('SIGTERM', onSignal)
+
+ let fin: Finished | undefined
+ for await (const ev of handle.events) {
+ if (ev.kind === 'iter' || ev.kind === 'done') console.log(ev.raw)
+ else if (ev.kind === 'log') console.log(ev.line)
+ else fin = { status: ev.status, exitCode: ev.exitCode }
+ }
+ const f = fin ?? await handle.finished
+
+ // FINISHED-write failure lane (spec §6 last row): verdict file must exist on disk
+ if (!existsSync(join(handle.runDir, 'FINISHED'))) {
+ console.error(`amico-run: FINISHED missing in ${handle.runDir} (write fault)`)
+ return 64
+ }
+ // stdout protocol line — camelCase by design (spec §4)
+ console.log(`AMICODE_FINISHED status=${f.status} exitCode=${f.exitCode} runDir=${handle.runDir}`)
+ if (f.status === 'aborted') return 130
+ if (f.status === 'completed') return 0
+ return f.exitCode === 0 ? 1 : f.exitCode
+}
+
+main(process.argv.slice(2)).then(
+ c => { process.exitCode = c },
+ e => {
+ // Any unexpected throw is an orchestrator fault, not a solve failure → 64.
+ console.error(`amico-run: unexpected error: ${e instanceof Error ? e.stack ?? e.message : e}`)
+ process.exitCode = 64
+ },
+)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,16 @@
+name: ci
+on:
+ push: { branches: [main] }
+ pull_request:
+jobs:
+ fast:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: pnpm/action-setup@v4 # version pinned by packageManager in package.json
+ - uses: actions/setup-node@v4
+ with: { node-version: 20, cache: pnpm }
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm -r run build
+ - run: pnpm -r run typecheck
+ - run: pnpm --filter @amicode/amico-run test # includes the S31 grep-rule test
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -5,8 +5,8 @@
  "name": "Run Extension (amicode-v2)",
  "type": "extensionHost",
  "request": "launch",
- "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
- "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+ "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/extension"],
+ "outFiles": ["${workspaceFolder}/packages/extension/dist/**/*.js"]
  }
  ]
 }
diff --git a/bin/amico-run b/bin/amico-run
diff --git a/package.json b/package.json
@@ -1,85 +1,10 @@
 {
- "name": "amicode-v2",
- "displayName": "Amicode v2",
- "description": "Amico research IDE — opencode-backed chat + native VS Code surfaces for vault, catalog, and live solve inspection.",
- "version": "0.0.1",
- "publisher": "harmoniqs",
- "license": "Apache-2.0",
+ "name": "amicode-workspace",
  "private": true,
- "engines": {
- "vscode": "^1.95.0"
- },
- "categories": ["Other"],
- "activationEvents": [
- "onCommand:amicode.openChat",
- "onCommand:amicode.openInspector",
- "onView:amicode.runInspector",
- "onView:amicode.vault",
- "onStartupFinished"
- ],
- "main": "./dist/extension.js",
- "contributes": {
- "viewsContainers": {
- "activitybar": [
- {
- "id": "amicode",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ],
- "panel": [
- {
- "id": "amicode-panel",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ]
- },
- "views": {
- "amicode": [
- { "id": "amicode.vault", "name": "Vault", "type": "tree" },
- { "id": "amicode.catalog", "name": "Catalog", "type": "tree" },
- { "id": "amicode.armonia", "name": "Armonia", "type": "tree" }
- ],
- "amicode-panel": [
- { "id": "amicode.runInspector", "name": "Run Inspector", "type": "webview" }
- ]
- },
- "commands": [
- { "command": "amicode.openChat", "title": "Amicode: Open Chat" },
- { "command": "amicode.openInspector", "title": "Amicode: Open Run Inspector" },
- { "command": "amicode.restartServer", "title": "Amicode: Restart opencode server" }
- ],
- "configuration": {
- "title": "Amicode",
- "properties": {
- "amicode.opencodeBinary": {
- "type": "string",
- "default": "opencode",
- "description": "Path or command name for the opencode CLI."
- },
- "amicode.juliaProject": {
- "type": "string",
- "default": "/tmp/amicode-spike-julia",
- "description": "Julia project root (--project=...) the run_julia tool will use."
- },
- "amicode.juliaScript": {
- "type": "string",
- "default": "",
- "description": "Absolute path to spike_solve.jl. If empty, looks up via the extensionPath/../amicode/julia/spike_solve.jl convention."
- }
- }
- }
- },
  "scripts": {
- "build":  "node esbuild.config.mjs",
- "watch":  "node esbuild.config.mjs --watch",
- "typecheck": "tsc --noEmit"
+ "build": "pnpm -r run build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test"
  },
- "devDependencies": {
- "@types/node": "^22.0.0",
- "@types/vscode": "^1.95.0",
- "esbuild": "^0.24.0",
- "typescript": "^5.6.0"
- }
+ "packageManager": "pnpm@9.15.9"
 }
diff --git a/packages/amico-run/esbuild.config.mjs b/packages/amico-run/esbuild.config.mjs
@@ -0,0 +1,17 @@
+import { build } from 'esbuild'
+import { chmodSync } from 'node:fs'
+
+await build({
+ entryPoints: ['src/cli.ts'],
+ bundle: true,
+ platform: 'node',
+ target: 'node20',
+ // ESM, not CJS: the package is "type": "module", so node executes dist/amico-run.js
+ // as ESM — a CJS bundle would die on `require is not defined in ES module scope`.
+ format: 'esm',
+ outfile: 'dist/amico-run.js',
+ banner: { js: '#!/usr/bin/env node' },
+ sourcemap: true,
+ logLevel: 'info',
+})
+chmodSync('dist/amico-run.js', 0o755)
diff --git a/packages/amico-run/launcher/amico-run b/packages/amico-run/launcher/amico-run
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Thin launcher: resolve node, exec the bundled orchestrator. No logic lives here.
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve symlink chains (node_modules/.bin)
+ DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+ SOURCE="$(readlink "$SOURCE")"
+ [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+if ! command -v node >/dev/null 2>&1; then
+ echo "amico-run: node >= 20 not found on PATH (install node or fix PATH; see provisioning runbook)" >&2
+ exit 64
+fi
+exec node "$DIR/../dist/amico-run.js" "$@"
diff --git a/packages/amico-run/package.json b/packages/amico-run/package.json
@@ -0,0 +1,23 @@
+{
+ "name": "@amicode/amico-run",
+ "version": "0.1.0",
+ "license": "Apache-2.0",
+ "type": "module",
+ "main": "./src/index.ts",
+ "types": "./src/index.ts",
+ "bin": { "amico-run": "./launcher/amico-run" },
+ "engines": { "node": ">=20" },
+ "scripts": {
+ "build": "node esbuild.config.mjs",
+ "typecheck": "tsc --noEmit",
+ "test": "vitest run --passWithNoTests --exclude '**/slow/**'",
+ "test:slow": "vitest run test/slow"
+ },
+ "devDependencies": {
+ "@types/node": "^22.0.0",
+ "esbuild": "^0.24.0",
+ "smol-toml": "^1.3.0",
+ "typescript": "^5.6.0",
+ "vitest": "^2.1.0"
+ }
+}
diff --git a/packages/amico-run/src/cli.ts b/packages/amico-run/src/cli.ts
@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { LocalExecutor } from './local_executor.js'
+import { ConfigError, type Finished, type SubmitOpts } from './types.js'
+
+const USAGE = `usage: amico-run <script.jl> [--executor local] [--lab <id-or-path>]
+ [--runs-root <path>] [--julia <path>] [--project <path>] [--sysimage <path>]`
+
+export async function main(argv: string[]): Promise<number> {
+ let script: string | undefined
+ let executor = 'local'
+ const opts: SubmitOpts = { julia: {} }
+
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i]
+ const next = (): string => {
+ const v = argv[++i]
+ if (v === undefined) throw new ConfigError(`flag ${a} requires a value`)
+ return v
+ }
+ try {
+ switch (a) {
+ case '--help': case '-h': console.log(USAGE); return 0
+ case '--executor': executor = next(); break
+ case '--lab': opts.lab = next(); break
+ case '--runs-root': opts.runsRoot = next(); break
+ case '--julia': opts.julia!.julia = next(); break
+ case '--project': opts.julia!.project = next(); break
+ case '--sysimage': opts.julia!.sysimage = next(); break
+ default:
+ if (a.startsWith('-')) { console.error(`amico-run: unknown flag ${a}\n${USAGE}`); return 64 }
+ if (script) { console.error(`amico-run: multiple scripts given`); return 64 }
+ script = a
+ }
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+ }
+ if (!script) { console.error(`amico-run: no script given\n${USAGE}`); return 64 }
+ if (executor !== 'local') { console.error(`amico-run: only --executor local is supported in β`); return 64 }
+
+ let handle
+ try {
+ handle = await new LocalExecutor().submit(script, opts)
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+
+ const onSignal = (): void => { void handle.abort() }
+ process.on('SIGINT', onSignal)
+ process.on('SIGTERM', onSignal)
+
+ let fin: Finished | undefined
+ for await (const ev of handle.events) {
+ if (ev.kind === 'iter' || ev.kind === 'done') console.log(ev.raw)
+ else if (ev.kind === 'log') console.log(ev.line)
+ else fin = { status: ev.status, exitCode: ev.exitCode }
+ }
+ const f = fin ?? await handle.finished
+
+ // FINISHED-write failure lane (spec §6 last row): verdict file must exist on disk
+ if (!existsSync(join(handle.runDir, 'FINISHED'))) {
+ console.error(`amico-run: FINISHED missing in ${handle.runDir} (write fault)`)
+ return 64
+ }
+ // stdout protocol line — camelCase by design (spec §4)
+ console.log(`AMICODE_FINISHED status=${f.status} exitCode=${f.exitCode} runDir=${handle.runDir}`)
+ if (f.status === 'aborted') return 130
+ if (f.status === 'completed') return 0
+ return f.exitCode === 0 ? 1 : f.exitCode
+}
+
+main(process.argv.slice(2)).then(
+ c => { process.exitCode = c },
+ e => {
+ // Any unexpected throw is an orchestrator fault, not a solve failure → 64.
+ console.error(`amico-run: unexpected error: ${e instanceof Error ? e.stack ?? e.message : e}`)
+ process.exitCode = 64
+ },
+)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,16 @@
+name: ci
+on:
+ push: { branches: [main] }
+ pull_request:
+jobs:
+ fast:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: pnpm/action-setup@v4 # version pinned by packageManager in package.json
+ - uses: actions/setup-node@v4
+ with: { node-version: 20, cache: pnpm }
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm -r run build
+ - run: pnpm -r run typecheck
+ - run: pnpm --filter @amicode/amico-run test # includes the S31 grep-rule test
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -5,8 +5,8 @@
  "name": "Run Extension (amicode-v2)",
  "type": "extensionHost",
  "request": "launch",
- "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
- "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+ "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/extension"],
+ "outFiles": ["${workspaceFolder}/packages/extension/dist/**/*.js"]
  }
  ]
 }
diff --git a/bin/amico-run b/bin/amico-run
diff --git a/package.json b/package.json
@@ -1,85 +1,10 @@
 {
- "name": "amicode-v2",
- "displayName": "Amicode v2",
- "description": "Amico research IDE — opencode-backed chat + native VS Code surfaces for vault, catalog, and live solve inspection.",
- "version": "0.0.1",
- "publisher": "harmoniqs",
- "license": "Apache-2.0",
+ "name": "amicode-workspace",
  "private": true,
- "engines": {
- "vscode": "^1.95.0"
- },
- "categories": ["Other"],
- "activationEvents": [
- "onCommand:amicode.openChat",
- "onCommand:amicode.openInspector",
- "onView:amicode.runInspector",
- "onView:amicode.vault",
- "onStartupFinished"
- ],
- "main": "./dist/extension.js",
- "contributes": {
- "viewsContainers": {
- "activitybar": [
- {
- "id": "amicode",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ],
- "panel": [
- {
- "id": "amicode-panel",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ]
- },
- "views": {
- "amicode": [
- { "id": "amicode.vault", "name": "Vault", "type": "tree" },
- { "id": "amicode.catalog", "name": "Catalog", "type": "tree" },
- { "id": "amicode.armonia", "name": "Armonia", "type": "tree" }
- ],
- "amicode-panel": [
- { "id": "amicode.runInspector", "name": "Run Inspector", "type": "webview" }
- ]
- },
- "commands": [
- { "command": "amicode.openChat", "title": "Amicode: Open Chat" },
- { "command": "amicode.openInspector", "title": "Amicode: Open Run Inspector" },
- { "command": "amicode.restartServer", "title": "Amicode: Restart opencode server" }
- ],
- "configuration": {
- "title": "Amicode",
- "properties": {
- "amicode.opencodeBinary": {
- "type": "string",
- "default": "opencode",
- "description": "Path or command name for the opencode CLI."
- },
- "amicode.juliaProject": {
- "type": "string",
- "default": "/tmp/amicode-spike-julia",
- "description": "Julia project root (--project=...) the run_julia tool will use."
- },
- "amicode.juliaScript": {
- "type": "string",
- "default": "",
- "description": "Absolute path to spike_solve.jl. If empty, looks up via the extensionPath/../amicode/julia/spike_solve.jl convention."
- }
- }
- }
- },
  "scripts": {
- "build":  "node esbuild.config.mjs",
- "watch":  "node esbuild.config.mjs --watch",
- "typecheck": "tsc --noEmit"
+ "build": "pnpm -r run build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test"
  },
- "devDependencies": {
- "@types/node": "^22.0.0",
- "@types/vscode": "^1.95.0",
- "esbuild": "^0.24.0",
- "typescript": "^5.6.0"
- }
+ "packageManager": "pnpm@9.15.9"
 }
diff --git a/packages/amico-run/esbuild.config.mjs b/packages/amico-run/esbuild.config.mjs
@@ -0,0 +1,17 @@
+import { build } from 'esbuild'
+import { chmodSync } from 'node:fs'
+
+await build({
+ entryPoints: ['src/cli.ts'],
+ bundle: true,
+ platform: 'node',
+ target: 'node20',
+ // ESM, not CJS: the package is "type": "module", so node executes dist/amico-run.js
+ // as ESM — a CJS bundle would die on `require is not defined in ES module scope`.
+ format: 'esm',
+ outfile: 'dist/amico-run.js',
+ banner: { js: '#!/usr/bin/env node' },
+ sourcemap: true,
+ logLevel: 'info',
+})
+chmodSync('dist/amico-run.js', 0o755)
diff --git a/packages/amico-run/launcher/amico-run b/packages/amico-run/launcher/amico-run
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Thin launcher: resolve node, exec the bundled orchestrator. No logic lives here.
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve symlink chains (node_modules/.bin)
+ DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+ SOURCE="$(readlink "$SOURCE")"
+ [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+if ! command -v node >/dev/null 2>&1; then
+ echo "amico-run: node >= 20 not found on PATH (install node or fix PATH; see provisioning runbook)" >&2
+ exit 64
+fi
+exec node "$DIR/../dist/amico-run.js" "$@"
diff --git a/packages/amico-run/package.json b/packages/amico-run/package.json
@@ -0,0 +1,23 @@
+{
+ "name": "@amicode/amico-run",
+ "version": "0.1.0",
+ "license": "Apache-2.0",
+ "type": "module",
+ "main": "./src/index.ts",
+ "types": "./src/index.ts",
+ "bin": { "amico-run": "./launcher/amico-run" },
+ "engines": { "node": ">=20" },
+ "scripts": {
+ "build": "node esbuild.config.mjs",
+ "typecheck": "tsc --noEmit",
+ "test": "vitest run --passWithNoTests --exclude '**/slow/**'",
+ "test:slow": "vitest run test/slow"
+ },
+ "devDependencies": {
+ "@types/node": "^22.0.0",
+ "esbuild": "^0.24.0",
+ "smol-toml": "^1.3.0",
+ "typescript": "^5.6.0",
+ "vitest": "^2.1.0"
+ }
+}
diff --git a/packages/amico-run/src/cli.ts b/packages/amico-run/src/cli.ts
@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { LocalExecutor } from './local_executor.js'
+import { ConfigError, type Finished, type SubmitOpts } from './types.js'
+
+const USAGE = `usage: amico-run <script.jl> [--executor local] [--lab <id-or-path>]
+ [--runs-root <path>] [--julia <path>] [--project <path>] [--sysimage <path>]`
+
+export async function main(argv: string[]): Promise<number> {
+ let script: string | undefined
+ let executor = 'local'
+ const opts: SubmitOpts = { julia: {} }
+
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i]
+ const next = (): string => {
+ const v = argv[++i]
+ if (v === undefined) throw new ConfigError(`flag ${a} requires a value`)
+ return v
+ }
+ try {
+ switch (a) {
+ case '--help': case '-h': console.log(USAGE); return 0
+ case '--executor': executor = next(); break
+ case '--lab': opts.lab = next(); break
+ case '--runs-root': opts.runsRoot = next(); break
+ case '--julia': opts.julia!.julia = next(); break
+ case '--project': opts.julia!.project = next(); break
+ case '--sysimage': opts.julia!.sysimage = next(); break
+ default:
+ if (a.startsWith('-')) { console.error(`amico-run: unknown flag ${a}\n${USAGE}`); return 64 }
+ if (script) { console.error(`amico-run: multiple scripts given`); return 64 }
+ script = a
+ }
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+ }
+ if (!script) { console.error(`amico-run: no script given\n${USAGE}`); return 64 }
+ if (executor !== 'local') { console.error(`amico-run: only --executor local is supported in β`); return 64 }
+
+ let handle
+ try {
+ handle = await new LocalExecutor().submit(script, opts)
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+
+ const onSignal = (): void => { void handle.abort() }
+ process.on('SIGINT', onSignal)
+ process.on('SIGTERM', onSignal)
+
+ let fin: Finished | undefined
+ for await (const ev of handle.events) {
+ if (ev.kind === 'iter' || ev.kind === 'done') console.log(ev.raw)
+ else if (ev.kind === 'log') console.log(ev.line)
+ else fin = { status: ev.status, exitCode: ev.exitCode }
+ }
+ const f = fin ?? await handle.finished
+
+ // FINISHED-write failure lane (spec §6 last row): verdict file must exist on disk
+ if (!existsSync(join(handle.runDir, 'FINISHED'))) {
+ console.error(`amico-run: FINISHED missing in ${handle.runDir} (write fault)`)
+ return 64
+ }
+ // stdout protocol line — camelCase by design (spec §4)
+ console.log(`AMICODE_FINISHED status=${f.status} exitCode=${f.exitCode} runDir=${handle.runDir}`)
+ if (f.status === 'aborted') return 130
+ if (f.status === 'completed') return 0
+ return f.exitCode === 0 ? 1 : f.exitCode
+}
+
+main(process.argv.slice(2)).then(
+ c => { process.exitCode = c },
+ e => {
+ // Any unexpected throw is an orchestrator fault, not a solve failure → 64.
+ console.error(`amico-run: unexpected error: ${e instanceof Error ? e.stack ?? e.message : e}`)
+ process.exitCode = 64
+ },
+)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,16 @@
+name: ci
+on:
+ push: { branches: [main] }
+ pull_request:
+jobs:
+ fast:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: pnpm/action-setup@v4 # version pinned by packageManager in package.json
+ - uses: actions/setup-node@v4
+ with: { node-version: 20, cache: pnpm }
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm -r run build
+ - run: pnpm -r run typecheck
+ - run: pnpm --filter @amicode/amico-run test # includes the S31 grep-rule test
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -5,8 +5,8 @@
  "name": "Run Extension (amicode-v2)",
  "type": "extensionHost",
  "request": "launch",
- "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
- "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+ "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/extension"],
+ "outFiles": ["${workspaceFolder}/packages/extension/dist/**/*.js"]
  }
  ]
 }
diff --git a/bin/amico-run b/bin/amico-run
diff --git a/package.json b/package.json
@@ -1,85 +1,10 @@
 {
- "name": "amicode-v2",
- "displayName": "Amicode v2",
- "description": "Amico research IDE — opencode-backed chat + native VS Code surfaces for vault, catalog, and live solve inspection.",
- "version": "0.0.1",
- "publisher": "harmoniqs",
- "license": "Apache-2.0",
+ "name": "amicode-workspace",
  "private": true,
- "engines": {
- "vscode": "^1.95.0"
- },
- "categories": ["Other"],
- "activationEvents": [
- "onCommand:amicode.openChat",
- "onCommand:amicode.openInspector",
- "onView:amicode.runInspector",
- "onView:amicode.vault",
- "onStartupFinished"
- ],
- "main": "./dist/extension.js",
- "contributes": {
- "viewsContainers": {
- "activitybar": [
- {
- "id": "amicode",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ],
- "panel": [
- {
- "id": "amicode-panel",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ]
- },
- "views": {
- "amicode": [
- { "id": "amicode.vault", "name": "Vault", "type": "tree" },
- { "id": "amicode.catalog", "name": "Catalog", "type": "tree" },
- { "id": "amicode.armonia", "name": "Armonia", "type": "tree" }
- ],
- "amicode-panel": [
- { "id": "amicode.runInspector", "name": "Run Inspector", "type": "webview" }
- ]
- },
- "commands": [
- { "command": "amicode.openChat", "title": "Amicode: Open Chat" },
- { "command": "amicode.openInspector", "title": "Amicode: Open Run Inspector" },
- { "command": "amicode.restartServer", "title": "Amicode: Restart opencode server" }
- ],
- "configuration": {
- "title": "Amicode",
- "properties": {
- "amicode.opencodeBinary": {
- "type": "string",
- "default": "opencode",
- "description": "Path or command name for the opencode CLI."
- },
- "amicode.juliaProject": {
- "type": "string",
- "default": "/tmp/amicode-spike-julia",
- "description": "Julia project root (--project=...) the run_julia tool will use."
- },
- "amicode.juliaScript": {
- "type": "string",
- "default": "",
- "description": "Absolute path to spike_solve.jl. If empty, looks up via the extensionPath/../amicode/julia/spike_solve.jl convention."
- }
- }
- }
- },
  "scripts": {
- "build":  "node esbuild.config.mjs",
- "watch":  "node esbuild.config.mjs --watch",
- "typecheck": "tsc --noEmit"
+ "build": "pnpm -r run build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test"
  },
- "devDependencies": {
- "@types/node": "^22.0.0",
- "@types/vscode": "^1.95.0",
- "esbuild": "^0.24.0",
- "typescript": "^5.6.0"
- }
+ "packageManager": "pnpm@9.15.9"
 }
diff --git a/packages/amico-run/esbuild.config.mjs b/packages/amico-run/esbuild.config.mjs
@@ -0,0 +1,17 @@
+import { build } from 'esbuild'
+import { chmodSync } from 'node:fs'
+
+await build({
+ entryPoints: ['src/cli.ts'],
+ bundle: true,
+ platform: 'node',
+ target: 'node20',
+ // ESM, not CJS: the package is "type": "module", so node executes dist/amico-run.js
+ // as ESM — a CJS bundle would die on `require is not defined in ES module scope`.
+ format: 'esm',
+ outfile: 'dist/amico-run.js',
+ banner: { js: '#!/usr/bin/env node' },
+ sourcemap: true,
+ logLevel: 'info',
+})
+chmodSync('dist/amico-run.js', 0o755)
diff --git a/packages/amico-run/launcher/amico-run b/packages/amico-run/launcher/amico-run
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Thin launcher: resolve node, exec the bundled orchestrator. No logic lives here.
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve symlink chains (node_modules/.bin)
+ DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+ SOURCE="$(readlink "$SOURCE")"
+ [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+if ! command -v node >/dev/null 2>&1; then
+ echo "amico-run: node >= 20 not found on PATH (install node or fix PATH; see provisioning runbook)" >&2
+ exit 64
+fi
+exec node "$DIR/../dist/amico-run.js" "$@"
diff --git a/packages/amico-run/package.json b/packages/amico-run/package.json
@@ -0,0 +1,23 @@
+{
+ "name": "@amicode/amico-run",
+ "version": "0.1.0",
+ "license": "Apache-2.0",
+ "type": "module",
+ "main": "./src/index.ts",
+ "types": "./src/index.ts",
+ "bin": { "amico-run": "./launcher/amico-run" },
+ "engines": { "node": ">=20" },
+ "scripts": {
+ "build": "node esbuild.config.mjs",
+ "typecheck": "tsc --noEmit",
+ "test": "vitest run --passWithNoTests --exclude '**/slow/**'",
+ "test:slow": "vitest run test/slow"
+ },
+ "devDependencies": {
+ "@types/node": "^22.0.0",
+ "esbuild": "^0.24.0",
+ "smol-toml": "^1.3.0",
+ "typescript": "^5.6.0",
+ "vitest": "^2.1.0"
+ }
+}
diff --git a/packages/amico-run/src/cli.ts b/packages/amico-run/src/cli.ts
@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { LocalExecutor } from './local_executor.js'
+import { ConfigError, type Finished, type SubmitOpts } from './types.js'
+
+const USAGE = `usage: amico-run <script.jl> [--executor local] [--lab <id-or-path>]
+ [--runs-root <path>] [--julia <path>] [--project <path>] [--sysimage <path>]`
+
+export async function main(argv: string[]): Promise<number> {
+ let script: string | undefined
+ let executor = 'local'
+ const opts: SubmitOpts = { julia: {} }
+
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i]
+ const next = (): string => {
+ const v = argv[++i]
+ if (v === undefined) throw new ConfigError(`flag ${a} requires a value`)
+ return v
+ }
+ try {
+ switch (a) {
+ case '--help': case '-h': console.log(USAGE); return 0
+ case '--executor': executor = next(); break
+ case '--lab': opts.lab = next(); break
+ case '--runs-root': opts.runsRoot = next(); break
+ case '--julia': opts.julia!.julia = next(); break
+ case '--project': opts.julia!.project = next(); break
+ case '--sysimage': opts.julia!.sysimage = next(); break
+ default:
+ if (a.startsWith('-')) { console.error(`amico-run: unknown flag ${a}\n${USAGE}`); return 64 }
+ if (script) { console.error(`amico-run: multiple scripts given`); return 64 }
+ script = a
+ }
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+ }
+ if (!script) { console.error(`amico-run: no script given\n${USAGE}`); return 64 }
+ if (executor !== 'local') { console.error(`amico-run: only --executor local is supported in β`); return 64 }
+
+ let handle
+ try {
+ handle = await new LocalExecutor().submit(script, opts)
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+
+ const onSignal = (): void => { void handle.abort() }
+ process.on('SIGINT', onSignal)
+ process.on('SIGTERM', onSignal)
+
+ let fin: Finished | undefined
+ for await (const ev of handle.events) {
+ if (ev.kind === 'iter' || ev.kind === 'done') console.log(ev.raw)
+ else if (ev.kind === 'log') console.log(ev.line)
+ else fin = { status: ev.status, exitCode: ev.exitCode }
+ }
+ const f = fin ?? await handle.finished
+
+ // FINISHED-write failure lane (spec §6 last row): verdict file must exist on disk
+ if (!existsSync(join(handle.runDir, 'FINISHED'))) {
+ console.error(`amico-run: FINISHED missing in ${handle.runDir} (write fault)`)
+ return 64
+ }
+ // stdout protocol line — camelCase by design (spec §4)
+ console.log(`AMICODE_FINISHED status=${f.status} exitCode=${f.exitCode} runDir=${handle.runDir}`)
+ if (f.status === 'aborted') return 130
+ if (f.status === 'completed') return 0
+ return f.exitCode === 0 ? 1 : f.exitCode
+}
+
+main(process.argv.slice(2)).then(
+ c => { process.exitCode = c },
+ e => {
+ // Any unexpected throw is an orchestrator fault, not a solve failure → 64.
+ console.error(`amico-run: unexpected error: ${e instanceof Error ? e.stack ?? e.message : e}`)
+ process.exitCode = 64
+ },
+)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,16 @@
+name: ci
+on:
+ push: { branches: [main] }
+ pull_request:
+jobs:
+ fast:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: pnpm/action-setup@v4 # version pinned by packageManager in package.json
+ - uses: actions/setup-node@v4
+ with: { node-version: 20, cache: pnpm }
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm -r run build
+ - run: pnpm -r run typecheck
+ - run: pnpm --filter @amicode/amico-run test # includes the S31 grep-rule test
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -5,8 +5,8 @@
  "name": "Run Extension (amicode-v2)",
  "type": "extensionHost",
  "request": "launch",
- "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
- "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+ "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/extension"],
+ "outFiles": ["${workspaceFolder}/packages/extension/dist/**/*.js"]
  }
  ]
 }
diff --git a/bin/amico-run b/bin/amico-run
diff --git a/package.json b/package.json
@@ -1,85 +1,10 @@
 {
- "name": "amicode-v2",
- "displayName": "Amicode v2",
- "description": "Amico research IDE — opencode-backed chat + native VS Code surfaces for vault, catalog, and live solve inspection.",
- "version": "0.0.1",
- "publisher": "harmoniqs",
- "license": "Apache-2.0",
+ "name": "amicode-workspace",
  "private": true,
- "engines": {
- "vscode": "^1.95.0"
- },
- "categories": ["Other"],
- "activationEvents": [
- "onCommand:amicode.openChat",
- "onCommand:amicode.openInspector",
- "onView:amicode.runInspector",
- "onView:amicode.vault",
- "onStartupFinished"
- ],
- "main": "./dist/extension.js",
- "contributes": {
- "viewsContainers": {
- "activitybar": [
- {
- "id": "amicode",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ],
- "panel": [
- {
- "id": "amicode-panel",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ]
- },
- "views": {
- "amicode": [
- { "id": "amicode.vault", "name": "Vault", "type": "tree" },
- { "id": "amicode.catalog", "name": "Catalog", "type": "tree" },
- { "id": "amicode.armonia", "name": "Armonia", "type": "tree" }
- ],
- "amicode-panel": [
- { "id": "amicode.runInspector", "name": "Run Inspector", "type": "webview" }
- ]
- },
- "commands": [
- { "command": "amicode.openChat", "title": "Amicode: Open Chat" },
- { "command": "amicode.openInspector", "title": "Amicode: Open Run Inspector" },
- { "command": "amicode.restartServer", "title": "Amicode: Restart opencode server" }
- ],
- "configuration": {
- "title": "Amicode",
- "properties": {
- "amicode.opencodeBinary": {
- "type": "string",
- "default": "opencode",
- "description": "Path or command name for the opencode CLI."
- },
- "amicode.juliaProject": {
- "type": "string",
- "default": "/tmp/amicode-spike-julia",
- "description": "Julia project root (--project=...) the run_julia tool will use."
- },
- "amicode.juliaScript": {
- "type": "string",
- "default": "",
- "description": "Absolute path to spike_solve.jl. If empty, looks up via the extensionPath/../amicode/julia/spike_solve.jl convention."
- }
- }
- }
- },
  "scripts": {
- "build":  "node esbuild.config.mjs",
- "watch":  "node esbuild.config.mjs --watch",
- "typecheck": "tsc --noEmit"
+ "build": "pnpm -r run build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test"
  },
- "devDependencies": {
- "@types/node": "^22.0.0",
- "@types/vscode": "^1.95.0",
- "esbuild": "^0.24.0",
- "typescript": "^5.6.0"
- }
+ "packageManager": "pnpm@9.15.9"
 }
diff --git a/packages/amico-run/esbuild.config.mjs b/packages/amico-run/esbuild.config.mjs
@@ -0,0 +1,17 @@
+import { build } from 'esbuild'
+import { chmodSync } from 'node:fs'
+
+await build({
+ entryPoints: ['src/cli.ts'],
+ bundle: true,
+ platform: 'node',
+ target: 'node20',
+ // ESM, not CJS: the package is "type": "module", so node executes dist/amico-run.js
+ // as ESM — a CJS bundle would die on `require is not defined in ES module scope`.
+ format: 'esm',
+ outfile: 'dist/amico-run.js',
+ banner: { js: '#!/usr/bin/env node' },
+ sourcemap: true,
+ logLevel: 'info',
+})
+chmodSync('dist/amico-run.js', 0o755)
diff --git a/packages/amico-run/launcher/amico-run b/packages/amico-run/launcher/amico-run
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Thin launcher: resolve node, exec the bundled orchestrator. No logic lives here.
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve symlink chains (node_modules/.bin)
+ DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+ SOURCE="$(readlink "$SOURCE")"
+ [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+if ! command -v node >/dev/null 2>&1; then
+ echo "amico-run: node >= 20 not found on PATH (install node or fix PATH; see provisioning runbook)" >&2
+ exit 64
+fi
+exec node "$DIR/../dist/amico-run.js" "$@"
diff --git a/packages/amico-run/package.json b/packages/amico-run/package.json
@@ -0,0 +1,23 @@
+{
+ "name": "@amicode/amico-run",
+ "version": "0.1.0",
+ "license": "Apache-2.0",
+ "type": "module",
+ "main": "./src/index.ts",
+ "types": "./src/index.ts",
+ "bin": { "amico-run": "./launcher/amico-run" },
+ "engines": { "node": ">=20" },
+ "scripts": {
+ "build": "node esbuild.config.mjs",
+ "typecheck": "tsc --noEmit",
+ "test": "vitest run --passWithNoTests --exclude '**/slow/**'",
+ "test:slow": "vitest run test/slow"
+ },
+ "devDependencies": {
+ "@types/node": "^22.0.0",
+ "esbuild": "^0.24.0",
+ "smol-toml": "^1.3.0",
+ "typescript": "^5.6.0",
+ "vitest": "^2.1.0"
+ }
+}
diff --git a/packages/amico-run/src/cli.ts b/packages/amico-run/src/cli.ts
@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { LocalExecutor } from './local_executor.js'
+import { ConfigError, type Finished, type SubmitOpts } from './types.js'
+
+const USAGE = `usage: amico-run <script.jl> [--executor local] [--lab <id-or-path>]
+ [--runs-root <path>] [--julia <path>] [--project <path>] [--sysimage <path>]`
+
+export async function main(argv: string[]): Promise<number> {
+ let script: string | undefined
+ let executor = 'local'
+ const opts: SubmitOpts = { julia: {} }
+
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i]
+ const next = (): string => {
+ const v = argv[++i]
+ if (v === undefined) throw new ConfigError(`flag ${a} requires a value`)
+ return v
+ }
+ try {
+ switch (a) {
+ case '--help': case '-h': console.log(USAGE); return 0
+ case '--executor': executor = next(); break
+ case '--lab': opts.lab = next(); break
+ case '--runs-root': opts.runsRoot = next(); break
+ case '--julia': opts.julia!.julia = next(); break
+ case '--project': opts.julia!.project = next(); break
+ case '--sysimage': opts.julia!.sysimage = next(); break
+ default:
+ if (a.startsWith('-')) { console.error(`amico-run: unknown flag ${a}\n${USAGE}`); return 64 }
+ if (script) { console.error(`amico-run: multiple scripts given`); return 64 }
+ script = a
+ }
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+ }
+ if (!script) { console.error(`amico-run: no script given\n${USAGE}`); return 64 }
+ if (executor !== 'local') { console.error(`amico-run: only --executor local is supported in β`); return 64 }
+
+ let handle
+ try {
+ handle = await new LocalExecutor().submit(script, opts)
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+
+ const onSignal = (): void => { void handle.abort() }
+ process.on('SIGINT', onSignal)
+ process.on('SIGTERM', onSignal)
+
+ let fin: Finished | undefined
+ for await (const ev of handle.events) {
+ if (ev.kind === 'iter' || ev.kind === 'done') console.log(ev.raw)
+ else if (ev.kind === 'log') console.log(ev.line)
+ else fin = { status: ev.status, exitCode: ev.exitCode }
+ }
+ const f = fin ?? await handle.finished
+
+ // FINISHED-write failure lane (spec §6 last row): verdict file must exist on disk
+ if (!existsSync(join(handle.runDir, 'FINISHED'))) {
+ console.error(`amico-run: FINISHED missing in ${handle.runDir} (write fault)`)
+ return 64
+ }
+ // stdout protocol line — camelCase by design (spec §4)
+ console.log(`AMICODE_FINISHED status=${f.status} exitCode=${f.exitCode} runDir=${handle.runDir}`)
+ if (f.status === 'aborted') return 130
+ if (f.status === 'completed') return 0
+ return f.exitCode === 0 ? 1 : f.exitCode
+}
+
+main(process.argv.slice(2)).then(
+ c => { process.exitCode = c },
+ e => {
+ // Any unexpected throw is an orchestrator fault, not a solve failure → 64.
+ console.error(`amico-run: unexpected error: ${e instanceof Error ? e.stack ?? e.message : e}`)
+ process.exitCode = 64
+ },
+)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,16 @@
+name: ci
+on:
+ push: { branches: [main] }
+ pull_request:
+jobs:
+ fast:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: pnpm/action-setup@v4 # version pinned by packageManager in package.json
+ - uses: actions/setup-node@v4
+ with: { node-version: 20, cache: pnpm }
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm -r run build
+ - run: pnpm -r run typecheck
+ - run: pnpm --filter @amicode/amico-run test # includes the S31 grep-rule test
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -5,8 +5,8 @@
  "name": "Run Extension (amicode-v2)",
  "type": "extensionHost",
  "request": "launch",
- "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
- "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+ "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/extension"],
+ "outFiles": ["${workspaceFolder}/packages/extension/dist/**/*.js"]
  }
  ]
 }
diff --git a/bin/amico-run b/bin/amico-run
diff --git a/package.json b/package.json
@@ -1,85 +1,10 @@
 {
- "name": "amicode-v2",
- "displayName": "Amicode v2",
- "description": "Amico research IDE — opencode-backed chat + native VS Code surfaces for vault, catalog, and live solve inspection.",
- "version": "0.0.1",
- "publisher": "harmoniqs",
- "license": "Apache-2.0",
+ "name": "amicode-workspace",
  "private": true,
- "engines": {
- "vscode": "^1.95.0"
- },
- "categories": ["Other"],
- "activationEvents": [
- "onCommand:amicode.openChat",
- "onCommand:amicode.openInspector",
- "onView:amicode.runInspector",
- "onView:amicode.vault",
- "onStartupFinished"
- ],
- "main": "./dist/extension.js",
- "contributes": {
- "viewsContainers": {
- "activitybar": [
- {
- "id": "amicode",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ],
- "panel": [
- {
- "id": "amicode-panel",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ]
- },
- "views": {
- "amicode": [
- { "id": "amicode.vault", "name": "Vault", "type": "tree" },
- { "id": "amicode.catalog", "name": "Catalog", "type": "tree" },
- { "id": "amicode.armonia", "name": "Armonia", "type": "tree" }
- ],
- "amicode-panel": [
- { "id": "amicode.runInspector", "name": "Run Inspector", "type": "webview" }
- ]
- },
- "commands": [
- { "command": "amicode.openChat", "title": "Amicode: Open Chat" },
- { "command": "amicode.openInspector", "title": "Amicode: Open Run Inspector" },
- { "command": "amicode.restartServer", "title": "Amicode: Restart opencode server" }
- ],
- "configuration": {
- "title": "Amicode",
- "properties": {
- "amicode.opencodeBinary": {
- "type": "string",
- "default": "opencode",
- "description": "Path or command name for the opencode CLI."
- },
- "amicode.juliaProject": {
- "type": "string",
- "default": "/tmp/amicode-spike-julia",
- "description": "Julia project root (--project=...) the run_julia tool will use."
- },
- "amicode.juliaScript": {
- "type": "string",
- "default": "",
- "description": "Absolute path to spike_solve.jl. If empty, looks up via the extensionPath/../amicode/julia/spike_solve.jl convention."
- }
- }
- }
- },
  "scripts": {
- "build":  "node esbuild.config.mjs",
- "watch":  "node esbuild.config.mjs --watch",
- "typecheck": "tsc --noEmit"
+ "build": "pnpm -r run build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test"
  },
- "devDependencies": {
- "@types/node": "^22.0.0",
- "@types/vscode": "^1.95.0",
- "esbuild": "^0.24.0",
- "typescript": "^5.6.0"
- }
+ "packageManager": "pnpm@9.15.9"
 }
diff --git a/packages/amico-run/esbuild.config.mjs b/packages/amico-run/esbuild.config.mjs
@@ -0,0 +1,17 @@
+import { build } from 'esbuild'
+import { chmodSync } from 'node:fs'
+
+await build({
+ entryPoints: ['src/cli.ts'],
+ bundle: true,
+ platform: 'node',
+ target: 'node20',
+ // ESM, not CJS: the package is "type": "module", so node executes dist/amico-run.js
+ // as ESM — a CJS bundle would die on `require is not defined in ES module scope`.
+ format: 'esm',
+ outfile: 'dist/amico-run.js',
+ banner: { js: '#!/usr/bin/env node' },
+ sourcemap: true,
+ logLevel: 'info',
+})
+chmodSync('dist/amico-run.js', 0o755)
diff --git a/packages/amico-run/launcher/amico-run b/packages/amico-run/launcher/amico-run
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Thin launcher: resolve node, exec the bundled orchestrator. No logic lives here.
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve symlink chains (node_modules/.bin)
+ DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+ SOURCE="$(readlink "$SOURCE")"
+ [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+if ! command -v node >/dev/null 2>&1; then
+ echo "amico-run: node >= 20 not found on PATH (install node or fix PATH; see provisioning runbook)" >&2
+ exit 64
+fi
+exec node "$DIR/../dist/amico-run.js" "$@"
diff --git a/packages/amico-run/package.json b/packages/amico-run/package.json
@@ -0,0 +1,23 @@
+{
+ "name": "@amicode/amico-run",
+ "version": "0.1.0",
+ "license": "Apache-2.0",
+ "type": "module",
+ "main": "./src/index.ts",
+ "types": "./src/index.ts",
+ "bin": { "amico-run": "./launcher/amico-run" },
+ "engines": { "node": ">=20" },
+ "scripts": {
+ "build": "node esbuild.config.mjs",
+ "typecheck": "tsc --noEmit",
+ "test": "vitest run --passWithNoTests --exclude '**/slow/**'",
+ "test:slow": "vitest run test/slow"
+ },
+ "devDependencies": {
+ "@types/node": "^22.0.0",
+ "esbuild": "^0.24.0",
+ "smol-toml": "^1.3.0",
+ "typescript": "^5.6.0",
+ "vitest": "^2.1.0"
+ }
+}
diff --git a/packages/amico-run/src/cli.ts b/packages/amico-run/src/cli.ts
@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { LocalExecutor } from './local_executor.js'
+import { ConfigError, type Finished, type SubmitOpts } from './types.js'
+
+const USAGE = `usage: amico-run <script.jl> [--executor local] [--lab <id-or-path>]
+ [--runs-root <path>] [--julia <path>] [--project <path>] [--sysimage <path>]`
+
+export async function main(argv: string[]): Promise<number> {
+ let script: string | undefined
+ let executor = 'local'
+ const opts: SubmitOpts = { julia: {} }
+
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i]
+ const next = (): string => {
+ const v = argv[++i]
+ if (v === undefined) throw new ConfigError(`flag ${a} requires a value`)
+ return v
+ }
+ try {
+ switch (a) {
+ case '--help': case '-h': console.log(USAGE); return 0
+ case '--executor': executor = next(); break
+ case '--lab': opts.lab = next(); break
+ case '--runs-root': opts.runsRoot = next(); break
+ case '--julia': opts.julia!.julia = next(); break
+ case '--project': opts.julia!.project = next(); break
+ case '--sysimage': opts.julia!.sysimage = next(); break
+ default:
+ if (a.startsWith('-')) { console.error(`amico-run: unknown flag ${a}\n${USAGE}`); return 64 }
+ if (script) { console.error(`amico-run: multiple scripts given`); return 64 }
+ script = a
+ }
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+ }
+ if (!script) { console.error(`amico-run: no script given\n${USAGE}`); return 64 }
+ if (executor !== 'local') { console.error(`amico-run: only --executor local is supported in β`); return 64 }
+
+ let handle
+ try {
+ handle = await new LocalExecutor().submit(script, opts)
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+
+ const onSignal = (): void => { void handle.abort() }
+ process.on('SIGINT', onSignal)
+ process.on('SIGTERM', onSignal)
+
+ let fin: Finished | undefined
+ for await (const ev of handle.events) {
+ if (ev.kind === 'iter' || ev.kind === 'done') console.log(ev.raw)
+ else if (ev.kind === 'log') console.log(ev.line)
+ else fin = { status: ev.status, exitCode: ev.exitCode }
+ }
+ const f = fin ?? await handle.finished
+
+ // FINISHED-write failure lane (spec §6 last row): verdict file must exist on disk
+ if (!existsSync(join(handle.runDir, 'FINISHED'))) {
+ console.error(`amico-run: FINISHED missing in ${handle.runDir} (write fault)`)
+ return 64
+ }
+ // stdout protocol line — camelCase by design (spec §4)
+ console.log(`AMICODE_FINISHED status=${f.status} exitCode=${f.exitCode} runDir=${handle.runDir}`)
+ if (f.status === 'aborted') return 130
+ if (f.status === 'completed') return 0
+ return f.exitCode === 0 ? 1 : f.exitCode
+}
+
+main(process.argv.slice(2)).then(
+ c => { process.exitCode = c },
+ e => {
+ // Any unexpected throw is an orchestrator fault, not a solve failure → 64.
+ console.error(`amico-run: unexpected error: ${e instanceof Error ? e.stack ?? e.message : e}`)
+ process.exitCode = 64
+ },
+)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -0,0 +1,16 @@
+name: ci
+on:
+ push: { branches: [main] }
+ pull_request:
+jobs:
+ fast:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: pnpm/action-setup@v4 # version pinned by packageManager in package.json
+ - uses: actions/setup-node@v4
+ with: { node-version: 20, cache: pnpm }
+ - run: pnpm install --frozen-lockfile
+ - run: pnpm -r run build
+ - run: pnpm -r run typecheck
+ - run: pnpm --filter @amicode/amico-run test # includes the S31 grep-rule test
diff --git a/.vscode/launch.json b/.vscode/launch.json
@@ -5,8 +5,8 @@
  "name": "Run Extension (amicode-v2)",
  "type": "extensionHost",
  "request": "launch",
- "args": ["--extensionDevelopmentPath=${workspaceFolder}"],
- "outFiles": ["${workspaceFolder}/dist/**/*.js"]
+ "args": ["--extensionDevelopmentPath=${workspaceFolder}/packages/extension"],
+ "outFiles": ["${workspaceFolder}/packages/extension/dist/**/*.js"]
  }
  ]
 }
diff --git a/bin/amico-run b/bin/amico-run
diff --git a/package.json b/package.json
@@ -1,85 +1,10 @@
 {
- "name": "amicode-v2",
- "displayName": "Amicode v2",
- "description": "Amico research IDE — opencode-backed chat + native VS Code surfaces for vault, catalog, and live solve inspection.",
- "version": "0.0.1",
- "publisher": "harmoniqs",
- "license": "Apache-2.0",
+ "name": "amicode-workspace",
  "private": true,
- "engines": {
- "vscode": "^1.95.0"
- },
- "categories": ["Other"],
- "activationEvents": [
- "onCommand:amicode.openChat",
- "onCommand:amicode.openInspector",
- "onView:amicode.runInspector",
- "onView:amicode.vault",
- "onStartupFinished"
- ],
- "main": "./dist/extension.js",
- "contributes": {
- "viewsContainers": {
- "activitybar": [
- {
- "id": "amicode",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ],
- "panel": [
- {
- "id": "amicode-panel",
- "title": "Amicode",
- "icon": "media/amico.svg"
- }
- ]
- },
- "views": {
- "amicode": [
- { "id": "amicode.vault", "name": "Vault", "type": "tree" },
- { "id": "amicode.catalog", "name": "Catalog", "type": "tree" },
- { "id": "amicode.armonia", "name": "Armonia", "type": "tree" }
- ],
- "amicode-panel": [
- { "id": "amicode.runInspector", "name": "Run Inspector", "type": "webview" }
- ]
- },
- "commands": [
- { "command": "amicode.openChat", "title": "Amicode: Open Chat" },
- { "command": "amicode.openInspector", "title": "Amicode: Open Run Inspector" },
- { "command": "amicode.restartServer", "title": "Amicode: Restart opencode server" }
- ],
- "configuration": {
- "title": "Amicode",
- "properties": {
- "amicode.opencodeBinary": {
- "type": "string",
- "default": "opencode",
- "description": "Path or command name for the opencode CLI."
- },
- "amicode.juliaProject": {
- "type": "string",
- "default": "/tmp/amicode-spike-julia",
- "description": "Julia project root (--project=...) the run_julia tool will use."
- },
- "amicode.juliaScript": {
- "type": "string",
- "default": "",
- "description": "Absolute path to spike_solve.jl. If empty, looks up via the extensionPath/../amicode/julia/spike_solve.jl convention."
- }
- }
- }
- },
  "scripts": {
- "build":  "node esbuild.config.mjs",
- "watch":  "node esbuild.config.mjs --watch",
- "typecheck": "tsc --noEmit"
+ "build": "pnpm -r run build",
+ "typecheck": "pnpm -r run typecheck",
+ "test": "pnpm -r run test"
  },
- "devDependencies": {
- "@types/node": "^22.0.0",
- "@types/vscode": "^1.95.0",
- "esbuild": "^0.24.0",
- "typescript": "^5.6.0"
- }
+ "packageManager": "pnpm@9.15.9"
 }
diff --git a/packages/amico-run/esbuild.config.mjs b/packages/amico-run/esbuild.config.mjs
@@ -0,0 +1,17 @@
+import { build } from 'esbuild'
+import { chmodSync } from 'node:fs'
+
+await build({
+ entryPoints: ['src/cli.ts'],
+ bundle: true,
+ platform: 'node',
+ target: 'node20',
+ // ESM, not CJS: the package is "type": "module", so node executes dist/amico-run.js
+ // as ESM — a CJS bundle would die on `require is not defined in ES module scope`.
+ format: 'esm',
+ outfile: 'dist/amico-run.js',
+ banner: { js: '#!/usr/bin/env node' },
+ sourcemap: true,
+ logLevel: 'info',
+})
+chmodSync('dist/amico-run.js', 0o755)
diff --git a/packages/amico-run/launcher/amico-run b/packages/amico-run/launcher/amico-run
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Thin launcher: resolve node, exec the bundled orchestrator. No logic lives here.
+set -euo pipefail
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do # resolve symlink chains (node_modules/.bin)
+ DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+ SOURCE="$(readlink "$SOURCE")"
+ [[ $SOURCE != /* ]] && SOURCE="$DIR/$SOURCE"
+done
+DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+if ! command -v node >/dev/null 2>&1; then
+ echo "amico-run: node >= 20 not found on PATH (install node or fix PATH; see provisioning runbook)" >&2
+ exit 64
+fi
+exec node "$DIR/../dist/amico-run.js" "$@"
diff --git a/packages/amico-run/package.json b/packages/amico-run/package.json
@@ -0,0 +1,23 @@
+{
+ "name": "@amicode/amico-run",
+ "version": "0.1.0",
+ "license": "Apache-2.0",
+ "type": "module",
+ "main": "./src/index.ts",
+ "types": "./src/index.ts",
+ "bin": { "amico-run": "./launcher/amico-run" },
+ "engines": { "node": ">=20" },
+ "scripts": {
+ "build": "node esbuild.config.mjs",
+ "typecheck": "tsc --noEmit",
+ "test": "vitest run --passWithNoTests --exclude '**/slow/**'",
+ "test:slow": "vitest run test/slow"
+ },
+ "devDependencies": {
+ "@types/node": "^22.0.0",
+ "esbuild": "^0.24.0",
+ "smol-toml": "^1.3.0",
+ "typescript": "^5.6.0",
+ "vitest": "^2.1.0"
+ }
+}
diff --git a/packages/amico-run/src/cli.ts b/packages/amico-run/src/cli.ts
@@ -0,0 +1,82 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { LocalExecutor } from './local_executor.js'
+import { ConfigError, type Finished, type SubmitOpts } from './types.js'
+
+const USAGE = `usage: amico-run <script.jl> [--executor local] [--lab <id-or-path>]
+ [--runs-root <path>] [--julia <path>] [--project <path>] [--sysimage <path>]`
+
+export async function main(argv: string[]): Promise<number> {
+ let script: string | undefined
+ let executor = 'local'
+ const opts: SubmitOpts = { julia: {} }
+
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i]
+ const next = (): string => {
+ const v = argv[++i]
+ if (v === undefined) throw new ConfigError(`flag ${a} requires a value`)
+ return v
+ }
+ try {
+ switch (a) {
+ case '--help': case '-h': console.log(USAGE); return 0
+ case '--executor': executor = next(); break
+ case '--lab': opts.lab = next(); break
+ case '--runs-root': opts.runsRoot = next(); break
+ case '--julia': opts.julia!.julia = next(); break
+ case '--project': opts.julia!.project = next(); break
+ case '--sysimage': opts.julia!.sysimage = next(); break
+ default:
+ if (a.startsWith('-')) { console.error(`amico-run: unknown flag ${a}\n${USAGE}`); return 64 }
+ if (script) { console.error(`amico-run: multiple scripts given`); return 64 }
+ script = a
+ }
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+ }
+ if (!script) { console.error(`amico-run: no script given\n${USAGE}`); return 64 }
+ if (executor !== 'local') { console.error(`amico-run: only --executor local is supported in β`); return 64 }
+
+ let handle
+ try {
+ handle = await new LocalExecutor().submit(script, opts)
+ } catch (e) {
+ if (e instanceof ConfigError) { console.error(`amico-run: ${e.message}`); return 64 }
+ throw e
+ }
+
+ const onSignal = (): void => { void handle.abort() }
+ process.on('SIGINT', onSignal)
+ process.on('SIGTERM', onSignal)
+
+ let fin: Finished | undefined
+ for await (const ev of handle.events) {
+ if (ev.kind === 'iter' || ev.kind === 'done') console.log(ev.raw)
+ else if (ev.kind === 'log') console.log(ev.line)
+ else fin = { status: ev.status, exitCode: ev.exitCode }
+ }
+ const f = fin ?? await handle.finished
+
+ // FINISHED-write failure lane (spec §6 last row): verdict file must exist on disk
+ if (!existsSync(join(handle.runDir, 'FINISHED'))) {
+ console.error(`amico-run: FINISHED missing in ${handle.runDir} (write fault)`)
+ return 64
+ }
+ // stdout protocol line — camelCase by design (spec §4)
+ console.log(`AMICODE_FINISHED status=${f.status} exitCode=${f.exitCode} runDir=${handle.runDir}`)
+ if (f.status === 'aborted') return 130
+ if (f.status === 'completed') return 0
+ return f.exitCode === 0 ? 1 : f.exitCode
+}
+
+main(process.argv.slice(2)).then(
+ c => { process.exitCode = c },
+ e => {
+ // Any unexpected throw is an orchestrator fault, not a solve failure → 64.
+ console.error(`amico-run: unexpected error: ${e instanceof Error ? e.stack ?? e.message : e}`)
+ process.exitCode = 64
+ },
+)