@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/session-link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-link.js","sourceRoot":"","sources":["../src/session-link.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,mFAAmF;AACnF,qFAAqF;AAErF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,aAAa,CAAA;AAEnD,kFAAkF;AAClF,MAAM,UAAU,uBAAuB,CAAC,QAAgB;IACtD,OAAO,QAAQ,CAAC,QAAQ,CAAC,sBAAsB,CAAC,CAAA;AAClD,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,kBAAkB,CAAC,QAAgB,EAAE,SAAiB;IACpE,OAAO,QAAQ,CAAC,KAAK,CAAC,sBAAsB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;AAC/D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,wBAAwB,CAAA"}

package/dist/sessions.d.ts

@@ -0,0 +1,77 @@
+import { SESSIONS_DIR, type StoreFs } from './store/index.js';
+import { type GitRunner } from './project.js';
+/**
+ * Committed session history (#1179): where a project's finished runs are archived so they survive
+ * the repo being cleaned.
+ *
+ * The bug this exists for: run state was written to `.the-framework/runs/`, which the install-time
+ * `.gitignore` keeps untracked, so `git clean -fdx` — an ordinary thing to do to a repo — deleted
+ * every session a project had ever run. Nothing was recoverable, because nothing had ever been
+ * committed.
+ *
+ * Scoped per user, as `.the-framework/<user>/sessions/`, rather than one shared directory. Two
+ * people working the same repo would otherwise write the same paths from different machines and
+ * conflict on every merge; under their own directory their histories simply sit side by side. The
+ * list being visible to the whole team is the intended outcome, not a leak — see the issue.
+ *
+ * The identity is the git `user.email` already configured in the repo, so there is nothing new to
+ * set up and the directory matches the name on the commits.
+ */
+/** The directory, under a user's own directory, that holds their archived runs. */
+export { SESSIONS_DIR };
+/** Where a run's history goes when git has no identity configured. */
+export declare const ANONYMOUS_USER_DIR = "anonymous";
+/**
+ * An email as a directory name: lowercased, with anything outside a conservative set replaced by
+ * `-`. The result must start with a letter or digit, which is what rules out `.`, `..` and dotfile
+ * names — this value comes from repo configuration and is joined onto a path, so a name that could
+ * climb out of the directory is the one thing that must be impossible. Anything that cannot be made
+ * to fit falls back to {@link ANONYMOUS_USER_DIR} rather than to a guess.
+ */
+export declare function userDirName(email: string | undefined): string;
+/** The `.the-framework/<user>/sessions` directory under a project root. */
+export declare function sessionsDir(cwd: string, user: string): string;
+/**
+ * The `.the-framework/.gitignore` rules that make every user's sessions tracked. Three lines, not
+ * one: the seeded allow-list ignores everything with `*`, and git never descends into an ignored
+ * directory, so each directory on the way down has to be re-included before the files under it can
+ * be. Same shape as the conversations rules (#908), which this sits beside.
+ *
+ * User-agnostic on purpose (#1312). Naming each user meant every person who ever ran a session in
+ * the repo appended their own three lines to a *tracked* file: their checkout went dirty, the next
+ * safety commit swept the edit into a branch, and two machines doing it near each other conflicted.
+ * A glob covers everyone, including people who have not run anything yet, so the file is written
+ * once and then never again.
+ *
+ * A star matches one path segment and never a slash, so the sessions rule reaches exactly
+ * `<user>/sessions/` and not `worktrees/<run>/sessions/`. The transient siblings stay ignored
+ * either way: un-ignoring a directory only lets git descend into it, and the bare `*` still
+ * ignores every file it finds there.
+ */
+export declare function sessionsGitignore(): string;
+/**
+ * Drop the per-user session rules, keeping every other line.
+ *
+ * Only users the file actually names a `sessions` rule for are stripped, and only those three
+ * exact lines. The conversations rules (#908) are a literal directory name rather than a user, so
+ * they never match, and a hand-written rule this does not recognize is left where it is.
+ */
+export declare function withoutPerUserRules(md: string): string;
+/**
+ * Make sure `.the-framework/.gitignore` un-ignores archived sessions, returning whether it wrote.
+ * Done lazily on archive rather than at install time: the ignore file is seeded once and only when
+ * absent, so every repo activated before this feature carries the old allow-list.
+ *
+ * Writes at most twice in a repo's life, and usually once: a file already on the glob form is left
+ * alone, and a file still naming users is upgraded to the glob form in place — the per-user lines
+ * come out in the same write that puts the glob in, so the churn (#1312) ends rather than being
+ * added to. `user` no longer selects the rules; it stays because the caller has it and a future
+ * rule may need it again.
+ *
+ * Only a file we recognize is touched; anything hand-edited beyond recognition is left alone.
+ */
+export declare function ensureSessionsIgnored(cwd: string, _user: string, fs?: StoreFs): Promise<boolean>;
+export declare function resolveUserDir(cwd: string, git?: GitRunner): Promise<string>;
+/** Drop the {@link resolveUserDir} cache. For tests, and for a daemon that outlives a config change. */
+export declare function forgetUserDirs(): void;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAGA,OAAO,EAAe,YAAY,EAAE,KAAK,OAAO,EAAE,MAAM,kBAAkB,CAAA;AAC1E,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AAE5D;;;;;;;;;;;;;;;;GAgBG;AAEH,mFAAmF;AACnF,OAAO,EAAE,YAAY,EAAE,CAAA;AAEvB,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,cAAc,CAAA;AAQ7C;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQ7D;AAED,2EAA2E;AAC3E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAUD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAQtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,GAAE,OAAuB,GAAG,OAAO,CAAC,OAAO,CAAC,CAarH;AAYD,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,SAA2B,GAAG,OAAO,CAAC,MAAM,CAAC,CAOnG;AAED,wGAAwG;AACxG,wBAAgB,cAAc,IAAI,IAAI,CAErC"}

