ftown-bridge 0.18.2 → 0.19.1

package/dist/session-store.d.ts

@@ -3,7 +3,10 @@ export declare class SessionStore {
     private readonly sessionsDir;
     private readonly archivePath;
     private readonly writeLocks;
-    constructor(dataDir: string);
+    private readonly maxTerminalLogBytes;
+    constructor(dataDir: string, options?: {
+        maxTerminalLogBytes?: number;
+    });
     /** Per-session data dir (session.json, terminal.log, inbox.jsonl). */
     sessionDir(sessionId: string): string;
     private sessionFilePath;
@@ -12,6 +15,17 @@ export declare class SessionStore {
     loadSession(sessionId: string): Promise<Session | null>;
     listSessions(): Promise<Session[]>;
     appendTerminalData(sessionId: string, data: string): Promise<void>;
+    /**
+     * Cap a terminal.log's on-disk size. Runs inside the per-session write lock,
+     * so it never races an append. The file is allowed to grow to 2x the retained
+     * size before being rewritten down to the tail — this amortises the rewrite
+     * cost while bounding disk use to at most 2x `maxTerminalLogBytes` per session.
+     * The partial first line of the retained tail is dropped so consumers never
+     * start mid-line (or mid-escape-sequence), and a one-line marker records that
+     * older output was discarded. Best-effort: any failure is swallowed so it can
+     * never poison the write-lock chain and stall future appends.
+     */
+    private trimTerminalLogIfNeeded;
     deleteSession(sessionId: string): Promise<void>;
     /** Append a tombstone for a removed session to <dataDir>/archive.jsonl. */
     archiveSession(session: Session): Promise<void>;

package/dist/session-store.js

@@ -1,13 +1,29 @@
-import { readFile, writeFile, mkdir, readdir, appendFile, rm, truncate } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, readdir, appendFile, rm, truncate, stat, open, rename } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { existsSync } from 'node:fs';
+/**
+ * Retained tail size for a session's terminal.log. A misbehaving child (e.g. a
+ * TUI stuck in a runaway repaint loop) can otherwise stream unbounded output
+ * and grow this file without limit — observed in the wild at 2.5 GB and still
+ * climbing, which also makes the full-file `loadTerminalLog` read exceed V8's
+ * max string length and throw. The on-disk file is only ever consumed as
+ * "recent output" (download/search); the live screen is driven by a separate
+ * in-memory emulator, so keeping just the tail is lossless for viewers.
+ */
+const DEFAULT_MAX_TERMINAL_LOG_BYTES = 64 * 1024 * 1024;
+const NEWLINE = 0x0a;
 export class SessionStore {
     sessionsDir;
     archivePath;
     writeLocks = new Map();
-    constructor(dataDir) {
+    maxTerminalLogBytes;
+    constructor(dataDir, options = {}) {
         this.sessionsDir = join(dataDir, 'sessions');
         this.archivePath = join(dataDir, 'archive.jsonl');
+        const envCap = Number(process.env.FTOWN_MAX_TERMINAL_LOG_BYTES);
+        this.maxTerminalLogBytes =
+            options.maxTerminalLogBytes ??
+                (Number.isFinite(envCap) && envCap > 0 ? envCap : DEFAULT_MAX_TERMINAL_LOG_BYTES);
     }
     /** Per-session data dir (session.json, terminal.log, inbox.jsonl). */
     sessionDir(sessionId) {
@@ -53,10 +69,54 @@ export class SessionStore {
         await mkdir(dir, { recursive: true });
         const filePath = this.terminalLogPath(sessionId);
         const prevLock = this.writeLocks.get(sessionId) ?? Promise.resolve();
-        const newLock = prevLock.then(() => appendFile(filePath, data, 'utf-8'));
+        const newLock = prevLock
+            .then(() => appendFile(filePath, data, 'utf-8'))
+            .then(() => this.trimTerminalLogIfNeeded(filePath));
         this.writeLocks.set(sessionId, newLock);
         await newLock;
     }
+    /**
+     * Cap a terminal.log's on-disk size. Runs inside the per-session write lock,
+     * so it never races an append. The file is allowed to grow to 2x the retained
+     * size before being rewritten down to the tail — this amortises the rewrite
+     * cost while bounding disk use to at most 2x `maxTerminalLogBytes` per session.
+     * The partial first line of the retained tail is dropped so consumers never
+     * start mid-line (or mid-escape-sequence), and a one-line marker records that
+     * older output was discarded. Best-effort: any failure is swallowed so it can
+     * never poison the write-lock chain and stall future appends.
+     */
+    async trimTerminalLogIfNeeded(filePath) {
+        try {
+            const { size } = await stat(filePath);
+            if (size <= this.maxTerminalLogBytes * 2) {
+                return;
+            }
+            const keep = this.maxTerminalLogBytes;
+            const fh = await open(filePath, 'r');
+            let tail;
+            try {
+                const buf = Buffer.alloc(keep);
+                const { bytesRead } = await fh.read(buf, 0, keep, size - keep);
+                tail = buf.subarray(0, bytesRead);
+            }
+            finally {
+                await fh.close();
+            }
+            // Drop the (almost certainly partial) first line so the retained log
+            // begins on a clean line boundary.
+            const nl = tail.indexOf(NEWLINE);
+            const body = nl >= 0 ? tail.subarray(nl + 1) : tail;
+            const marker = Buffer.from(`[ftown] terminal.log truncated — retaining last ${keep} bytes\r\n`, 'utf-8');
+            // Rewrite via a temp file + atomic rename so a concurrent full-file reader
+            // (loadTerminalLog runs outside the lock) never observes a partial file.
+            const tmpPath = `${filePath}.trim-${process.pid}.tmp`;
+            await writeFile(tmpPath, Buffer.concat([marker, body]));
+            await rename(tmpPath, filePath);
+        }
+        catch (err) {
+            console.error(`[SessionStore] Failed to trim terminal log ${filePath}:`, err);
+        }
+    }
     async deleteSession(sessionId) {
         const dir = this.sessionDir(sessionId);
         if (existsSync(dir)) {

package/dist/session-store.js.map

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

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export type ShellType = 'claude' | 'cursor' | 'codex' | 'shell' | 'zai' | 'kimi' | 'opencode' | 'deepseek' | 'fireworks';
+export type ShellType = 'claude' | 'cursor' | 'codex' | 'shell' | 'zai' | 'kimi' | 'opencode' | 'deepseek' | 'fireworks' | 'grok';
 export type SessionRuntime = 'tmux' | 'direct';
 export interface Session {
     id: string;
@@ -26,7 +26,7 @@ export type SessionStatus = 'pending' | 'running' | 'completed' | 'error';
 export interface ArchivedSession extends Session {
     removedAt: string;
 }
-export type LoopHarness = 'claude' | 'cursor' | 'codex' | 'opencode' | 'shell';
+export type LoopHarness = 'claude' | 'cursor' | 'codex' | 'grok' | 'opencode' | 'shell';
 export type LoopRunStatus = 'ok' | 'error' | 'running' | 'skipped';
 export type LoopSchedule = {
     kind: 'interval';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ftown-bridge",
-  "version": "0.18.2",
+  "version": "0.19.1",
   "description": "CLI bridge for ftown — generic PTY-over-Centrifugo relay",
   "type": "module",
   "main": "dist/index.js",

package/skills/factory/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: factory
+description: deploy and manage a per-project AI software factory (init/up/down/status/teardown) — FTS ticket pipeline + ftown loops. Trigger on "factory init", "deploy a factory", "factory status", "pause the factory".
+---
+
+<!-- Vendored from the ffactory repo (skills/factory + factory-template); sync changes there first. -->
+
+# Factory
+
+You are a capable model helping a human deploy and operate a per-project AI software
+factory: a `fticket` (`fts`) ticket pipeline driven by three ftown loops (a dispatcher
+that spawns stage workers, a preflight-guarded interval triage sweep, and a daily digest
+report). This skill is procedures, not narrative — follow the exact commands. It runs
+inside the target project repo (`$REPO` = repo root, resolved via
+`git rev-parse --show-toplevel`).
+
+## Layout
+
+- `factory/` — checked into the project repo, the factory's *definition*:
+  `factory.yaml` (stages, limits, triage config), `skills/*.md` (stage worker briefings +
+  `_protocol.md`), `bin/dispatch.py`.
+- `.ffactory/` — gitignored, the factory's *runtime state*: `factory.db` (fts sqlite),
+  `tickets/<n>/` (per-ticket artifact folders), `worktrees/` (implement-stage checkouts),
+  `dispatch.cursor` (dispatcher bookmark). Disposable — deleting it loses history but not
+  the factory's definition.
+
+## init
+
+Idempotent. If `factory/` already exists in `$REPO`, stop and tell the user the factory is
+already initialized (point them at `status`/`up`/`down` instead) — do not overwrite.
+
+1. **Preconditions.** Confirm `$REPO` is a git repo. Run `~/.ftown/ftown-sessions list` —
+   if it errors, the bridge is down; stop and tell the user to start it first. Confirm
+   `uv` is on PATH.
+2. **Install fticket.** `uv tool install fticket` (or `uv tool upgrade fticket` if already
+   installed). Verify with `fts --help`.
+3. **Copy the template.**
+   ```bash
+   cp -r ~/.ftown/skills/factory/factory-template "$REPO/factory"
+   ```
+   `factory/bin` moves in as-is (no edits). Ask the user for: project name (default: the
+   repo directory's basename), an operator ftown session id (optional — default `-`, no
+   operator mail), and any stage routing tweaks (harness/model/max_workers per stage).
+   Edit `factory/factory.yaml` with their answers.
+4. **Gitignore + state dirs.** Append `.ffactory/` to `$REPO/.gitignore` (create the file
+   if absent). `mkdir -p "$REPO/.ffactory/tickets"`.
+5. **Init the ticket db**, reading stage order and limits back out of the edited
+   `factory.yaml`:
+   ```bash
+   fts init --db .ffactory/factory.db \
+     --stages groom,design,implement,review,qa,pr \
+     --bounce-limit 3 --claim-ttl-ms 1800000
+   ```
+   (substitute the actual stage names in yaml order, `limits.bounce_limit`, and
+   `limits.claim_ttl_ms`).
+6. **Register the loops, grouped under one factory label.** The `--group` flag folds all
+   loops together in the ftown dashboard and requires ftown bridge PR #29. If
+   `loop create` rejects `--group` as an unknown flag, tell the user their bridge is out
+   of date and needs updating — do not silently drop the flag and register ungrouped.
+
+   Dispatcher (interval loop, runs the Python dispatcher every tick):
+   ```bash
+   ~/.ftown/ftown-sessions loop create \
+     --name "<project>-dispatch" --every 30s --shell shell --workdir "$REPO" \
+     --group "Factory: <project>" --max-runtime 10m --retention 10 \
+     --preflight "~/.local/bin/fts queues --db $REPO/.ffactory/factory.db --json | python3 -c 'import json,sys; qs=json.load(sys.stdin); sys.exit(0 if any(q.get(\"queued\",0)+q.get(\"claimed\",0)+q.get(\"in_progress\",0)+q.get(\"blocked\",0) for q in qs) else 1)'" \
+     --task "uv run --python 3.13 --with fticket,pyyaml python factory/bin/dispatch.py"
+   ```
+   (`--every` from `limits.dispatch_every`. The preflight skips the tick — no shell
+   session — while no ticket is queued/claimed/in_progress/blocked, so an idle factory
+   costs nothing. A resting `rejected`/`dead_letter` ticket doesn't wake it: those belong
+   to explicit chaining and triage respectively.)
+
+   Triage (interval loop with a preflight skip guard — only spawns a session when there
+   is dead-letter/orphan work; requires ftown bridge >= 0.18.0 for cheap preflight skips —
+   on 0.17 the preflight still works but bloats run history since a skip still logs a
+   run):
+   ```bash
+   ~/.ftown/ftown-sessions loop create \
+     --name "<project>-triage" --every 10m --shell claude --model sonnet \
+     --workdir "$REPO" --group "Factory: <project>" --retention 10 \
+     --preflight "~/.local/bin/fts triage --db $REPO/.ffactory/factory.db --json | python3 -c 'import json,sys; d=json.load(sys.stdin); sys.exit(0 if d[\"dead_letter\"] or d[\"orphans\"] else 1)'" \
+     --task "FTS_DB=<abs path to .ffactory/factory.db> REPO_ROOT=<abs $REPO> OPERATOR_SESSION=<value or -> — Read and follow factory/skills/triage.md."
+   ```
+   (`--every`/`--shell`/`--model` from `triage.every`/`triage.harness`/`triage.model`.)
+   The preflight exits 0 (work exists → run the session) when `fts triage --json` reports
+   any dead_letter or orphan tickets, and exits 1 (healthy → skip, no session spawned)
+   otherwise. The triage briefing must set the three task variables literally;
+   `triage.md` treats a missing variable as fatal.
+
+   Digest (daily cron loop, shift report mailed to the operator) — register this loop
+   ONLY when `operator_session` in `factory.yaml` is not `-`; skip it entirely otherwise,
+   since there is nowhere to mail the digest:
+   ```bash
+   ~/.ftown/ftown-sessions loop create \
+     --name "<project>-digest" --cron "0 9 * * *" --shell claude --model sonnet \
+     --workdir "$REPO" --group "Factory: <project>" --retention 5 \
+     --task "FTS_DB=<abs path to .ffactory/factory.db> REPO_ROOT=<abs $REPO> OPERATOR_SESSION=<operator> — Read and follow factory/skills/digest.md."
+   ```
+   (`--cron`/`--shell`/`--model` from `digest.cron`/`digest.harness`/`digest.model`.)
+7. **Wrap up.** Suggest the user commit `factory/` (not `.ffactory/`). Show them how to
+   create the first ticket:
+   ```bash
+   mkdir -p .ffactory/tickets/1
+   # write .ffactory/tickets/1/request.md with the ask
+   fts create --db .ffactory/factory.db --title "<title>" --stage groom \
+     --folder .ffactory/tickets/1
+   ```
+   and how to watch it: `fts serve --db .ffactory/factory.db --port 8377` (dashboard).
+
+## up / down
+
+Resume or pause every registered loop by name. Loops don't expose lookup-by-name
+directly, so filter `loops` output for the project's `--group` label (`Factory:
+<project>`) to get ids first — this naturally covers whichever loops are actually
+registered (dispatch + triage always; digest only if an operator is configured):
+
+```bash
+~/.ftown/ftown-sessions loops                      # find ids for all loops in group "Factory: <project>"
+~/.ftown/ftown-sessions loop resume <loop-id>      # up — repeat for each loop id found
+~/.ftown/ftown-sessions loop pause  <loop-id>      # down — repeat for each loop id found
+```
+
+## status
+
+Report all of:
+
+1. `fts board --db .ffactory/factory.db` — ticket counts by stage.
+2. `fts queues --db .ffactory/factory.db` — per-stage claim queues.
+3. `fts doctor --db .ffactory/factory.db` — health checks (flag any failure first).
+4. `~/.ftown/ftown-sessions loop runs <loop-id>` for every loop id registered under
+   `Factory: <project>` (dispatch, triage, and digest if present) — last few runs of
+   each, success/error. For triage specifically, also check `loop get <triage-id>` for
+   `lastSkipAt`/`lastSkipReason` — frequent skips are healthy (the preflight guard found
+   no dead-letter/orphan work).
+5. Active workers: `~/.ftown/ftown-sessions list` filtered to names starting with
+   `<project>-t` (worker sessions the dispatcher spawned, distinct from the loop names
+   themselves which start with `<project>-dispatch`/`<project>-triage`/`<project>-digest`).
+
+## run-now
+
+Force an immediate dispatcher tick without waiting for the interval:
+```bash
+~/.ftown/ftown-sessions loop run <dispatch-loop-id>
+```
+
+## teardown
+
+Confirm with the user first — this is destructive to scheduling, distinct from deleting
+data.
+
+1. Pause then delete every loop registered under `Factory: <project>`: `loop pause <id>`
+   then `loop delete <id>` for dispatch, triage, and digest (if it was registered).
+2. Remind the user: `.ffactory/` is disposable runtime state (db, tickets, worktrees) —
+   only delete it if they explicitly confirm, since it's the ticket history. `factory/`
+   is the checked-in definition — keep it (removing it is a separate, deliberate repo
+   change, not part of teardown).
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+| --- | --- |
+| `ftown-sessions list` errors at any step | Bridge is down — start the ftown bridge before retrying. |
+| `loop create --group` rejected as unknown flag | Bridge predates ftown PR #29 — tell the user to update the bridge; do not drop `--group` and register loops ungrouped. |
+| Workers never spawn even though tickets are queued | Check `loop runs <dispatch-id>` for run status first, then the dispatcher's own stderr (surfaced in the run's session output) for `dispatch.py` errors — e.g. `max_sessions` cap reached, or a claim that keeps expiring. |
+| A ticket looks stuck in one stage | `fts why --db .ffactory/factory.db <id>` — gives a stuck diagnosis (expired claim, bounce-limit hit, missing resource lease, etc.) without needing to read the raw db. |
+| Triage never fires | Check `loop get <triage-id>` for `lastSkipAt`/`lastSkipReason` — preflight guard skipping is healthy when there are no dead-letter/orphan tickets; only worry if `fts triage --json` shows work but the loop still skips. |