ghostrail 0.7.5 → 0.9.0

package/dist/service/manager.js

@@ -0,0 +1,107 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import process from "node:process";
+import { spawnCollect } from "../backend/proc.js";
+import { parseUnitStates, renderSystemdUnit, unitName } from "./unit.js";
+/** Which manager this platform offers, whether or not it is supported. */
+export async function detectManager() {
+    if (process.platform === "darwin") {
+        const launchctl = await spawnCollect(["launchctl", "help"], { timeoutMs: 5_000 });
+        // launchctl exits nonzero for `help`, so presence is what is being tested.
+        return launchctl.exitCode === 127 ? "none" : "launchd";
+    }
+    const systemctl = await spawnCollect(["systemctl", "--user", "--version"], {
+        timeoutMs: 5_000,
+    });
+    return systemctl.exitCode === 0 ? "systemd" : "none";
+}
+/** Where systemd looks for this user's units. */
+export function systemdUnitDir(env = process.env) {
+    const base = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+    return join(base, "systemd", "user");
+}
+/**
+ * Write a unit unless it is already right, or has been edited.
+ *
+ * An edited unit is never overwritten. Same instinct as `init --update`: a
+ * customization is deliberate until proven otherwise, and silently reverting
+ * one is the kind of thing that makes a tool untrustworthy.
+ */
+export async function installUnit(spec, env = process.env) {
+    const unit = unitName(spec.name, spec.path);
+    const dir = systemdUnitDir(env);
+    const file = join(dir, unit);
+    const wanted = renderSystemdUnit(spec);
+    let current;
+    try {
+        current = await readFile(file, "utf8");
+    }
+    catch {
+        current = undefined;
+    }
+    if (current === wanted)
+        return { outcome: "unchanged", unit, file };
+    if (current !== undefined)
+        return { outcome: "hand-edited", unit, file };
+    await mkdir(dir, { recursive: true });
+    await writeFile(file, wanted, "utf8");
+    return { outcome: "written", unit, file };
+}
+/** Run a systemctl user subcommand, returning its exit code and output. */
+async function systemctl(args) {
+    const result = await spawnCollect(["systemctl", "--user", ...args], { timeoutMs: 30_000 });
+    return { code: result.exitCode, out: `${result.stdout}${result.stderr}` };
+}
+/** Reload the manager so a newly written unit is visible. */
+export async function reload() {
+    await systemctl(["daemon-reload"]);
+}
+/** Enable and start a unit. Returns an error message, or undefined on success. */
+export async function enableAndStart(unit) {
+    const result = await systemctl(["enable", "--now", unit]);
+    return result.code === 0 ? undefined : result.out.trim();
+}
+/**
+ * Stop and disable a unit.
+ *
+ * This can genuinely take minutes: an in-flight tick is not interrupted, so the
+ * manager waits out the current agent run. Callers should say so before this
+ * starts rather than letting it look hung.
+ */
+export async function disableAndStop(unit) {
+    const result = await systemctl(["disable", "--now", unit]);
+    if (result.code === 0)
+        return undefined;
+    // A unit that was never installed is not a failure to stop. The goal is that
+    // it is not running, and it is not. Reporting this as an error made `stop` on
+    // a never-started ghostrail look broken.
+    if (/does not exist|not loaded|no such file/i.test(result.out))
+        return undefined;
+    return result.out.trim();
+}
+/** Remove a unit file. Absent is success: the goal is that it is not there. */
+export async function removeUnit(unit, env = process.env) {
+    await rm(join(systemdUnitDir(env), unit), { force: true });
+}
+/** Active state per unit, for the units asked about. */
+export async function unitStates(units) {
+    if (units.length === 0)
+        return new Map();
+    const result = await systemctl(["show", "--property=Id", "--property=ActiveState", ...units]);
+    return parseUnitStates(result.out);
+}
+/** The real one: systemd through `systemctl --user`. */
+export function systemdManager(env = process.env) {
+    return {
+        kind: detectManager,
+        install: (spec) => installUnit(spec, env),
+        enable: async (unit) => {
+            await reload();
+            return enableAndStart(unit);
+        },
+        disable: disableAndStop,
+        states: unitStates,
+    };
+}
+//# sourceMappingURL=manager.js.map

package/dist/service/manager.js.map

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

