ghostrail 0.15.0 → 0.15.2

package/README.md

@@ -10,7 +10,7 @@ Ghostrail turns a repo into a factory by dropping in one config file and one pro
 
 A software factory is thin glue over three primitive layers: where work comes from, what agent does the work, and where the work runs in isolation. Most people rebuild that glue per repo. Ghostrail extracts it once, so the tracker, the agent job, the gate, and the isolation backend are all configuration:
 
-- **Config-driven.** A `ghostrail.toml` plus a prompt file is the whole factory.
+- **Config-driven.** A [`ghostrail.toml`](#configuration-reference) plus a prompt file is the whole factory.
 - **Pluggable backends.** `local-worktree` and `container-per-run` ship first-class; Firecracker, E2B, and remote sandboxes are adapters behind the same five-verb interface.
 - **Pluggable agents.** Claude Code headless is the day-one agent, behind an `[agent]` seam so other agents can slot in.
 - **Local and simple by default.** The quickstart runs on your own hardware with zero infrastructure and no additional cost. Cloud backends and a hosted board are opt-in.
@@ -26,6 +26,208 @@ ghostrail respond                  # fold new human PR comments back into branch
 ghostrail board                    # watch runs at http://127.0.0.1:5050/
 ```
 
+## Configuration reference
+
+`ghostrail.toml` is the whole factory: one file, one table per adapter seam.
+Every key below is read and validated in
+[`src/config/load.ts`](./src/config/load.ts); the defaults come from
+[`src/config/schema.ts`](./src/config/schema.ts) — this table is checked
+against that code, not against the illustrative templates under
+[`templates/`](./templates) or [`examples/`](./examples), which drift.
+
+A few things apply across every table, worth knowing before you read them:
+
+- **Durations are strings.** `timeout` and `claim_ttl` are parsed by a small
+  parser that accepts a whole positive number plus one unit: `"30m"`, `"2h"`,
+  `"90s"`. A bare number (`30`) is a validation error, not minutes.
+- **An invalid value does not stop the rest of the file from validating.**
+  Every key is checked independently: a missing or malformed value is
+  recorded as an error and that one key falls back to its default, so one
+  typo doesn't hide problems elsewhere in the file. That said, `ghostrail
+  run`/`watch` still refuse to start if *any* error was recorded — look for
+  `config error at <path>: ...` lines on stderr. A couple of lookups made
+  before a run starts (like the factory name in early log output) instead
+  treat a config that fails to validate as absent and quietly fall back to
+  their own hardcoded default, without printing anything.
+- **An omitted section takes every default in it.** `[guardrails]`,
+  `[backend]`, `[gate]`, and `[output]` can all be left out of the file
+  entirely.
+
+### `[factory]`
+
+| Key | Type | Values | Default | Required |
+| --- | --- | --- | --- | --- |
+| `name` | string | any non-empty string | none | yes |
+| `base_branch` | string | any non-empty string | `"main"` | no |
+| `source` | string | a git URL or local path | none — operates on `--repo` in place | no |
+
+### `[source]`
+
+| Key | Type | Values | Default | Required |
+| --- | --- | --- | --- | --- |
+| `kind` | string | `"linear"` \| `"github-issues"` \| `"beads"` | `"linear"`* | yes |
+| `team` | string | tracker team key | `""` | yes for `linear`, no otherwise |
+| `project` | string | project name within the team | none | no |
+
+\* A missing or invalid `kind` is recorded as an error, then falls back to
+`"linear"` rather than blocking the rest of the file — see the note above.
+
+#### `[source.eligible]`
+
+Filters which tracker items are eligible work. The same shape is reused,
+verbatim, by [`[triage.eligible]`](#triage-optional).
+
+| Key | Type | Values | Default | Required |
+| --- | --- | --- | --- | --- |
+| `state` | string | a tracker workflow state name | none — not filtered | no |
+| `label` | string or array of strings | one or more label names (AND'd) | `[]` — not filtered | no |
+| `assignee` | string | `"unassigned"` \| `"me"` \| a user email or id | none — not filtered | no |
+
+### `[agent]`
+
+| Key | Type | Values | Default | Required |
+| --- | --- | --- | --- | --- |
+| `kind` | string | `"claude-code"` today | `"claude-code"`* | yes |
+| `prompt` | string | path to a prompt file, relative to the config | none | yes |
+| `allowed_tools` | array of strings | tool names the agent may call | `["Read", "Edit", "Write", "Bash", "Grep", "Glob"]` | no |
+
+\* Same fallback as `[source].kind`: missing or invalid is an error, and the
+field still resolves to `"claude-code"`.
+
+### `[backend]`
+
+| Key | Type | Values | Default | Required |
+| --- | --- | --- | --- | --- |
+| `kind` | string | `"local-worktree"` \| `"container"` \| `"firecracker"` \| `"e2b"` \| `"remote"` | `"local-worktree"` | no |
+| `image` | string | a container image reference | none | no — needed once `kind = "container"` |
+| `managed_checkout` | boolean | `true` \| `false` | `true` | no |
+
+`managed_checkout` only affects `local-worktree`: `true` makes worktrees from
+a bare clone ghostrail owns under its own state dir; `false` borrows your
+working checkout instead. See [choosing a backend](docs/backends.md).
+
+### `[gate]`
+
+| Key | Type | Values | Default | Required |
+| --- | --- | --- | --- | --- |
+| `commands` | array of strings | shell commands, run in order in the workspace | `[]` | no |
+
+### `[guardrails]`
+
+| Key | Type | Values | Default | Required |
+| --- | --- | --- | --- | --- |
+| `max_items_per_run` | number | > 0 | `3` | no |
+| `budget_usd_per_item` | number | > 0 | `3` | no |
+| `max_cost_usd_per_run` | number | > 0 | `5` | no |
+| `timeout` | duration string | e.g. `"30m"` | `"30m"` | no |
+| `claim_ttl` | duration string | e.g. `"2h"` | `"2h"` | no |
+| `concurrency` | number | > 0 | `1` | no |
+
+- `budget_usd_per_item` does two jobs: it's the hard per-item cost ceiling,
+  *and* it's the cost ghostrail assumes for an item that finishes without
+  reporting any cost at all. Raising it to give one item more headroom also
+  raises what an unreported-cost item gets charged.
+- Neither budget key can express "unlimited" today
+  ([TJ-1581](https://linear.app/timothyjordan/issue/TJ-1581/featguardrails-allow-an-unlimited-budget-for-budget-usd-per-item-and)
+  tracks adding one); update this row once it ships.
+- This table says what each key accepts. What each one bounds inside a tick,
+  and how they interact with `concurrency`, is the subject of the tick
+  documentation (tracked in
+  [TJ-1580](https://linear.app/timothyjordan/issue/TJ-1580/docs-explain-how-a-tick-works-and-how-every-guardrail-lever-changes-it));
+  until it lands, see "How it works" in [`docs/index.md`](docs/index.md).
+
+### `[output]`
+
+| Key | Type | Values | Default | Required |
+| --- | --- | --- | --- | --- |
+| `open_pr` | boolean | `true` \| `false` | `true` | no |
+| `draft` | boolean | `true` \| `false` | `false` | no |
+| `auto_merge` | boolean | `true` \| `false` | `false` | no |
+| `branch_prefix` | string | any non-empty string | `"ghostrail"` | no |
+| `commit_type` | string | a conventional-commit type, e.g. `"feat"`, `"fix"`, `"chore"` | `"chore"` | no |
+
+`auto_merge` is policy, not just a default: it hard-defaults to `false`
+because a human owns every merge. No combination of keys makes ghostrail
+merge its own PR.
+
+### Top level
+
+| Key | Type | Values | Default | Required |
+| --- | --- | --- | --- | --- |
+| `artifacts` | array of strings | names of global artifacts under `~/.config/ghostrail/artifacts/` | `[]` | no |
+
+### `[respond]` (optional)
+
+Enables `ghostrail respond`. Omit the whole section to leave it disabled.
+
+| Key | Type | Values | Default | Required |
+| --- | --- | --- | --- | --- |
+| `prompt` | string | path to a prompt file, relative to the config | none | yes, if `[respond]` is present |
+
+### `[triage]` (optional)
+
+Required by `ghostrail triage`; without it, that command has nothing to run.
+
+| Key | Type | Values | Default | Required |
+| --- | --- | --- | --- | --- |
+| `prompt` | string | path to a prompt file, relative to the config | none | yes, if `[triage]` is present |
+| `eligible` | inline table | same shape as [`[source.eligible]`](#sourceeligible) | `{ labels: [] }` | no |
+
+### A complete example
+
+```toml
+[factory]
+name = "fix-bugs"
+base_branch = "main"            # default; shown for clarity
+
+[source]
+kind = "linear"                 # linear | github-issues | beads
+team = "TJ"                     # required for linear: its team key
+project = "myproject"           # optional: scope to one project
+eligible = { state = "Todo", label = "factory", assignee = "unassigned" }
+
+[agent]
+kind = "claude-code"
+prompt = "prompts/fix-bug.md"
+# allowed_tools defaults to ["Read", "Edit", "Write", "Bash", "Grep", "Glob"]
+
+[backend]
+kind = "local-worktree"         # default; container | firecracker | e2b | remote also declared
+# managed_checkout = true       # default: local-worktree owns its clone
+
+[gate]
+commands = [
+  "pnpm install --frozen-lockfile",
+  "pnpm lint",
+  "pnpm typecheck",
+  "pnpm test:unit",
+]
+
+[guardrails]
+max_items_per_run = 3           # default
+budget_usd_per_item = 3         # default; also the assumed cost of an unreported-cost item
+max_cost_usd_per_run = 5        # default
+timeout = "30m"                 # default
+claim_ttl = "2h"                # default
+concurrency = 1                 # default: one item at a time
+
+[output]
+open_pr = true                  # default
+draft = false                   # default
+auto_merge = false              # hard default: a human owns every merge
+branch_prefix = "ghostrail"     # default
+commit_type = "chore"           # default
+
+artifacts = ["style-guide"]     # optional: shared references staged into every run
+
+[respond]                       # optional: enables `ghostrail respond`
+prompt = "prompts/respond.md"
+
+[triage]                        # optional: required by `ghostrail triage`
+prompt = "prompts/triage.md"
+eligible = { state = "Todo", label = "triage", assignee = "unassigned" }
+```
+
 ## Credentials
 
 Ghostrail reads its credentials from two dotenv-style files before every `run`,

package/dist/cli/commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"commands.d.ts","sourceRoot":"","sources":["../../src/cli/commands.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands.js

@@ -10,10 +10,10 @@ import { createBoardServer, isLoopback, normalizeToken } from "../board/server.j
 import { buildProposal, writeProfile } from "../claude-profile/index.js";
 import { parseDuration } from "../config/duration.js";
 import { parseConfig, parseMergedConfig } from "../config/load.js";
-import { createDashboardServer } from "../dashboard/index.js";
+import { createDashboardServer, defaultStateDir } from "../dashboard/index.js";
 import { buildLoopDeps, buildRespondDeps, buildTriageDeps, repoGhRunner, resolveRepoSlug, } from "../factory/build.js";
 import { describeMigration, migrateLegacyStore, resolveWorkRepo, stateDirFor, } from "../factory/state.js";
-import { entryKey, findByKey, findByPath, upsert } from "../global/registry.js";
+import { entryKey, findByPath, findForRepoResolving, replaceEntry, upsert, } from "../global/registry.js";
 import { canonicalRepoId, localRepoId } from "../global/repo-id.js";
 import { GlobalStore, resolveGlobalDir } from "../global/store.js";
 import { DEFAULT_FACTORY_IMAGE, dockerBuildArgs, dockerDir, parseImageFlags, } from "../image/build.js";
@@ -34,6 +34,7 @@ import { FileStore } from "../store/file-store.js";
 import { triageTick } from "../triage/engine.js";
 import { VERSION } from "../version.js";
 import { askOnTerminal, parseInstallOffers } from "./prompt.js";
+import { describeStalledUpdate } from "./update-diagnosis.js";
 /**
  * Parse the flags shared by `run` and `respond`: `--config`/`-c <path>` and
  * `--repo`/`-C <path>`, starting from the given defaults. Unknown tokens are
@@ -436,6 +437,7 @@ function dashboardDeps(env, manager) {
         readRegistry: () => store.readRegistry(),
         writeRegistry: (entries) => store.writeRegistry(entries),
         health: ghostrailHealth,
+        stateDir: defaultStateDir,
         states: async (entries) => {
             if ((await manager.kind()) !== "systemd")
                 return new Map();
@@ -1068,16 +1070,27 @@ async function registerGhostrail(repo, env, streams) {
             return;
         }
         const repoId = await resolveRepoId(path);
-        const existing = findByKey(entries, repoId);
+        const existing = await findForRepoResolving(entries, repoId, path, resolveRepoId);
         if (existing !== undefined) {
-            // A second checkout of a repo that already has a ghostrail. Adopt this
-            // checkout as the hint and say so, rather than adding a second ghostrail
-            // that would poll the same tracker query and race the first for its work.
-            if (existing.path === path)
+            // Everything the entry already carries survives, `watch` above all:
+            // re-registering must never switch a ghostrail back on that the operator
+            // deliberately turned off.
+            const adopted = { ...existing, repo: repoId, path };
+            if (existing.repo === repoId && existing.path === path)
                 return;
-            await store.writeRegistry(upsert(entries, { ...existing, repo: repoId, path }));
-            streams.out(`this repo already has the ghostrail "${existing.name}"; pointed it at this checkout\n` +
-                `  was: ${existing.path}\n  now: ${path}\n`);
+            // By the entry's *old* key: adopting an identity re-keys it, so an
+            // ordinary upsert would append beside it rather than replace it.
+            await store.writeRegistry(replaceEntry(entries, entryKey(existing), adopted));
+            if (existing.repo === undefined) {
+                // Registered before repo identities existed. Adopting it here is the
+                // migration; appending instead would give one repo two entries and two
+                // service units, which is the failure this all exists to remove.
+                streams.out(`adopted the existing ghostrail "${existing.name}" for ${repoId}\n`);
+            }
+            else {
+                streams.out(`this repo already has the ghostrail "${existing.name}"; pointed it at this checkout\n` +
+                    `  was: ${existing.path}\n  now: ${path}\n`);
+            }
             return;
         }
         const entry = {
@@ -1309,10 +1322,29 @@ export async function cmdInit(argv, streams, cwd = process.cwd(), env = process.
     }
     streams.out("\n");
     await registerGhostrail(repo, env, streams);
-    streams.out("next: `ghostrail skill` installs the /ghostrail skill for your coding agent,\n");
-    streams.out("      then run `/ghostrail customize` there to tailor the prompts to this repo\n");
+    streams.out(await initNextStepsHint(env, cwd));
     return 0;
 }
+/**
+ * The `next:` hint at the end of a plain `ghostrail init`. Skips telling the
+ * user to run `ghostrail skill` when it is already installed and current, so
+ * a repeat `init` does not repeat advice already followed. Detection reuses
+ * the same plan `ghostrail skill --check` reports on; any failure there is
+ * best-effort only and falls back to the original two-line hint rather than
+ * failing `init`, which already succeeded at scaffolding.
+ */
+async function initNextStepsHint(env, cwd) {
+    const customizeOnly = "next: run `/ghostrail customize` in your coding agent to tailor the prompts to this repo\n";
+    const installAndCustomize = "next: `ghostrail skill` installs the /ghostrail skill for your coding agent,\n" +
+        "      then run `/ghostrail customize` there to tailor the prompts to this repo\n";
+    try {
+        const plan = await planSkillInstall(pathCtx(env, cwd), { scope: "global" });
+        return plan.upToDate ? customizeOnly : installAndCustomize;
+    }
+    catch {
+        return installAndCustomize;
+    }
+}
 /**
  * Parse `ghostrail skill` options. Default scope is `global` (the user's own
  * agent config), because the skill drives ghostrail wherever you are; `--project`
@@ -1511,17 +1543,20 @@ export async function cmdSelfUpdate(argv, streams, deps = {}) {
     // after "updated X -> Y" (the CLI's status) with nothing marking which one
     // it described.
     streams.out("ghostrail:\n");
-    // Resolve `latest` BEFORE installing. This is what makes the "version did not
-    // change" branch below meaningful: with the already-current case ruled out
-    // first, an unchanged version can only mean the install went somewhere PATH
-    // does not resolve. Without this check the two are indistinguishable, and we
-    // used to blame a split install for what was simply nothing to do.
+    // Resolve `latest` BEFORE installing, so "nothing newer existed" is ruled out
+    // before anything else is inferred from an unchanged version.
     const latest = await readLatest();
     if (latest !== undefined && latest === current) {
         streams.out(`  already on the latest version (${current})\n`);
         return finishWithSkill(argv, streams, runSkill);
     }
-    const installResult = await install("latest");
+    // The exact version, not the tag. `npm view` reads the registry while
+    // `npm install` may resolve `latest` from a cached packument, so for a few
+    // minutes after a release the two disagree and npm cheerfully reinstalls the
+    // version already present, exits 0, and leaves nothing to distinguish that
+    // from a failed install. Naming the version closes the window: a stale cache
+    // now produces a real npm error instead of a silent no-op.
+    const installResult = await install(latest ?? "latest");
     if (installResult.exitCode !== 0) {
         streams.err(installResult.stderr || installResult.stdout);
         streams.err(`  update failed (npm exited ${installResult.exitCode})\n`);
@@ -1537,16 +1572,18 @@ export async function cmdSelfUpdate(argv, streams, deps = {}) {
         return 1;
     }
     if (installed === current) {
-        // We only get here having already ruled out "nothing newer existed", so
-        // blaming a split install is sound — unless we never learned what `latest`
-        // is, in which case say that instead of asserting a newer version exists.
-        if (latest === undefined) {
-            streams.err(`  could not determine the latest version; ghostrail is still ${current}\n`);
-        }
-        else {
-            streams.err(`  still on ${current} after updating; the new version went somewhere else\n`);
+        // Which explanation fits is decided by the machine, not assumed. Ruling out
+        // "nothing newer existed" does not leave a split install as the only
+        // possibility, and asserting it while printing two agreeing paths is what
+        // sent an operator looking for a second node install that did not exist.
+        const locations = await (deps.locations ?? probeInstallLocations)();
+        for (const line of describeStalledUpdate({
+            current,
+            ...(latest === undefined ? {} : { wanted: latest }),
+            locations,
+        })) {
+            streams.err(`  ${line}\n`);
         }
-        await reportInstallLocations(streams, deps);
         return 1;
     }
     streams.out(`  updated ${current} -> ${installed}\n`);
@@ -1594,19 +1631,6 @@ async function installedVersion() {
     const version = result.stdout.trim();
     return version.length === 0 ? undefined : version;
 }
-/**
- * Print the two facts that identify a split install: where npm puts global
- * packages, and which `ghostrail` the shell actually runs. When they disagree,
- * that is the whole answer.
- */
-async function reportInstallLocations(streams, deps = {}) {
-    const { npmRoot, which } = await (deps.locations ?? probeInstallLocations)();
-    if (npmRoot !== undefined)
-        streams.err(`  npm installs into: ${npmRoot}\n`);
-    if (which !== undefined)
-        streams.err(`  your shell runs:   ${which}\n`);
-    streams.err("  If those disagree, you have more than one node version and the update landed under a different one.\n");
-}
 /** Ask npm where it installs, and the shell which ghostrail it runs. */
 async function probeInstallLocations() {
     const npm = process.platform === "win32" ? "npm.cmd" : "npm";