package/dist/sessions.js

@@ -0,0 +1,146 @@
+import { join } from 'node:path';
+import { THE_FRAMEWORK_DIR } from './framework-dir.js';
+import { gitignorePath, LOGS_GITIGNORE } from './logs.js';
+import { nodeStoreFs, SESSIONS_DIR } from './store/index.js';
+import { nodeGitRunner } from './project.js';
+/**
+ * Committed session history (#1179): where a project's finished runs are archived so they survive
+ * the repo being cleaned.
+ *
+ * The bug this exists for: run state was written to `.the-framework/runs/`, which the install-time
+ * `.gitignore` keeps untracked, so `git clean -fdx` — an ordinary thing to do to a repo — deleted
+ * every session a project had ever run. Nothing was recoverable, because nothing had ever been
+ * committed.
+ *
+ * Scoped per user, as `.the-framework/<user>/sessions/`, rather than one shared directory. Two
+ * people working the same repo would otherwise write the same paths from different machines and
+ * conflict on every merge; under their own directory their histories simply sit side by side. The
+ * list being visible to the whole team is the intended outcome, not a leak — see the issue.
+ *
+ * The identity is the git `user.email` already configured in the repo, so there is nothing new to
+ * set up and the directory matches the name on the commits.
+ */
+/** The directory, under a user's own directory, that holds their archived runs. */
+export { SESSIONS_DIR };
+/** Where a run's history goes when git has no identity configured. */
+export const ANONYMOUS_USER_DIR = 'anonymous';
+/**
+ * Longest directory name we will make from an email. Well past any real address, and short enough
+ * that the archive paths under it stay inside the path limits of every platform we run on.
+ */
+const MAX_USER_DIR = 64;
+/**
+ * An email as a directory name: lowercased, with anything outside a conservative set replaced by
+ * `-`. The result must start with a letter or digit, which is what rules out `.`, `..` and dotfile
+ * names — this value comes from repo configuration and is joined onto a path, so a name that could
+ * climb out of the directory is the one thing that must be impossible. Anything that cannot be made
+ * to fit falls back to {@link ANONYMOUS_USER_DIR} rather than to a guess.
+ */
+export function userDirName(email) {
+    const cleaned = (email ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9@._+-]/g, '-');
+    return cleaned.length > 0 && cleaned.length <= MAX_USER_DIR && /^[a-z0-9][a-z0-9@._+-]*$/.test(cleaned)
+        ? cleaned
+        : ANONYMOUS_USER_DIR;
+}
+/** The `.the-framework/<user>/sessions` directory under a project root. */
+export function sessionsDir(cwd, user) {
+    return join(cwd, THE_FRAMEWORK_DIR, user, SESSIONS_DIR);
+}
+/**
+ * The `.the-framework/.gitignore` rules that make every user's sessions tracked. Three lines, not
+ * one: the seeded allow-list ignores everything with `*`, and git never descends into an ignored
+ * directory, so each directory on the way down has to be re-included before the files under it can
+ * be. Same shape as the conversations rules (#908), which this sits beside.
+ *
+ * User-agnostic on purpose (#1312). Naming each user meant every person who ever ran a session in
+ * the repo appended their own three lines to a *tracked* file: their checkout went dirty, the next
+ * safety commit swept the edit into a branch, and two machines doing it near each other conflicted.
+ * A glob covers everyone, including people who have not run anything yet, so the file is written
+ * once and then never again.
+ *
+ * A star matches one path segment and never a slash, so the sessions rule reaches exactly
+ * `<user>/sessions/` and not `worktrees/<run>/sessions/`. The transient siblings stay ignored
+ * either way: un-ignoring a directory only lets git descend into it, and the bare `*` still
+ * ignores every file it finds there.
+ */
+export function sessionsGitignore() {
+    return `!*/\n!*/${SESSIONS_DIR}/\n!*/${SESSIONS_DIR}/**\n`;
+}
+/** The glob rule whose presence means a file is already on the #1312 form. */
+const GLOB_RULE = `!*/${SESSIONS_DIR}/**`;
+/** `!<user>/`, `!<user>/sessions/` and `!<user>/sessions/**` for one named user. */
+function perUserRules(user) {
+    return [`!${user}/`, `!${user}/${SESSIONS_DIR}/`, `!${user}/${SESSIONS_DIR}/**`];
+}
+/**
+ * Drop the per-user session rules, keeping every other line.
+ *
+ * Only users the file actually names a `sessions` rule for are stripped, and only those three
+ * exact lines. The conversations rules (#908) are a literal directory name rather than a user, so
+ * they never match, and a hand-written rule this does not recognize is left where it is.
+ */
+export function withoutPerUserRules(md) {
+    const lines = md.split('\n');
+    const users = lines
+        .map(line => /^!(.+)\/sessions\/\*\*$/.exec(line.trim())?.[1])
+        .filter((user) => user !== undefined && user !== '*');
+    if (!users.length)
+        return md;
+    const drop = new Set(users.flatMap(perUserRules));
+    return lines.filter(line => !drop.has(line.trim())).join('\n');
+}
+/**
+ * Make sure `.the-framework/.gitignore` un-ignores archived sessions, returning whether it wrote.
+ * Done lazily on archive rather than at install time: the ignore file is seeded once and only when
+ * absent, so every repo activated before this feature carries the old allow-list.
+ *
+ * Writes at most twice in a repo's life, and usually once: a file already on the glob form is left
+ * alone, and a file still naming users is upgraded to the glob form in place — the per-user lines
+ * come out in the same write that puts the glob in, so the churn (#1312) ends rather than being
+ * added to. `user` no longer selects the rules; it stays because the caller has it and a future
+ * rule may need it again.
+ *
+ * Only a file we recognize is touched; anything hand-edited beyond recognition is left alone.
+ */
+export async function ensureSessionsIgnored(cwd, _user, fs = nodeStoreFs()) {
+    const path = gitignorePath(cwd);
+    const rules = sessionsGitignore();
+    if (!(await fs.exists(path))) {
+        await fs.write(path, LOGS_GITIGNORE + rules);
+        return true;
+    }
+    const current = await fs.read(path);
+    if (current.includes(GLOB_RULE))
+        return false;
+    if (!current.includes('!LOGS.md'))
+        return false;
+    const pruned = withoutPerUserRules(current);
+    await fs.write(path, pruned.endsWith('\n') ? pruned + rules : pruned + '\n' + rules);
+    return true;
+}
+/**
+ * The directory name for the identity this repo commits under, from `git config user.email`.
+ *
+ * Cached per repo for the process's life: it is read on every archive, it changes about as often
+ * as a git identity does, and a run that outlived a config change would only mean the next run
+ * files itself correctly. A missing or unreadable identity yields {@link ANONYMOUS_USER_DIR}, so
+ * history is still kept — filing it under a placeholder is strictly better than dropping it.
+ */
+const cache = new Map();
+export async function resolveUserDir(cwd, git = nodeGitRunner()) {
+    const hit = cache.get(cwd);
+    if (hit !== undefined)
+        return hit;
+    const email = await git(['config', 'user.email'], cwd).catch(() => '');
+    const dir = userDirName(email.trim());
+    cache.set(cwd, dir);
+    return dir;
+}
+/** Drop the {@link resolveUserDir} cache. For tests, and for a daemon that outlives a config change. */
+export function forgetUserDirs() {
+    cache.clear();
+}
+//# sourceMappingURL=sessions.js.map