package/dist/service/unit.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Rendering and naming for the user service units that keep a ghostrail
+ * running. Pure: nothing here touches the disk or shells out, so the awkward
+ * parts (unit naming, the stop timeout) are testable without a service manager.
+ */
+/** Everything a unit file needs. */
+export interface UnitSpec {
+    /** The ghostrail's display name, for the unit description. */
+    name: string;
+    /** Absolute path to the repo. Becomes the working directory. */
+    path: string;
+    /** Absolute path to the ghostrail binary. */
+    exec: string;
+    /** Poll interval, as a duration string like `5m`. */
+    interval: string;
+    /** How long the manager waits for a clean stop, in seconds. */
+    stopTimeoutSec: number;
+}
+/**
+ * The unit file name for a ghostrail: `ghostrail-<slug>-<hash>.service`.
+ *
+ * The hash of the path is not decoration. `name` is display-only and duplicates
+ * are entirely legal: two repos scaffolded from the same template are both
+ * called `code-local`. Keying the unit on the name alone would give them one
+ * unit between them, so starting the second would silently hijack the first.
+ * The identity is the path, so the path is what disambiguates.
+ */
+export declare function unitName(name: string, path: string): string;
+/**
+ * How long the service manager must wait for a clean stop.
+ *
+ * `watchLoop` checks its abort signal *before* each tick and each sleep, so a
+ * SIGTERM arriving mid-tick does not interrupt the running agent: the tick
+ * finishes first. A manager that gives up sooner SIGKILLs a live agent run,
+ * orphaning its container and leaving the tracker issue claimed by a bot that no
+ * longer exists.
+ *
+ * The headroom is there because the agent timeout bounds the agent, not the
+ * tick: provisioning, the gate, and publishing all happen outside it.
+ */
+export declare function stopTimeoutSeconds(timeoutMs: number): number;
+/**
+ * A systemd user unit. Deterministic, so an unchanged unit can be recognized
+ * and an edited one left alone.
+ *
+ * Paths are written as-is: a unit file is not shell, and a path containing a
+ * space is legal in `WorkingDirectory=`.
+ */
+export declare function renderSystemdUnit(spec: UnitSpec): string;
+/**
+ * Parse `systemctl --user show --property=Id --property=ActiveState` for
+ * several units into unit name -> active state.
+ *
+ * Tolerates what the real command emits: records separated by blank lines,
+ * properties in any order, extra properties, and a unit that does not exist
+ * (reported as `inactive` rather than as a failure). A record with no `Id` is
+ * skipped rather than fatal.
+ */
+export declare function parseUnitStates(stdout: string): Map<string, string>;
+//# sourceMappingURL=unit.d.ts.map

package/dist/service/unit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unit.d.ts","sourceRoot":"","sources":["../../src/service/unit.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,oCAAoC;AACpC,MAAM,WAAW,QAAQ;IACvB,8DAA8D;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,cAAc,EAAE,MAAM,CAAC;CACxB;AAWD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG3D;AAQD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAQ5D;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAoBxD;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAoBnE"}

package/dist/service/unit.js

