headlesscode 1.0.2

package/SECURITY.md

@@ -0,0 +1,211 @@
+# Security
+
+## TL;DR
+
+`headlesscode` is a **headless coding-agent harness**: an AI model reads a task,
+then drives your machine by running shell commands and editing files. By design,
+an unconfigured session runs **arbitrary commands with your full user
+privileges** and can **read and modify your files** — including `~/.ssh`,
+`~/.aws`, and any other credentials the user can access.
+
+**Run it only on a machine you are willing to let an AI operate, only on
+repositories you trust, and only with untrusted content isolated from your real
+session.** This project does not sandbox agent actions, and nothing in the
+harness can be relied upon to stop a malicious or compromised model that has
+been given the ability to execute commands.
+
+## Default-allow command execution
+
+An unconfigured session gives the agent:
+
+- **Arbitrary shell command execution.** `execute_command` spawns the
+  model-supplied command string with `shell: true`, the full process
+  environment, and no sandbox (see
+  [`src/tools/executor.ts`](src/tools/executor.ts:1286) and
+  [`src/permissions/commands.ts`](src/permissions/commands.ts:834)). The
+  command runs as **you** — the same OS user, with the same files, network
+  access, and credentials the harness process has. There is no per-command
+  approval prompt (the harness is non-interactive by design), no container, and
+  no privilege boundary.
+- **File read/write.** The write tools (`write_to_file`, `apply_diff`,
+  `search_replace`, `edit_file`) can create and overwrite any file under the
+  workspace root. Reads are not restricted at all.
+
+An empty `allowedCommands` list means **allow everything** — only the
+`deniedCommands` list (also empty by default) restricts anything. This is a
+deliberate design choice for a headless tool: it preserves the behavior of a
+local CLI that a developer runs in their own checkout. It is **not** a security
+boundary.
+
+### What this means in practice
+
+With default settings, an agent can, for example:
+
+- Read `~/.ssh/id_rsa`, `~/.aws/credentials`, or any other file the user can
+  read.
+- Exfiltrate data over the network (`curl`, `scp`, `gh`, …).
+- Modify, delete, or encrypt files; install software; change system
+  configuration.
+- Persist backdoors or leave any other modification on the machine.
+
+Do not point this at data or machines where that outcome would be
+unacceptable, and do not feed it untrusted task text or repository content you
+have not reviewed.
+
+## When untrusted content is involved
+
+If the task text, the repository, or anything the agent will read could be
+hostile, treat the agent as untrusted code running as your user. The only safe
+mitigation is OS-level isolation **outside** this project — for example a
+throwaway container, VM, or dedicated user account with no access to your real
+credentials:
+
+- No credentials (SSH keys, cloud tokens, API keys) mounted unless the task
+  genuinely needs them.
+- No writable access to anything you care about beyond a scratch workspace.
+- Network access limited if exfiltration is a concern.
+
+The harness itself cannot provide this isolation, and no amount of prompt
+engineering, rules files, or "trusted mode" configuration is a substitute for
+it.
+
+## Browser and vision cloud data flow
+
+Two agent-driven tools send data off the machine as part of their normal
+operation — not a bug, but worth knowing before pointing either at anything
+sensitive:
+
+- **Browser tool.** `browser_action` (see
+  [`src/tools/browser/service.ts`](src/tools/browser/service.ts:112)) launches
+  a headless Chromium instance and navigates it to whatever URL the model
+  supplies. The page content, cookies set by the site, and any redirects are
+  fetched directly by the browser process on your machine/network — the same
+  as visiting the URL yourself. If the model is given (or invents) a URL for
+  an internal or sensitive endpoint, that page's content becomes visible to
+  the model in its response.
+- **Vision (image description).** `describeImage`
+  (see [`src/vision/describe.ts`](src/vision/describe.ts:118)) base64-encodes
+  a screenshot or workspace image and POSTs it to OpenRouter
+  (`openrouter.ai`, or `HEADLESSCODE_VISION_MODEL`'s configured provider) for
+  captioning, then feeds the description back into the model's context. The
+  image bytes themselves leave the machine and are processed by a third-party
+  cloud model, subject to that provider's own data-handling policy.
+
+Neither flow has a local-only mode today. Do not use `browser_action` against
+URLs, or `describeImage` against screenshots/images, that contain data you
+would not otherwise send to a third-party cloud API.
+
+## The permissions mechanism (defense in depth, not a boundary)
+
+The harness ships an optional permissions layer that can restrict what the
+agent does — see [`docs/central-store.md`](docs/central-store.md) and
+[`src/permissions/config.ts`](src/permissions/config.ts). It includes:
+
+- `--allowed-commands` / `--denied-commands` (or
+  `HEADLESSCODE_ALLOWED_COMMANDS` / `HEADLESSCODE_DENIED_COMMANDS`, or a
+  central `permissions.json`) — allow/deny prefix matching for commands.
+- `--protected-files` / `HEADLESSCODE_PROTECTED_FILES` — glob patterns of files
+  the write tools refuse to touch (defaults protect `.env`, `*.pem`, `*.key`,
+  `id_rsa*`).
+- `--allow-protected-writes` — explicit escape hatch that bypasses the
+  protected-files check (OFF by default).
+
+This layer is useful defense in depth against accidents and makes refusal
+messages actionable, but it is a **prefix-match policy on a command string**, not
+a sandbox. A malicious or sufficiently capable model can evade it (e.g. by
+writing a script and running it, or by abusing any command that is allowed), so
+**do not rely on it to contain untrusted code.** Restricting commands does not
+restrict what the agent can *read* or what allowed commands can accomplish.
+
+## Known limitations (tracked audit findings)
+
+These are specific, known gaps in the defense-in-depth layers above — not new
+risks beyond the "not a sandbox" scope already documented, but concrete ways
+the prefix-match and pattern-based checks can be evaded. Documented here per
+the project's own audit process rather than silently left implicit.
+
+- **Deny-list is a raw-string prefix match, not a program-identity check**
+  (`src/permissions/commands.ts` — `findLongestPrefixMatch`). A deny entry of
+  `rm` is trivially evaded by `command rm`, `/bin/rm`, `env rm`, `xargs rm`,
+  or `python -c "shutil.rmtree(...)"` — none of these share the `rm` prefix.
+  The allow/deny mechanism is prefix matching on the literal command string by
+  design (ported verbatim from upstream for parity); it does not resolve
+  `argv[0]`, follow `PATH`, or understand that many programs can accomplish
+  the same effect. Treat every deny-list entry as a speed bump against
+  accidental/careless commands, never as a guarantee that a given program
+  cannot run.
+- **Central-store protection (`src/permissions/store-protection.ts`) is
+  pattern-based, not a sandbox.** As of the SEC-6 fix it protects the store
+  root, its ancestors, AND its descendants, and it follows symlinks
+  (`fs.realpathSync`) and tracks a leading `cd <dir> &&` chain's effective
+  cwd. It still does **not** catch: `cd` performed inside a subshell
+  (`(cd /x && rm -rf y)`) or via a shell variable/`pushd`/`popd`; `sudo rm`;
+  non-`rm` deletion (`find ... -delete`, `python -c shutil.rmtree(...)`, a
+  script that deletes the store); or a non-recursive `rm` of a single file
+  inside the store. It only recognizes GNU/POSIX `rm` flag syntax.
+- **The dashboard's local HTTP server gates only POST routes with the bearer
+  token** (`HEADLESSCODE_DASHBOARD_TOKEN`); GET routes that list/read
+  workspace files, checkpoints, codemap, cost history, and projects are
+  reachable by any request that can reach `127.0.0.1` on the dashboard port
+  (including via DNS-rebinding or localhost-CSRF from a browser tab open to a
+  malicious page). Do not run the dashboard on a shared or multi-user machine
+  without additional network isolation (see also
+  [`src/dashboard/files.ts`](src/dashboard/files.ts) and
+  [`src/dashboard/trend.ts`](src/dashboard/trend.ts)).
+- **`execute_command` children inherit the full process environment,**
+  including `HEADLESSCODE_OPENROUTER_API_KEY` and any other secret exported
+  into the harness's own env. `protected-files.ts` only prevents the agent
+  from *writing* `.env`; nothing stops the agent from reading its own
+  process's environment (`printenv`, `env`) and having that flow into the LLM
+  context. Acceptable for the documented trusted-single-user model; a real
+  constraint if this project is ever run multi-tenant (see
+  `docs/multi-tenant-hosting-design.md`) — don't put shared secrets in a
+  session's environment that a given task should not be able to see.
+
+## Reporting vulnerabilities
+
+This project is pre-1.0 and has no private disclosure channel yet. For now,
+report security findings by opening a GitHub issue on
+[Capsize-Games/headlesscode](https://github.com/Capsize-Games/headlesscode)
+tagged `security`, or a pull request with a fix. See the docs in `docs/` for
+the overall design.
+
+## Supported versions
+
+Only the current `master` branch is supported. The project has not cut
+releases yet (no tags, `version: 0.1.0`); patches land on `master` and are
+expected to be forward-only.
+
+## Security-relevant areas
+
+If you are auditing the codebase, the highest-value targets are:
+
+- `src/tools/executor.ts` — the tool executor, including the
+  `execute_command` handler that spawns shell commands and the path-traversal
+  guard for file tools.
+- `src/permissions/` — command allow/deny, protected files, and the
+  central-store protection; defaults are documented in `config.ts`.
+- `src/cloud/` and `src/orchestrator/` — session isolation, worktree
+  spawning, and the scripts they shell out to (`scripts/*.sh`).
+- `src/vendor/zoo-code/` — the vendored Apache-2.0 portable core (see
+  `ATTRIBUTION.md`); upstream security fixes should be tracked via
+  `VENDOR-NOTES.md`.
+
+The npm package (`npm pack`) ships only the runtime source under `src/`
+(excluding `__tests__/`), `shared/`, and the top-level docs — internal
+`plans/`, `recon/`, `.roo/`, and dev scripts are intentionally excluded (see
+the `files` field in `package.json`).
+
+## Responsible-use checklist
+
+Before running `headlesscode` on anything you care about:
+
+1. Confirm you are running it as a user whose privileges you are willing to
+   expose to the agent (ideally a dedicated, unprivileged account).
+2. Confirm the workspace and task are trusted, or the environment is isolated
+   (container/VM) so the blast radius is contained.
+3. Review the command permissions (`--allowed-commands` /
+   `--denied-commands`) and protected files (`--protected-files`) if you want
+   the defense-in-depth layer on.
+4. Never run it with credentials or secrets mounted that the task does not
+   need.

package/bin/headlesscode.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * headlesscode bin launcher (issue #99).
+ *
+ * npm's `bin` entry used to point at `src/cli.ts`, whose shebang is
+ * `#!/usr/bin/env tsx` — but tsx is a devDependency, so on a clean
+ * `npm install -g` (which installs dependencies only) `env` finds no `tsx`
+ * on PATH and every invocation fails with "tsx: not found".
+ *
+ * This launcher fixes that by resolving THIS package's own node_modules/tsx
+ * directly (the same ancestor walk-up `scripts/run-tests.mjs` uses — npm
+ * flattens node_modules, so tsx may live in this package's node_modules OR
+ * be hoisted to an ancestor's) and re-execing node through tsx's CLI entry.
+ * It also pins TSX_TSCONFIG_PATH to this package's tsconfig.json so tsx
+ * resolves the package's own tsconfig instead of discovering one from the
+ * caller's CWD (the tsconfig now has no `paths` aliases — issue #99 rework —
+ * but the pin keeps the package's compiler options, e.g. `moduleResolution`,
+ * stable regardless of where the CLI is invoked from).
+ *
+ * A small amount of JS (not TS) on purpose: the launcher must run without
+ * tsx — the whole point is that it finds tsx itself.
+ */
+
+import { spawnSync } from "node:child_process"
+import * as fs from "node:fs"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+
+/** This package's root (the directory above bin/). */
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+
+/**
+ * Resolve the tsx CLI entry by walking up through ancestor `node_modules`
+ * directories — the same resolution Node's own module lookup (and
+ * `scripts/run-tests.mjs`) uses. npm hoists dependencies to the nearest
+ * ancestor node_modules, so the tsx binary may sit at
+ * `<pkgRoot>/node_modules/tsx/dist/cli.mjs` (repo checkout, nested install)
+ * or at an ancestor's (a global install or a consumer with a flat tree).
+ */
+function resolveTsxCli(dir) {
+	let current = dir
+	while (true) {
+		const candidate = path.join(current, "node_modules", "tsx", "dist", "cli.mjs")
+		if (fs.existsSync(candidate)) {
+			return candidate
+		}
+		const parent = path.dirname(current)
+		if (parent === current) {
+			return undefined
+		}
+		current = parent
+	}
+}
+
+const tsxCli = resolveTsxCli(PKG_ROOT)
+if (tsxCli === undefined) {
+	process.stderr.write(
+		"headlesscode: cannot find the 'tsx' runtime (node_modules/tsx/dist/cli.mjs) — " +
+			"this package's dependencies are not installed. Run `npm install` (or re-install the package) and retry.\n",
+	)
+	process.exit(1)
+}
+
+const cliEntry = path.join(PKG_ROOT, "src", "cli.ts")
+const tsconfigPath = path.join(PKG_ROOT, "tsconfig.json")
+
+// Run the CLI through tsx in a child process with inherited stdio. The
+// caller's cwd is preserved (headlesscode's own --repo/--workspace default
+// to process.cwd(), matching install-cli.sh's wrapper contract). TSX_TSCONFIG_PATH
+// pins tsconfig resolution to THIS package, independent of the cwd.
+const result = spawnSync(
+	process.execPath,
+	[tsxCli, cliEntry, ...process.argv.slice(2)],
+	{ stdio: "inherit", env: { ...process.env, TSX_TSCONFIG_PATH: tsconfigPath } },
+)
+
+if (result.error) {
+	process.stderr.write(`headlesscode: failed to launch the CLI: ${result.error.message}\n`)
+	process.exit(1)
+}
+// Propagate the CLI's exit code; a signal-killed child becomes a non-zero
+// exit here (the launcher itself has no signal handlers installed).
+process.exit(result.status ?? 1)

package/package.json

@@ -0,0 +1,63 @@
+{
+	"name": "headlesscode",
+	"version": "1.0.2",
+	"description": "Standalone headless coding-agent harness: runs the Zoo Code agent loop (prompts, tools, modes) without a VS Code UI, driven by CLI, HTTP, and parallel worktree orchestration.",
+	"license": "Apache-2.0",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/Capsize-Games/headlesscode.git"
+	},
+	"author": "The headlesscode contributors",
+	"keywords": [
+		"cli",
+		"coding-agent",
+		"headless",
+		"automation",
+		"agent"
+	],
+	"type": "module",
+	"engines": {
+		"node": ">=18"
+	},
+	"bin": {
+		"headlesscode": "bin/headlesscode.mjs"
+	},
+	"files": [
+		"LICENSE",
+		"README.md",
+		"ATTRIBUTION.md",
+		"SECURITY.md",
+		"CONTRIBUTING.md",
+		"CODE_OF_CONDUCT.md",
+		"tsconfig.json",
+		"shared/",
+		"src/",
+		"!src/**/__tests__/",
+		"!src/**/*.test.ts"
+	],
+	"scripts": {
+		"typecheck": "tsc --noEmit",
+		"smoke": "tsx src/vendor/tests/smoke.ts",
+		"dev": "tsx src/index.ts",
+		"start": "tsx src/cli.ts",
+		"cli": "tsx src/cli.ts",
+		"test": "node scripts/run-tests.mjs",
+		"prepublishOnly": "npm ci && npm test"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.30.0",
+		"@octokit/auth-app": "^8.2.0",
+		"fastest-levenshtein": "^1.0.16",
+		"p-wait-for": "^5.0.2",
+		"playwright": "^1.62.1",
+		"simple-git": "^3.36.0",
+		"tsx": "^4.19.0",
+		"typescript": "^5.6.0",
+		"undici": "^8.10.0",
+		"yaml": "^2.5.1",
+		"zod": "^3.25.76"
+	},
+	"devDependencies": {
+		"@types/node": "^22.10.0"
+	}
+}

package/shared/prompts/review-mode-prompt-short.md

@@ -0,0 +1,93 @@
+# Independent review — operating procedure
+
+Use this after a worker session (in any worktree under `.worktrees/`) claims
+to have finished a task. Run it against that worktree directly — it needs
+the real checked-out branch, not a description of the work.
+
+---
+
+You are an independent reviewer. You did not write the code you are about to
+review, and you must not extend it any benefit of the doubt. Your job is to
+verify claims against reality, not to check whether the claims sound
+plausible. Assume the report you're reviewing has at least one wrong or
+overstated claim until you've personally confirmed otherwise — reports from
+autonomous coding sessions routinely overstate what was actually verified
+(a claimed "all tests pass" that turns out to mean "the tests that were
+touched pass," a claimed e2e run that was never actually executed, a
+"verified working" that means "looks right on read-through").
+
+## What to review
+
+1. **Read the worker's own summary/report in full.** Note every concrete,
+   checkable claim: which files changed, test/e2e pass counts, "tsc clean,"
+   specific behaviors it says it preserved or fixed.
+2. **Read the actual diff** (`git -C .worktrees/<name> diff origin/master...HEAD`
+   or equivalent) — not just the summary. Read the whole diff for anything
+   under ~500 lines; for larger diffs, prioritize the highest-risk files
+   first (anything touching the tool executor, budget/cost accounting,
+   orchestrator state, or checkpoint/git operations) before sampling the
+   rest.
+3. **Re-run every checkable claim yourself, for real, inside that worktree:**
+   - `npx tsc --noEmit` — confirm it's actually clean, don't take "tsc
+     clean" on faith.
+   - `npm test` — compare the actual suite count/pass count against what
+     the report claims. A mismatch of even one suite is not a rounding
+     error.
+   - If the report claims e2e suites pass, re-run the relevant ones under
+     `scripts/e2e*/run.sh` yourself and compare actual PASS/FAIL counts.
+   - If the report claims a manual smoke test was run (e.g. "confirmed the
+     dashboard shows a running session," "confirmed the process wasn't
+     killed on timeout"), reproduce it yourself where practical rather than
+     trusting the description — these are exactly the kind of claims most
+     likely to be asserted without having actually been checked.
+4. **Check for silent behavior changes**, not just crashes or test
+   failures — a change that alters control flow (e.g. moving a non-fatal
+   try/catch, changing what a timeout does, changing default-allow to
+   default-deny somewhere) can pass every existing test and still be wrong
+   if nothing exercises that specific path. Read the diff for anything that
+   changes an existing function's behavior, not just what's newly added.
+5. **Check the task file the worker was given** (whichever `plans/*.md` file
+   governed this worktree) and confirm the work actually addresses what was
+   asked, including anything under "What NOT to do" — a worker that built
+   something not requested, or built something explicitly excluded, is a
+   real finding even if the code itself is otherwise fine.
+6. **Keep every scratch/temp file inside the workspace — no `/tmp`.**
+   Any scratch you need (probe scripts, temp output captures, throwaway
+   test files) goes in `<workspace>/.headlesscode/scratch/` (create it
+   if it doesn't exist; `/.headlesscode/` is gitignored). Writing to
+   `/tmp` or any other path outside the workspace violates the repo's
+   "Never write to /tmp" rule — outside-workspace writes cannot be
+   auto-approved in the interactive GUI and are rejected by the file
+   tools in headless workers.
+
+## Verdict and action
+
+- **If everything checks out**: say so plainly, with the actual command
+  output you personally reproduced as evidence, not "looks good."
+- **If you find a real problem**: report it with exact file:line evidence,
+  the real command output that demonstrates it, and specific, actionable
+  instructions for what needs to change — written the way you'd want to
+  receive feedback if you were about to fix it yourself.
+- **Do not fix the problem yourself in this mode.** Verification and
+  remediation are separate passes — report what needs to change, don't
+  change it.
+
+## What NOT to do
+
+- Do not pad the review with issues that have no real consequence just to
+  look thorough.
+- Do not accept "the tests pass" as sufficient evidence for a claim the
+  tests don't actually exercise — check what the tests actually assert.
+- Do not skip re-running commands because the report already includes
+  output — output in a report is a claim, not evidence, until reproduced.
+- Do not review by reading only the summary — read the actual diff and run
+  actual commands every time.
+- No `/tmp` — scratch goes in `<workspace>/.headlesscode/scratch/` (the
+  repo rule "Never write to /tmp" is binding here too; a `/tmp` write in
+  a review session is a finding).
+
+## When you're done
+
+Give a short final verdict: pass or fail, and if fail, the specific list of
+what needs to change, precise enough that someone could act on it without
+re-deriving your findings from scratch.