package/dist/sessions.js.map

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

package/dist/spike-locks.d.ts

@@ -0,0 +1,75 @@
+import { type GitRunner } from './project.js';
+import type { SpikeAssignment } from './auto-pm.js';
+/** The first line of a placeholder sibling: the claim, naming the agent that holds it. */
+export declare const SPIKE_LOCK_PREFIX = "PENDING:";
+/**
+ * How old a PENDING lock must be before it is presumed dead and released. Generous against the
+ * slowest live path — spiking and planning can take hours, on top of a cloud queue — because a
+ * lock released under a live agent re-opens the double-work window the lock exists to close,
+ * while a dead agent's ticket only waits one interval longer. This is a bug-recovery mechanism
+ * that ideally never fires (#1364 review), so erring long costs nearly nothing.
+ */
+export declare const SPIKE_LOCK_STALE_MS: number;
+/** Whether a sibling's content is a PENDING placeholder rather than a real spike or plan. */
+export declare function isSpikeLock(md: string): boolean;
+/** What a lock file holds: the claim line and nothing else, so the check above stays trivial. */
+export declare function spikeLockContent(agentId: string): string;
+/** The commit a batch of locks lands as. Names the count so the history reads as what happened. */
+export declare function lockMessage(count: number): string;
+/** The commit a release lands as. */
+export declare function releaseMessage(count: number): string;
+/** Injectable seams so both operations are unit-testable off disk, git, and GitHub. */
+export interface SpikeLockDeps {
+    git?: GitRunner;
+    /** Write one lock file (default `fs.writeFile`). */
+    write?: (path: string, content: string) => Promise<void>;
+    /** Read one sibling (default `fs.readFile`); a rejection reads as "not a lock". */
+    read?: (path: string) => Promise<string>;
+    /** Delete one lock file (default `fs.rm`). */
+    remove?: (path: string) => Promise<void>;
+    /** List `tickets/` (default `fs.readdir`); a rejection reads as an empty directory. */
+    list?: (dir: string) => Promise<string[]>;
+    /**
+     * Whether any open PR touches `file` (#1313's read, reused): a finished agent's PR carries the
+     * real sibling, so an open one keeps the lock however old it is. `undefined` means the answer
+     * could not be read, which also keeps the lock — releasing on a `gh` hiccup would re-open the
+     * double-work window over a network blip.
+     */
+    prTouches?: (cwd: string, file: string) => Promise<boolean | undefined>;
+    /** Clock, injectable for tests. */
+    now?: () => number;
+    /** Override {@link SPIKE_LOCK_STALE_MS}. */
+    staleMs?: number;
+    /** Progress line. */
+    log?: (message: string) => void;
+}
+/**
+ * Claim `assignments`' tickets for their agents: write both placeholder siblings per ticket,
+ * commit the whole batch in one pathspec-scoped commit, and push it to origin's default branch
+ * ({@link pushLockCommit}). Resolves the subset actually locked — a ticket whose sibling appeared since the candidates
+ * were enumerated is skipped, not overwritten: an existing file is someone's claim or someone's
+ * work, and either outranks this batch.
+ *
+ * A batch whose commit failed is rolled back (the written files removed) and resolves `[]`:
+ * uncommitted placeholders in the user's checkout would be noise git blames on nobody. A batch
+ * whose *push* failed is kept and resolved as locked — the commit still guards every run forked
+ * from this checkout, which is the common case, and the sweep should not stand a healthy local
+ * fan-out down over a network blip. The push is what closes the cross-machine window (#1320), so
+ * its failure is logged rather than swallowed.
+ *
+ * Never throws: this runs on a background tick with nothing to catch it.
+ */
+export declare function acquireSpikeLocks(cwd: string, assignments: readonly SpikeAssignment[], deps?: SpikeLockDeps): Promise<SpikeAssignment[]>;
+/**
+ * Release the PENDING locks whose agents are presumed dead, so a crashed spike does not brick its
+ * ticket forever. A lock is stale exactly when all three hold (#1327's rule): its content is still
+ * the placeholder, no open PR touches it (a finished agent's PR carries the real sibling — the
+ * #1313 claim takes over from here), and its last commit is older than {@link SPIKE_LOCK_STALE_MS}.
+ * An *uncommitted* placeholder is left alone: it is a batch being acquired right now, or a commit
+ * failure {@link acquireSpikeLocks} already rolled back.
+ *
+ * Deletions land as one pathspec-scoped commit, pushed best-effort like the acquisition.
+ * Resolves the released tickets' filenames. Never throws.
+ */
+export declare function releaseStaleSpikeLocks(cwd: string, deps?: SpikeLockDeps): Promise<string[]>;
+//# sourceMappingURL=spike-locks.d.ts.map