@@ -0,0 +1,111 @@
+import { createHash } from "node:crypto";
+/** Lowercase, non-alphanumeric runs collapsed to `-`, trimmed. */
+function slug(name) {
+    const out = name
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return out.length > 0 ? out : "ghostrail";
+}
+/**
+ * The unit file name for a ghostrail: `ghostrail-<slug>-<hash>.service`.
+ *
+ * The hash of the path is not decoration. `name` is display-only and duplicates
+ * are entirely legal: two repos scaffolded from the same template are both
+ * called `code-local`. Keying the unit on the name alone would give them one
+ * unit between them, so starting the second would silently hijack the first.
+ * The identity is the path, so the path is what disambiguates.
+ */
+export function unitName(name, path) {
+    const hash = createHash("sha256").update(path, "utf8").digest("hex").slice(0, 8);
+    return `ghostrail-${slug(name)}-${hash}.service`;
+}
+/** Headroom over the agent timeout, in seconds. */
+const STOP_HEADROOM_SEC = 300;
+/** Never wait less than this for a stop, however short the configured timeout. */
+const MIN_STOP_SEC = 600;
+/**
+ * How long the service manager must wait for a clean stop.
+ *
+ * `watchLoop` checks its abort signal *before* each tick and each sleep, so a
+ * SIGTERM arriving mid-tick does not interrupt the running agent: the tick
+ * finishes first. A manager that gives up sooner SIGKILLs a live agent run,
+ * orphaning its container and leaving the tracker issue claimed by a bot that no
+ * longer exists.
+ *
+ * The headroom is there because the agent timeout bounds the agent, not the
+ * tick: provisioning, the gate, and publishing all happen outside it.
+ */
+export function stopTimeoutSeconds(timeoutMs) {
+    // Total by construction. The caller reads this from a validated config, so a
+    // negative or non-finite value should be unreachable, but this number is the
+    // one thing standing between a stop and a SIGKILL through a live agent run.
+    // Rendering `TimeoutStopSec=NaN` would make systemd reject the whole unit.
+    if (!Number.isFinite(timeoutMs) || timeoutMs < 0)
+        return MIN_STOP_SEC;
+    const seconds = Math.ceil(timeoutMs / 1000) + STOP_HEADROOM_SEC;
+    return Math.max(seconds, MIN_STOP_SEC);
+}
+/**
+ * A systemd user unit. Deterministic, so an unchanged unit can be recognized
+ * and an edited one left alone.
+ *
+ * Paths are written as-is: a unit file is not shell, and a path containing a
+ * space is legal in `WorkingDirectory=`.
+ */
+export function renderSystemdUnit(spec) {
+    return `${[
+        "[Unit]",
+        `Description=ghostrail factory (${spec.name})`,
+        "Documentation=https://github.com/timothyjordan/ghostrail",
+        "",
+        "[Service]",
+        "Type=simple",
+        `WorkingDirectory=${spec.path}`,
+        // Absolute: a bare `ghostrail` is not on a service manager's PATH, and on
+        // an nvm install the real path is version-specific.
+        `ExecStart=${spec.exec} watch --interval ${spec.interval}`,
+        "Restart=on-failure",
+        "RestartSec=30",
+        // Long enough for an in-flight tick to finish. See stopTimeoutSeconds.
+        `TimeoutStopSec=${spec.stopTimeoutSec}`,
+        "",
+        "[Install]",
+        "WantedBy=default.target",
+    ].join("\n")}\n`;
+}
+/**
+ * Parse `systemctl --user show --property=Id --property=ActiveState` for
+ * several units into unit name -> active state.
+ *
+ * Tolerates what the real command emits: records separated by blank lines,
+ * properties in any order, extra properties, and a unit that does not exist
+ * (reported as `inactive` rather than as a failure). A record with no `Id` is
+ * skipped rather than fatal.
+ */
+export function parseUnitStates(stdout) {
+    const states = new Map();
+    for (const record of stdout.split(/\n\s*\n/)) {
+        let id;
+        let active;
+        for (const line of record.split("\n")) {
+            const eq = line.indexOf("=");
+            if (eq === -1)
+                continue;
+            const key = line.slice(0, eq).trim();
+            const value = line.slice(eq + 1).trim();
+            if (key === "Id")
+                id = value;
+            else if (key === "ActiveState")
+                active = value;
+        }
+        // A record carrying an Id but no ActiveState becomes "unknown" rather than
+        // being dropped: the unit exists, and saying so beats pretending it does
+        // not. A repeated Id keeps the last record, matching how systemd's own
+        // later output would supersede earlier output.
+        if (id !== undefined && id.length > 0)
+            states.set(id, active ?? "unknown");
+    }
+    return states;
+}
+//# sourceMappingURL=unit.js.map

package/dist/service/unit.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ghostrail",
-  "version": "0.7.5",
+  "version": "0.9.0",
   "description": "Open source software factory for coding agents. Config-driven loops, pluggable isolation backends, human merge gate.",
   "keywords": [
     "ai-agents",

package/skill/ghostrail/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: ghostrail
-description: Drive ghostrail (the software factory) from inside this repo. Use when the user types /ghostrail, or asks to set up, customize, check, or run a ghostrail factory — scaffolding ghostrail.toml and prompts, tailoring the scaffolded prompts and gate commands to this codebase, diagnosing a broken setup, or kicking off a run/respond/triage tick.
+description: Drive ghostrail (the software factory) from inside this repo. Use when the user types /ghostrail, or asks to set up, customize, check, or run a ghostrail factory — scaffolding ghostrail.toml and prompts, tailoring the scaffolded prompts and gate commands to this codebase, carrying a later template improvement into prompts you have customized, diagnosing a broken setup, or kicking off a run/respond/triage tick.
 user-invocable: true
-argument-hint: "[customize | init | doctor | status | run | respond | triage]"
+argument-hint: "[customize | init | update | doctor | status | run | respond | triage]"
 license: Apache-2.0
 metadata:
-  version: 0.2.0
+  version: 0.3.0
 allowed-tools:
   - Read
   - Write
@@ -87,25 +87,71 @@ Scaffold the factory into this repo, then hand off to **customize**.
 
 ### Already initialized? Check for template drift
 
-If the repo already has `ghostrail.toml` and `prompts/`, do not re-run a bare
-`init` and report "0 files written" as if nothing were wrong. Run:
+If the repo already has `ghostrail.toml` and prompts, do not re-run a bare
+`init` and report "0 files written" as if nothing were wrong. See **update**
+below.
+
+Never suggest `--force` as the way to take a template update: it overwrites
+every file, destroying the gate commands, tracker filters, and prompt edits that
+**customize** wrote.
+
+---
+
+## update
+
+Carry a template improvement into a repo that has customized its prompts. Run:
+
+```
+<GR> init <template> --update
+```
+
+It writes only files this repo never edited (proved by the baseline in
+`ghostrail.template.json`), and it never touches a customized file. For those it
+prints **signals**: what the template gained that the repo's copy lacks.
 
 ```
-<GR> init <template> --diff
+  ghostrail/prompts/resolve-issue.md
+    customized, and the template gained:
+      placeholder   {{description}}
+      result field  "testPlan"
 ```
 
-It is read-only. It reports each scaffolded file as up to date, locally
-customized, safe to take, a conflict, or missing, using the baseline recorded in
-`ghostrail.template.json`. Summarize the rows that are not up to date, show the
-`diff` command it printed, and offer to merge template changes in by hand.
+Placing those is your job, and it is not a text merge. A customized prompt can
+be a near-total rewrite that still needs the same one-line addition, so port the
+**intent**, not the template's wording:
+
+1. Read the template's copy of the file to see how it uses the signal. The path
+   is printed by `<GR> init <template> --diff`.
+2. Read the repo's copy and find where the same idea belongs *in its structure*.
+3. Add it in the repo's own voice. A placeholder goes where that content is
+   wanted (`{{description}}` under the issue's ID/title/link block). A result
+   field goes on the matching line of the result-document list, with a
+   description written to match the surrounding entries.
+4. Never reformat, reorder, or "tidy" the rest of the file. The customization is
+   deliberate. Your diff should be as small as the signal count implies.
+5. Re-run `<GR> init <template> --update` and confirm it now reports
+   `customized, nothing to take`.
+
+Verify a placeholder actually renders before anyone spends a run on it:
+
+```
+node -e 'import("URL_TO_PROMPT_JS").then(({renderPrompt})=>{
+  const t=require("fs").readFileSync("PATH/TO/PROMPT.md","utf8");
+  const o=renderPrompt(t,{id:"TJ-1",title:"t",url:"u",description:"BODY"});
+  console.log(o.match(/\{\{[a-z]+\}\}/g) ?? "no unrendered placeholders");
+})'
+```
 
-Never suggest `--force` as the way to take a template update: it overwrites every
-file, destroying the gate commands, tracker filters, and prompt edits that
-**customize** wrote. Merging by hand is the correct path.
+Two things to tell the user plainly:
 
-If it reports no recorded baseline, the repo predates provenance. Re-running a
-bare `<GR> init` once adopts a baseline for every file that still matches the
-template exactly, which is safe and improves later diffs.
+- **The installed template is the last published release.** A repo can be
+  current with it and still behind `main`. The `--update` header names the
+  version it compared against; repeat that in your summary.
+- **A repo with no baseline gets signals but no writes.** Without a recorded
+  baseline nothing can be *shown* to be untouched, so `--update` will not
+  overwrite anything. Re-running a bare `<GR> init` once adopts a baseline for
+  every file that still matches the template exactly, which is safe and makes
+  later updates able to write.
 
 ---
 

package/templates/code-local/prompts/resolve-issue.md

@@ -26,10 +26,24 @@ Match the surrounding code: its style, patterns, and test conventions.
 ## Reporting your result (required, do this last)
 Write a JSON file at `.ghostrail/result.json` with exactly one of:
 
-- `{"status":"done","summary":"<what you changed>","type":"<feat|fix|docs|refactor|chore|...>"}`
+- `{"status":"done","summary":"<what changed and why>","testPlan":"<how to check it by hand>","type":"<feat|fix|docs|refactor|chore|...>"}`
 - `{"status":"blocked","questions":"<a real product/design decision you need>"}`
 - `{"status":"failed","error":"<why>"}`
 - `{"status":"noop","reason":"<why nothing needed changing>"}`
 
 `type` is the conventional-commit type for the change; it sets the commit and PR
 title. If you omit it, the factory's configured default is used.
+
+`summary` and `testPlan` are the pull request a human reads, so write them for
+that reader rather than as a log of what you did:
+
+- **`summary`**: one or two sentences on what changed and why, then markdown
+  bullets for the specifics. Do not write a single long paragraph, and do not
+  add headings; the factory supplies its own.
+- **`testPlan`**: the steps someone runs to check this by hand. Concrete
+  commands, what to look at, and what they should see. The gate has already run
+  lint, typecheck, and the unit suite, so do not just repeat those: give the
+  commands that exercise what you actually changed. If the change is not
+  observable by hand (a refactor, a type fix), say what to run instead and what
+  a green result proves.
+

package/templates/content-loop/prompts/draft.md

@@ -25,7 +25,7 @@ strategy). Follow them closely: they define how this work should read.
 ## Reporting your result (required, do this last)
 Write `.ghostrail/result.json` with exactly one of:
 
-- `{"status":"done","summary":"<one-paragraph summary of the draft>"}`
+- `{"status":"done","summary":"<what you drafted and why>","testPlan":"<how to review it>"}`
 - `{"status":"blocked","questions":"<what you need decided>"}`
 - `{"status":"failed","error":"<why>"}`
 - `{"status":"noop","reason":"<why nothing needed changing>"}`