package/dist/spike-locks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spike-locks.d.ts","sourceRoot":"","sources":["../src/spike-locks.ts"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AAG5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAgBnD,0FAA0F;AAC1F,eAAO,MAAM,iBAAiB,aAAa,CAAA;AAE3C;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,QAAqB,CAAA;AAErD,6FAA6F;AAC7F,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,mGAAmG;AACnG,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,qCAAqC;AACrC,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,uFAAuF;AACvF,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,oDAAoD;IACpD,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACxD,mFAAmF;IACnF,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACxC,8CAA8C;IAC9C,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IACxC,uFAAuF;IACvF,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IACzC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAA;IACvE,mCAAmC;IACnC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;IAClB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,qBAAqB;IACrB,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;CAChC;AAmCD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,SAAS,eAAe,EAAE,EACvC,IAAI,GAAE,aAAkB,GACvB,OAAO,CAAC,eAAe,EAAE,CAAC,CAqC5B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAyDrG"}

package/dist/spike-locks.js

@@ -0,0 +1,208 @@
+import { readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { nodeGitRunner } from './project.js';
+import { cachedOpenPrFilePatches } from './dashboard/gh.js';
+import { TICKETS_DIR } from './tickets.js';
+// The PENDING lock for concurrent spike agents (#1327).
+//
+// A batch of Spike & plan agents must not double-work a ticket, and the guard cannot be the
+// daemon's memory: a hands-off web run's local process ends at the hand-off (#1253), another
+// machine's daemon never shared this one's memory at all, and the #1313 PR-diff claims only start
+// once a PR exists. So the claim is made where every agent already looks — the ticket's own
+// sibling files. Before an agent starts, its `.spike.md` and `.plan.md` are created as
+// placeholders reading `PENDING:<AGENT_ID>`, committed in one batch and pushed to the default
+// branch. A file that exists is a spike the stock prompt skips, so the lock needs no cooperation
+// from anyone who has not heard of it.
+//
+// The daemon writes and pushes the locks, never the agent (#1320): a cloud session has no push
+// access, and a lock that only existed inside the run it protects would protect nothing.
+/** The first line of a placeholder sibling: the claim, naming the agent that holds it. */
+export const SPIKE_LOCK_PREFIX = 'PENDING:';
+/**
+ * How old a PENDING lock must be before it is presumed dead and released. Generous against the
+ * slowest live path — spiking and planning can take hours, on top of a cloud queue — because a
+ * lock released under a live agent re-opens the double-work window the lock exists to close,
+ * while a dead agent's ticket only waits one interval longer. This is a bug-recovery mechanism
+ * that ideally never fires (#1364 review), so erring long costs nearly nothing.
+ */
+export const SPIKE_LOCK_STALE_MS = 6 * 60 * 60 * 1000;
+/** Whether a sibling's content is a PENDING placeholder rather than a real spike or plan. */
+export function isSpikeLock(md) {
+    return md.trimStart().startsWith(SPIKE_LOCK_PREFIX);
+}
+/** What a lock file holds: the claim line and nothing else, so the check above stays trivial. */
+export function spikeLockContent(agentId) {
+    return `${SPIKE_LOCK_PREFIX}${agentId}\n`;
+}
+/** The commit a batch of locks lands as. Names the count so the history reads as what happened. */
+export function lockMessage(count) {
+    return `[The Framework] lock ${count} ticket${count === 1 ? '' : 's'} for concurrent spike agents`;
+}
+/** The commit a release lands as. */
+export function releaseMessage(count) {
+    return `[The Framework] release ${count} stale spike lock${count === 1 ? '' : 's'}`;
+}
+const defaultPrTouches = async (cwd, file) => {
+    const { value } = await cachedOpenPrFilePatches(cwd, file);
+    return value === undefined ? undefined : value.length > 0;
+};
+/**
+ * Push the just-made lock commit to origin's default branch — the branch other machines fork
+ * from, the only place a lock closes the cross-machine window (#1320, #1364 review). Pushed only
+ * when the checkout is *on* that branch: `HEAD:main` from anywhere else would carry the branch's
+ * own commits onto main, and the old `HEAD:<current branch>` published whatever branch the
+ * checkout happened to be on. Resolves false when the push was skipped for that reason; a failed
+ * push still throws, so each caller keeps its own log line.
+ */
+async function pushLockCommit(git, cwd) {
+    const current = (await git(['rev-parse', '--abbrev-ref', 'HEAD'], cwd)).trim();
+    // `origin/main` in almost every checkout; asked rather than assumed, with the assumption as
+    // the fallback for a clone whose origin/HEAD was never set.
+    const head = await git(['symbolic-ref', '--short', 'refs/remotes/origin/HEAD'], cwd).then(out => out.trim(), () => 'origin/main');
+    const target = head.replace(/^origin\//, '');
+    if (current !== target)
+        return false;
+    await git(['push', 'origin', `HEAD:${target}`], cwd);
+    return true;
+}
+/** A ticket filename's lock paths, relative to the repo root. */
+function lockPaths(ticket) {
+    const stem = ticket.replace(/\.md$/, '');
+    return {
+        spike: `${TICKETS_DIR}/${stem}.spike.md`,
+        plan: `${TICKETS_DIR}/${stem}.plan.md`,
+    };
+}
+/**
+ * Claim `assignments`' tickets for their agents: write both placeholder siblings per ticket,
+ * commit the whole batch in one pathspec-scoped commit, and push it to origin's default branch
+ * ({@link pushLockCommit}). Resolves the subset actually locked — a ticket whose sibling appeared since the candidates
+ * were enumerated is skipped, not overwritten: an existing file is someone's claim or someone's
+ * work, and either outranks this batch.
+ *
+ * A batch whose commit failed is rolled back (the written files removed) and resolves `[]`:
+ * uncommitted placeholders in the user's checkout would be noise git blames on nobody. A batch
+ * whose *push* failed is kept and resolved as locked — the commit still guards every run forked
+ * from this checkout, which is the common case, and the sweep should not stand a healthy local
+ * fan-out down over a network blip. The push is what closes the cross-machine window (#1320), so
+ * its failure is logged rather than swallowed.
+ *
+ * Never throws: this runs on a background tick with nothing to catch it.
+ */
+export async function acquireSpikeLocks(cwd, assignments, deps = {}) {
+    const git = deps.git ?? nodeGitRunner();
+    const write = deps.write ?? ((path, content) => writeFile(path, content, 'utf8'));
+    const read = deps.read ?? (path => readFile(path, 'utf8'));
+    const remove = deps.remove ?? (path => rm(path));
+    const log = deps.log ?? (() => { });
+    const locked = [];
+    const files = [];
+    try {
+        for (const assignment of assignments) {
+            const { spike, plan } = lockPaths(assignment.ticket);
+            // Existence via a read, so one seam serves both operations. Either sibling present — real
+            // or placeholder — means the ticket is not this batch's to claim.
+            const taken = await Promise.all([read(join(cwd, spike)).then(() => true, () => false), read(join(cwd, plan)).then(() => true, () => false)]);
+            if (taken.some(Boolean))
+                continue;
+            await write(join(cwd, spike), spikeLockContent(assignment.agentId));
+            await write(join(cwd, plan), spikeLockContent(assignment.agentId));
+            locked.push(assignment);
+            files.push(spike, plan);
+        }
+        if (!locked.length)
+            return [];
+        await git(['add', '--', ...files], cwd);
+        await git(['commit', '-m', lockMessage(locked.length), '--', ...files], cwd);
+    }
+    catch {
+        // The claim is the *commit*: files that never reached one claim nothing, so they are removed
+        // rather than left as uncommitted noise, and the sweep falls back to a single unpinned agent.
+        await Promise.all(files.map(file => remove(join(cwd, file)).catch(() => undefined)));
+        return [];
+    }
+    try {
+        if (!(await pushLockCommit(git, cwd)))
+            log(`[framework] spike locks: the checkout is not on the default branch, so the lock commit was not pushed — agents on other machines cannot see these ${locked.length} claim(s)`);
+    }
+    catch {
+        log(`[framework] spike locks: the lock commit could not be pushed, so agents on other machines cannot see these ${locked.length} claim(s)`);
+    }
+    return locked;
+}
+/**
+ * Release the PENDING locks whose agents are presumed dead, so a crashed spike does not brick its
+ * ticket forever. A lock is stale exactly when all three hold (#1327's rule): its content is still
+ * the placeholder, no open PR touches it (a finished agent's PR carries the real sibling — the
+ * #1313 claim takes over from here), and its last commit is older than {@link SPIKE_LOCK_STALE_MS}.
+ * An *uncommitted* placeholder is left alone: it is a batch being acquired right now, or a commit
+ * failure {@link acquireSpikeLocks} already rolled back.
+ *
+ * Deletions land as one pathspec-scoped commit, pushed best-effort like the acquisition.
+ * Resolves the released tickets' filenames. Never throws.
+ */
+export async function releaseStaleSpikeLocks(cwd, deps = {}) {
+    const git = deps.git ?? nodeGitRunner();
+    const read = deps.read ?? (path => readFile(path, 'utf8'));
+    const remove = deps.remove ?? (path => rm(path));
+    const list = deps.list ?? (dir => readdir(dir));
+    const prTouches = deps.prTouches ?? defaultPrTouches;
+    const now = deps.now ?? (() => Date.now());
+    const staleMs = deps.staleMs ?? SPIKE_LOCK_STALE_MS;
+    const log = deps.log ?? (() => { });
+    try {
+        const names = await list(join(cwd, TICKETS_DIR)).catch(() => []);
+        const released = [];
+        const files = [];
+        for (const name of names) {
+            if (!/\.spike\.md$/.test(name))
+                continue;
+            const ticket = `${name.replace(/\.spike\.md$/, '')}.md`;
+            const { spike, plan } = lockPaths(ticket);
+            const [spikeMd, planMd] = await Promise.all([
+                read(join(cwd, spike)).catch(() => undefined),
+                read(join(cwd, plan)).catch(() => undefined),
+            ]);
+            const pending = [
+                ...(spikeMd !== undefined && isSpikeLock(spikeMd) ? [spike] : []),
+                ...(planMd !== undefined && isSpikeLock(planMd) ? [plan] : []),
+            ];
+            if (!pending.length)
+                continue;
+            // The newest lock commit is the claim's age. An empty answer is an uncommitted placeholder:
+            // a batch mid-acquisition, which is the opposite of stale.
+            const stamps = await Promise.all(pending.map(file => git(['log', '-1', '--format=%ct', '--', file], cwd).then(out => out.trim(), () => '')));
+            if (stamps.some(stamp => !stamp))
+                continue;
+            const newest = Math.max(...stamps.map(stamp => Number(stamp) * 1000));
+            if (!Number.isFinite(newest) || now() - newest < staleMs)
+                continue;
+            // Asked last because it is the expensive read, and only about the pending files: a stem
+            // whose real spike rode in on a PR while the plan stayed PENDING keeps the plan too.
+            const touched = await Promise.all(pending.map(file => prTouches(cwd, file)));
+            if (touched.some(t => t !== false))
+                continue;
+            for (const file of pending)
+                await remove(join(cwd, file));
+            files.push(...pending);
+            released.push(ticket);
+        }
+        if (!released.length)
+            return [];
+        await git(['add', '--', ...files], cwd);
+        await git(['commit', '-m', releaseMessage(files.length), '--', ...files], cwd);
+        try {
+            if (!(await pushLockCommit(git, cwd)))
+                log(`[framework] spike locks: the checkout is not on the default branch, so the release commit was not pushed`);
+        }
+        catch {
+            log(`[framework] spike locks: the release commit could not be pushed`);
+        }
+        log(`[framework] spike locks: released ${released.length} stale lock(s): ${released.join(', ')}`);
+        return released;
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=spike-locks.js.map

package/dist/spike-locks.js.map

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

package/dist/stale-branch.d.ts

@@ -0,0 +1,21 @@
+import { type GitRunner } from './project.js';
+import { type LinkedPr } from './dashboard/gh.js';
+/** What became of one pinned branch: gone already, genuinely busy, unprovable, or released. */
+export type StaleBranchOutcome = 'absent' | 'pending' | 'unproven' | 'released';
+/** Injectable seams so the release is unit-testable off disk and off GitHub. */
+export interface StaleBranchDeps {
+    git?: GitRunner;
+    /** The branch's full PR history (default {@link ghPrsForBranch}). */
+    prs?: (cwd: string, branch: string) => Promise<LinkedPr[]>;
+}
+/**
+ * Delete a pinned routine branch whose PR is closed or merged, so the next firing proceeds.
+ *
+ * Deliberately conservative on the two unprovable cases: an open PR keeps the branch (that is a
+ * triage genuinely pending), and a branch with no PR history at all keeps it too — that is either
+ * an agent still working toward its handoff or a `gh` that could not answer, and deleting on a
+ * hiccup would discard work. Never throws: a release that could not happen leaves the routine
+ * exactly as jammed as it was, which the next tick retries.
+ */
+export declare function releaseStalePinnedBranch(cwd: string, branch: string, deps?: StaleBranchDeps): Promise<StaleBranchOutcome>;
+//# sourceMappingURL=stale-branch.d.ts.map

package/dist/stale-branch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-branch.d.ts","sourceRoot":"","sources":["../src/stale-branch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,SAAS,EAAE,MAAM,cAAc,CAAA;AAC5D,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAsBjE,+FAA+F;AAC/F,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,CAAA;AAE/E,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,SAAS,CAAA;IACf,qEAAqE;IACrE,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAA;CAC3D;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,kBAAkB,CAAC,CAuB7B"}

package/dist/stale-branch.js

@@ -0,0 +1,32 @@
+import { nodeGitRunner } from './project.js';
+import { ghPrsForBranch } from './dashboard/gh.js';
+/**
+ * Delete a pinned routine branch whose PR is closed or merged, so the next firing proceeds.
+ *
+ * Deliberately conservative on the two unprovable cases: an open PR keeps the branch (that is a
+ * triage genuinely pending), and a branch with no PR history at all keeps it too — that is either
+ * an agent still working toward its handoff or a `gh` that could not answer, and deleting on a
+ * hiccup would discard work. Never throws: a release that could not happen leaves the routine
+ * exactly as jammed as it was, which the next tick retries.
+ */
+export async function releaseStalePinnedBranch(cwd, branch, deps = {}) {
+    const git = deps.git ?? nodeGitRunner();
+    const prs = deps.prs ?? ghPrsForBranch;
+    const local = await git(['show-ref', '--verify', `refs/heads/${branch}`], cwd).then(() => true, () => false);
+    const remote = await git(['ls-remote', '--heads', 'origin', branch], cwd).then(out => out.trim() !== '', () => false);
+    if (!local && !remote)
+        return 'absent';
+    const history = await prs(cwd, branch).catch(() => []);
+    if (history.some(pr => pr.state === 'OPEN'))
+        return 'pending';
+    if (history.length === 0)
+        return 'unproven';
+    if (remote)
+        await git(['push', 'origin', '--delete', branch], cwd).catch(() => undefined);
+    // -D, not -d: a squash merge leaves the branch unmerged in git's eyes. And git refusing because
+    // a worktree still has the branch checked out is the in-flight guard working, not a failure.
+    if (local)
+        await git(['branch', '-D', branch], cwd).catch(() => undefined);
+    return 'released';
+}
+//# sourceMappingURL=stale-branch.js.map

package/dist/stale-branch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-branch.js","sourceRoot":"","sources":["../src/stale-branch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,MAAM,cAAc,CAAA;AAC5D,OAAO,EAAE,cAAc,EAAiB,MAAM,mBAAmB,CAAA;AAgCjE;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,GAAW,EACX,MAAc,EACd,OAAwB,EAAE;IAE1B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,aAAa,EAAE,CAAA;IACvC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,cAAc,CAAA;IAEtC,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,CAAC,UAAU,EAAE,UAAU,EAAE,cAAc,MAAM,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CACjF,GAAG,EAAE,CAAC,IAAI,EACV,GAAG,EAAE,CAAC,KAAK,CACZ,CAAA;IACD,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,CAAC,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAC5E,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE,EACxB,GAAG,EAAE,CAAC,KAAK,CACZ,CAAA;IACD,IAAI,CAAC,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAA;IAEtC,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC,CAAA;IACtD,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,KAAK,MAAM,CAAC;QAAE,OAAO,SAAS,CAAA;IAC7D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAA;IAE3C,IAAI,MAAM;QAAE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IACzF,gGAAgG;IAChG,6FAA6F;IAC7F,IAAI,KAAK;QAAE,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;IAC1E,OAAO,UAAU,CAAA;AACnB,CAAC"}

package/dist/steps.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The opening prompt of a build session (`prompts/extend_prompt.md`): the work is delivered
+ * within the existing codebase (#185) — a project is a repo that already exists, so the old
+ * greenfield/scaffold framings are gone (#1683 review). The text lives in `prompts/` like every
+ * other agent-facing prompt (#551/#1347); this only fills the user's intent, under the same
+ * `tf.prompt` name the system prompt uses.
+ */
+export declare function extendPrompt(intent: string): string;
+//# sourceMappingURL=steps.d.ts.map

package/dist/steps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.d.ts","sourceRoot":"","sources":["../src/steps.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnD"}