@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/cloud-work.js

@@ -0,0 +1,204 @@
+import { nodeGitRunner } from '@openagt/agent-data';
+import { pickAgentPr, prsForBranchOrThrow } from './dashboard/pull-requests.js';
+import { openRemoteBranchPullRequest } from './dashboard/agent-handoff.js';
+import { listAgents, projectRuns, startedAtFromAgentId } from './store/index.js';
+import { errorMessage } from './error-message.js';
+import { startProjectPass } from './project-pass.js';
+// Adopt the branch a cloud session actually worked on (#1601).
+//
+// A web run is a local wrapper that hands the task to claude.ai and ends; the cloud session does
+// the work on a branch of its own naming (`claude/*`), never the designated run branch. Nothing
+// ever told the run's record about that branch, so every surface keyed to it — the session row,
+// the PR resolution, the merge — stared at an empty `agent-*` branch, and the run read
+// as "nothing committed" while its work sat on origin.
+//
+// The hand-off anchor (#1601) makes the match exact rather than guessed: the driver pushes an
+// empty commit unique to the run as the ref the session clones at, so the session's branch — and
+// only it — descends from that commit. This pass walks origin's `claude/*` heads, matches each
+// waiting run by that ancestry, and records what it finds onto the run's archive as one commit
+// on the data branch: the branch, the PR the session opened for it — and when the run was armed
+// for a PR the session never opened, it opens the draft PR itself, which is the armed handoff
+// finally resolving against the facts.
+//
+// Conservative on every unprovable case: a run matching no head (the session has not pushed, or
+// did nothing) or more than one (ancestry alone cannot say which) is simply retried next pass,
+// and a run older than the window stops being asked about at all.
+/** How long after its start a run is still asked about: safely past any cloud session's life. */
+export const CLOUD_ADOPTION_WINDOW_MS = 48 * 60 * 60 * 1000;
+/** Where a cloud session's own branches live: what an adopted run's record names. */
+const CLOUD_BRANCH_PREFIX = 'claude/';
+/** Whether the run's record still carries the branch it was born on, i.e. no adoption happened: no branch, or one that is not a cloud session's. */
+function onBirthBranch(meta) {
+    return !meta.branch?.startsWith(CLOUD_BRANCH_PREFIX);
+}
+/** Whether the run's handoff was armed to open a PR. Absent means armed, matching the agent. */
+function prArmed(meta) {
+    return meta.handoff?.pr !== false;
+}
+/** The settled web runs this pass still owes an answer. */
+function waitingRuns(agents, now) {
+    return agents.filter(meta => {
+        if (meta.target !== 'web' || meta.status === 'running' || !meta.cloudAnchor)
+            return false;
+        const startedAt = meta.startedAt ?? startedAtFromAgentId(meta.id);
+        const startedMs = startedAt === undefined ? NaN : Date.parse(startedAt);
+        if (!Number.isFinite(startedMs) || now - startedMs > CLOUD_ADOPTION_WINDOW_MS)
+            return false;
+        // Owed: the branch is not adopted yet, or it is and the armed PR is still unaccounted for.
+        // An unarmed run stops being asked about once its branch is recorded — a PR someone opens
+        // later is still found live, by branch name, by every surface that shows PRs.
+        return onBirthBranch(meta) || (meta.pr === undefined && prArmed(meta) && meta.status === 'done');
+    });
+}
+/** Where the pass keeps origin's `claude/*` heads locally. */
+const CLOUD_HEAD_PREFIX = 'refs/remotes/origin/claude/';
+/**
+ * Bring origin's `claude/*` heads local, once for the whole pass rather than once per head.
+ *
+ * The objects belong to a cloud VM, so they have to be fetched before any ancestry can be read.
+ * This replaces a fetch per unmatched head per waiting run (#1607) — the saving is the call
+ * count, not the transfer: a second fetch of heads already local negotiates and sends nothing.
+ *
+ * The destination refspec is named rather than left to chance. An ordinary checkout would write
+ * these refs anyway, because git opportunistically updates the remote-tracking branches its
+ * configured refspec covers even when the command line names its own; a checkout cloned with a
+ * narrower refspec — `--single-branch` — would not, and would re-fetch every pass forever.
+ *
+ * Pruned, because these refs are now a standing local copy of a list that used to be read live
+ * from origin each pass: without it a `claude/*` branch deleted on origin would go on matching.
+ */
+async function fetchCloudHeads(git, cwd) {
+    await git(['fetch', '--prune', 'origin', `+refs/heads/claude/*:${CLOUD_HEAD_PREFIX}*`], cwd);
+}
+/**
+ * The `claude/*` heads descending from `anchor` — the proof a branch is this run's, asked of git
+ * once for the whole set rather than once per head.
+ *
+ * `--contains` is the same ancestry question `merge-base --is-ancestor` answered one head at a
+ * time, and asking it this way also answers "how many" in the same call. Unprovable reads as no
+ * match and is retried next pass: an anchor whose object is not local is exactly the case where
+ * the session has pushed nothing for it to be an ancestor of.
+ */
+async function headsDescendingFrom(git, cwd, anchor) {
+    const listing = await git(['for-each-ref', `--contains=${anchor}`, '--format=%(objectname) %(refname)', CLOUD_HEAD_PREFIX], cwd).catch(() => '');
+    const heads = [];
+    for (const line of listing.split('\n')) {
+        const head = /^([0-9a-f]{40,64}) (.+)$/.exec(line.trim());
+        if (head?.[2]?.startsWith(CLOUD_HEAD_PREFIX)) {
+            heads.push({ ref: `claude/${head[2].slice(CLOUD_HEAD_PREFIX.length)}`, sha: head[1] });
+        }
+    }
+    return heads;
+}
+/** The default {@link CloudWorkDeps.patch}: the late facts onto the run, through the project's runs provider. */
+async function patchProvidedRun(cwd, agentId, patch) {
+    const runs = await projectRuns(cwd).catch(() => undefined);
+    return runs ? (await runs.patch(agentId, patch)).ok : false;
+}
+/**
+ * Adopt one project's cloud work (#1601): match each waiting web run to the `claude/*` head
+ * descending from its hand-off anchor, and record the branch and its PR onto the run's archive —
+ * opening the armed draft PR when the session never did. Never throws: a repo with no remote
+ * (or offline) adopts nothing, and every unmatched run is retried next pass.
+ */
+export async function adoptCloudWork(cwd, deps = {}) {
+    const git = deps.git ?? nodeGitRunner();
+    const prs = deps.prs ?? prsForBranchOrThrow;
+    const agents = deps.agents ?? ((project, since) => listAgents(project, projectRuns, { since }));
+    const patchArchive = deps.patch ?? patchProvidedRun;
+    const openPr = deps.openPr ?? openRemoteBranchPullRequest;
+    const now = deps.now ? deps.now() : Date.now();
+    const result = { adopted: [], failed: [] };
+    // Only the window's runs are asked for: an archive grows without bound, and everything older
+    // than the window is a record `waitingRuns` would drop anyway — so it is never read (#1607).
+    const waiting = waitingRuns(await agents(cwd, now - CLOUD_ADOPTION_WINDOW_MS).catch(() => []), now);
+    if (waiting.length === 0)
+        return result;
+    try {
+        await fetchCloudHeads(git, cwd);
+    }
+    catch {
+        return result; // no remote, or it cannot be reached: nothing to match against
+    }
+    for (const run of waiting) {
+        const matches = await headsDescendingFrom(git, cwd, run.cloudAnchor);
+        // Exactly one, or nothing happens: zero is a session that has not pushed (or never will),
+        // and two is a history this pass cannot arbitrate — both are the next pass's question.
+        if (matches.length !== 1)
+            continue;
+        const head = matches[0];
+        const branch = head.ref;
+        // A run whose record names some other branch — neither the one it was born on nor this head
+        // — is not this pass's to answer: a PR opened here would be recorded against a branch it
+        // does not live on.
+        if (!onBirthBranch(run) && run.branch !== branch)
+            continue;
+        // The PR the session opened for its branch, if any — filtered by the run's start so a
+        // predecessor's PR on a reused name is never this run's, `latest` so the last PR that saw
+        // the branch answers (#1512). "None" and "could not list" must not look alike here: a
+        // listing that fails opens nothing this pass (a second draft PR on a branch that already
+        // has one is the cost of guessing), and the run is asked again next time.
+        const since = run.startedAt ?? startedAtFromAgentId(run.id);
+        const listing = await prs(cwd, branch).then(found => ({ ok: true, pr: pickAgentPr(found, since, 'latest') }), (err) => ({ ok: false, error: errorMessage(err) }));
+        let pr = listing.ok ? listing.pr : undefined;
+        let opened = false;
+        if (!listing.ok) {
+            result.failed.push({ agentId: run.id, error: `could not list the PRs of ${branch} (${listing.error}), so no draft PR was opened this pass` });
+        }
+        else if (!pr && prArmed(run) && run.status === 'done' && head.sha !== run.cloudAnchor) {
+            // The armed handoff, finally resolving (#1601): the run was armed for a PR, the session
+            // opened none, and the branch carries something beyond the hand-off itself — so the draft
+            // PR the wrapper's epilogue could never open (it saw only the empty run branch) opens now.
+            // A run whose PR arming was off gets its branch recorded and nothing else.
+            const openedPr = await openPr(cwd, run, branch);
+            if (openedPr.ok && openedPr.number !== undefined && openedPr.url) {
+                pr = { number: openedPr.number, url: openedPr.url, state: 'OPEN', title: '' };
+                opened = true;
+            }
+            else if (!openedPr.ok) {
+                result.failed.push({ agentId: run.id, error: `could not open the armed draft PR for ${branch}: ${openedPr.error}` });
+            }
+        }
+        // One commit on the data branch carries whatever this pass learned: the branch (first time
+        // only), the PR (once known). Nothing learned, nothing written — and nothing announced.
+        const patch = {
+            ...(onBirthBranch(run) ? { branch } : {}),
+            ...(pr && run.pr === undefined ? { pr: { number: pr.number, url: pr.url } } : {}),
+        };
+        if (Object.keys(patch).length === 0)
+            continue;
+        if (!(await patchArchive(cwd, run.id, patch))) {
+            result.failed.push({ agentId: run.id, error: `could not record ${branch} on the run's archive` });
+            continue;
+        }
+        result.adopted.push({
+            agentId: run.id,
+            branch,
+            ...(pr ? { pr: { number: pr.number, url: pr.url } } : {}),
+            ...(opened ? { opened: true } : {}),
+        });
+    }
+    return result;
+}
+/**
+ * Adopt every registered project's cloud work (#1601), one turn per call.
+ *
+ * Adoptions and failures are said out loud, unmatched runs are not: a session that has not
+ * pushed yet is the normal state of every run this watches, and a line per tick about it would
+ * be noise. A run's row changing branch with no line explaining why would read as a bug.
+ */
+export function startCloudWorkAdoption(opts) {
+    const adopt = opts.adopt ?? adoptCloudWork;
+    // No timer of its own (E4): the daemon's one clock calls `tick`.
+    return startProjectPass(opts.projects, async (cwd) => {
+        const { adopted, failed } = await adopt(cwd).catch(() => ({ adopted: [], failed: [] }));
+        for (const adoption of adopted) {
+            const prLine = adoption.pr ? (adoption.opened ? `; opened its armed draft PR ${adoption.pr.url}` : `; its PR is ${adoption.pr.url}`) : '';
+            opts.log(`[framework] session ${adoption.agentId}'s cloud work landed on ${adoption.branch} — adopted as its branch (#1601)${prLine}`);
+        }
+        for (const failure of failed) {
+            opts.log(`[framework] cloud work adoption for session ${failure.agentId}: ${failure.error}`);
+        }
+    });
+}
+//# sourceMappingURL=cloud-work.js.map

package/dist/cloud-work.js.map

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

package/dist/config-layers.d.ts

@@ -0,0 +1,62 @@
+import { type HandoffLevel } from './handoff-level.js';
+import { type FrameworkFileConfig } from './config.js';
+/**
+ * Resolving an agent's settings across config layers (#841).
+ *
+ * The layers used to combine with `||`, which meant a flag could only ever turn a mode *on* and
+ * the-framework.yml could only ever turn one *on*: no layer could say `false`. #800 needs "a
+ * project overrides only what it sets", which cannot be built on OR.
+ *
+ * So: nearest layer that set a key wins, and a layer that left a key unset does not participate.
+ * Absent stays absent, so an existing setup resolves the same way; the one behaviour change is
+ * that an explicit `false` in a nearer layer now wins.
+ */
+/** The agent settings a config layer can carry. Keys left `undefined` mean "this layer said nothing". */
+export interface AgentConfigValues {
+    /** Remove the built-in #326 system prompt, keeping the session controls (#314/C3). */
+    vanilla?: boolean | undefined;
+    /** Run the wrapped agent fully raw (#625). */
+    transparent?: boolean | undefined;
+    /** How far a finished session publishes itself (#1102/#1216/B5). */
+    handoff?: HandoffLevel | undefined;
+}
+/** One tier of config, with the label the agent narrates when this tier wins a key. */
+export interface ConfigLayer {
+    /** Where these values came from, e.g. `flag` or `the-framework.yml`. */
+    name: string;
+    values: AgentConfigValues;
+}
+/** What a key resolves to when no layer set it. */
+export declare const RUN_CONFIG_DEFAULTS: {
+    readonly vanilla: false;
+    readonly transparent: false;
+    readonly handoff: HandoffLevel;
+};
+/**
+ * The nearest layer that set `key`, or `undefined` when none did. Layers are ordered
+ * nearest-first: run flags > project user > repo yml > global.
+ */
+export declare function resolveConfigKey<K extends keyof AgentConfigValues>(layers: readonly ConfigLayer[], key: K): {
+    value: NonNullable<AgentConfigValues[K]>;
+    from: string;
+} | undefined;
+/** An agent's settled config, plus which layer supplied each key a layer actually set. */
+export interface ResolvedAgentConfig {
+    vanilla: boolean;
+    transparent: boolean;
+    /** How far this session publishes itself (#1102/#1216/B5). */
+    handoff: HandoffLevel;
+    /** Winning layer name per key; a key left to its default is absent here. */
+    sources: Partial<Record<keyof AgentConfigValues, string>>;
+}
+/** Resolve every agent setting over `layers` (nearest first), falling back to {@link RUN_CONFIG_DEFAULTS}. */
+export declare function resolveAgentConfig(layers: readonly ConfigLayer[]): ResolvedAgentConfig;
+/** The repo tier: `the-framework.yml` as a layer. */
+export declare function fileConfigLayer(file: FrameworkFileConfig, name?: string): ConfigLayer;
+/**
+ * A one-line summary of what a layer set and which one won, e.g.
+ * `vanilla=off (flag), handoff=local (the-framework.yml)`. Keys nobody set are
+ * left out, so an agent with no config anywhere narrates nothing.
+ */
+export declare function describeResolvedConfig(config: ResolvedAgentConfig): string;
+//# sourceMappingURL=config-layers.d.ts.map

package/dist/config-layers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-layers.d.ts","sourceRoot":"","sources":["../src/config-layers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACvE,OAAO,EAAoC,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAExF;;;;;;;;;;GAUG;AAEH,yGAAyG;AACzG,MAAM,WAAW,iBAAiB;IAChC,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B,8CAA8C;IAC9C,WAAW,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACjC,oEAAoE;IACpE,OAAO,CAAC,EAAE,YAAY,GAAG,SAAS,CAAA;CACnC;AAED,uFAAuF;AACvF,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,iBAAiB,CAAA;CAC1B;AAED,mDAAmD;AACnD,eAAO,MAAM,mBAAmB;aAC9B,OAAO;aACP,WAAW;aAIX,OAAO;CACC,CAAA;AAEV;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,iBAAiB,EAChE,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,GAAG,EAAE,CAAC,GACL;IAAE,KAAK,EAAE,WAAW,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAMxE;AAED,0FAA0F;AAC1F,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,OAAO,CAAA;IACpB,8DAA8D;IAC9D,OAAO,EAAE,YAAY,CAAA;IACrB,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,iBAAiB,EAAE,MAAM,CAAC,CAAC,CAAA;CAC1D;AAED,8GAA8G;AAC9G,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,mBAAmB,CAetF;AAED,qDAAqD;AACrD,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,EAAE,IAAI,SAAsB,GAAG,WAAW,CAMlG;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,mBAAmB,GAAG,MAAM,CAS1E"}

package/dist/config-layers.js

@@ -0,0 +1,70 @@
+import { DEFAULT_HANDOFF } from './handoff-level.js';
+import { BOOLEAN_CONFIG_KEYS, CONFIG_KEYS } from './config.js';
+/** What a key resolves to when no layer set it. */
+export const RUN_CONFIG_DEFAULTS = {
+    vanilla: false,
+    transparent: false,
+    // `pr` by default (#1102): the zero-config handoff is what makes a session left alone hand
+    // itself back. Merging is the rung above, because landing work on the default branch is not
+    // reversible the way pushing a branch is (#1216).
+    handoff: DEFAULT_HANDOFF,
+};
+/**
+ * The nearest layer that set `key`, or `undefined` when none did. Layers are ordered
+ * nearest-first: run flags > project user > repo yml > global.
+ */
+export function resolveConfigKey(layers, key) {
+    for (const layer of layers) {
+        const value = layer.values[key];
+        if (value !== undefined)
+            return { value: value, from: layer.name };
+    }
+    return undefined;
+}
+/** Resolve every agent setting over `layers` (nearest first), falling back to {@link RUN_CONFIG_DEFAULTS}. */
+export function resolveAgentConfig(layers) {
+    const sources = {};
+    const pick = (key) => {
+        const hit = resolveConfigKey(layers, key);
+        if (!hit)
+            return undefined;
+        sources[key] = hit.from;
+        return hit.value;
+    };
+    const modes = {};
+    for (const key of BOOLEAN_CONFIG_KEYS)
+        modes[key] = pick(key) ?? RUN_CONFIG_DEFAULTS[key];
+    return {
+        ...modes,
+        handoff: pick('handoff') ?? RUN_CONFIG_DEFAULTS.handoff,
+        sources,
+    };
+}
+/** The repo tier: `the-framework.yml` as a layer. */
+export function fileConfigLayer(file, name = 'the-framework.yml') {
+    const values = {};
+    for (const key of CONFIG_KEYS) {
+        if (file[key] !== undefined)
+            Object.assign(values, { [key]: file[key] });
+    }
+    return { name, values };
+}
+/**
+ * A one-line summary of what a layer set and which one won, e.g.
+ * `vanilla=off (flag), handoff=local (the-framework.yml)`. Keys nobody set are
+ * left out, so an agent with no config anywhere narrates nothing.
+ */
+export function describeResolvedConfig(config) {
+    const shown = [
+        ...BOOLEAN_CONFIG_KEYS.map((key) => [key, onOff(config[key])]),
+        ['handoff', config.handoff],
+    ];
+    return shown
+        .filter(([key]) => config.sources[key])
+        .map(([key, value]) => `${key}=${value} (${config.sources[key]})`)
+        .join(', ');
+}
+function onOff(value) {
+    return value ? 'on' : 'off';
+}
+//# sourceMappingURL=config-layers.js.map

package/dist/config-layers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-layers.js","sourceRoot":"","sources":["../src/config-layers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAqB,MAAM,oBAAoB,CAAA;AACvE,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAA4B,MAAM,aAAa,CAAA;AA+BxF,mDAAmD;AACnD,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,OAAO,EAAE,KAAK;IACd,WAAW,EAAE,KAAK;IAClB,2FAA2F;IAC3F,4FAA4F;IAC5F,kDAAkD;IAClD,OAAO,EAAE,eAAe;CAChB,CAAA;AAEV;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAA8B,EAC9B,GAAM;IAEN,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAC/B,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,EAAE,KAAK,EAAE,KAA0C,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAA;IACzG,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAYD,8GAA8G;AAC9G,MAAM,UAAU,kBAAkB,CAAC,MAA8B;IAC/D,MAAM,OAAO,GAAqD,EAAE,CAAA;IACpE,MAAM,IAAI,GAAG,CAAoC,GAAM,EAAiD,EAAE;QACxG,MAAM,GAAG,GAAG,gBAAgB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;QACzC,IAAI,CAAC,GAAG;YAAE,OAAO,SAAS,CAAA;QAC1B,OAAO,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC,IAAI,CAAA;QACvB,OAAO,GAAG,CAAC,KAAK,CAAA;IAClB,CAAC,CAAA;IACD,MAAM,KAAK,GAAG,EAA2D,CAAA;IACzE,KAAK,MAAM,GAAG,IAAI,mBAAmB;QAAE,KAAK,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,mBAAmB,CAAC,GAAG,CAAC,CAAA;IACzF,OAAO;QACL,GAAG,KAAK;QACR,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,mBAAmB,CAAC,OAAO;QACvD,OAAO;KACR,CAAA;AACH,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,eAAe,CAAC,IAAyB,EAAE,IAAI,GAAG,mBAAmB;IACnF,MAAM,MAAM,GAAsB,EAAE,CAAA;IACpC,KAAK,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,GAAG,CAAC,KAAK,SAAS;YAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAC1E,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;AACzB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA2B;IAChE,MAAM,KAAK,GAAwC;QACjD,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC,GAAG,EAAqC,EAAE,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACjG,CAAC,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC;KAC5B,CAAA;IACD,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;SACtC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,KAAK,KAAK,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;SACjE,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC;AAED,SAAS,KAAK,CAAC,KAAc;IAC3B,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAA;AAC7B,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,54 @@
+import { type HandoffLevel } from './handoff-level.js';
+/**
+ * The per-repo session defaults persisted in `the-framework.yml`: the prompt switches and how far
+ * a finished session publishes itself, so a repo's config travels with the code instead of being
+ * chosen again every session.
+ */
+export interface FrameworkFileConfig {
+    /**
+     * Remove the built-in #326 system prompt, keeping the session controls. Default `false`.
+     *
+     * One name for one concept (C3). This key used to be `antiLazyPill` — the historical name of
+     * the prompt's ancestor (#301) — spelled the other way round from the `vanilla` it mapped to
+     * everywhere else, so the file, the preference and the agent option each said the same thing in a
+     * different direction and three comments apologised for it.
+     */
+    vanilla?: boolean;
+    /**
+     * Transparent mode (#625): make every agent in this project a raw `claude -p` — no framework
+     * system prompt, no emit protocols, no consumption guard, no dashboard, no TODO loop. The
+     * coarse "only-pick-what-you-need" master off-switch, at the per-project tier. Default `false`.
+     */
+    transparent?: boolean;
+    /**
+     * How far a finished session publishes itself (#1102/#1173/#1216/B5): `local`, `push`, `pr` or
+     * `merge`. Default `pr`. Whether a session publishes itself is a fact about the repo, so it
+     * belongs in the file that travels with it.
+     *
+     * `merge` has to be asked for out loud: publishing a branch is reversible, landing it on the
+     * default branch is not. Meant for work whose review already happened before the session — the
+     * queued work merges what a plan the human could veto already settled.
+     */
+    handoff?: HandoffLevel;
+}
+/**
+ * The boolean-valued mode keys. This is the canonical mode list: parsing, the config-layer copy,
+ * resolution, and the resolved-config summary all iterate it, so a new mode is added here once and
+ * flows through them (only its default and any renamed output field are declared per key).
+ */
+export declare const BOOLEAN_CONFIG_KEYS: readonly ['vanilla', 'transparent'];
+/** Every config key, enum then boolean, in declaration order. */
+export declare const CONFIG_KEYS: readonly ["handoff", "vanilla", "transparent"];
+/**
+ * Read `the-framework.yml` (or `.yaml`) from a directory. A missing file yields
+ * `{}`. Best-effort: a malformed file is reported via `onWarn` and treated as
+ * empty, never a failed agent. CLI flags override whatever this returns.
+ */
+export declare function loadFrameworkConfig(dir: string, onWarn?: (message: string) => void): Promise<FrameworkFileConfig>;
+/**
+ * Parse and validate a `the-framework.yml` body into a {@link FrameworkFileConfig}.
+ * An empty document is `{}`. Throws on a non-map document or a mistyped field so
+ * {@link loadFrameworkConfig} can surface it as a warning.
+ */
+export declare function parseFrameworkConfig(raw: string, source?: string): FrameworkFileConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAIA,OAAO,EAAkC,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtF;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;;;;OAQG;IACH,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB;AAUD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,YAAI,SAAS,EAAE,aAAa,CAAU,CAAA;AACtE,iEAAiE;AACjE,eAAO,MAAM,WAAW,gDAAyD,CAAA;AAEjF;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,MAAM,EACX,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAiB9B;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,SAAsB,GAAG,mBAAmB,CAwBnG"}

package/dist/config.js

@@ -0,0 +1,78 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { errorMessage } from './error-message.js';
+import { isHandoffLevel, HANDOFF_LEVELS } from './handoff-level.js';
+/** Config file names read from the workspace root, in precedence order. */
+const FRAMEWORK_CONFIG_FILES = ['the-framework.yml', 'the-framework.yaml'];
+/**
+ * The keys whose values come from a closed set, so parsing checks the value rather than the type
+ * (B5). Only the publish ladder so far; each is validated by name in {@link parseFrameworkConfig}.
+ */
+const ENUM_CONFIG_KEYS = ['handoff'];
+/**
+ * The boolean-valued mode keys. This is the canonical mode list: parsing, the config-layer copy,
+ * resolution, and the resolved-config summary all iterate it, so a new mode is added here once and
+ * flows through them (only its default and any renamed output field are declared per key).
+ */
+export const BOOLEAN_CONFIG_KEYS = ['vanilla', 'transparent'];
+/** Every config key, enum then boolean, in declaration order. */
+export const CONFIG_KEYS = [...ENUM_CONFIG_KEYS, ...BOOLEAN_CONFIG_KEYS];
+/**
+ * Read `the-framework.yml` (or `.yaml`) from a directory. A missing file yields
+ * `{}`. Best-effort: a malformed file is reported via `onWarn` and treated as
+ * empty, never a failed agent. CLI flags override whatever this returns.
+ */
+export async function loadFrameworkConfig(dir, onWarn) {
+    for (const name of FRAMEWORK_CONFIG_FILES) {
+        let raw;
+        try {
+            raw = await readFile(join(dir, name), 'utf8');
+        }
+        catch {
+            continue; // not this name; try the next
+        }
+        try {
+            return parseFrameworkConfig(raw, name);
+        }
+        catch (err) {
+            // parseFrameworkConfig already prefixes the file name in its message.
+            onWarn?.(`ignoring ${errorMessage(err)}`);
+            return {};
+        }
+    }
+    return {};
+}
+/**
+ * Parse and validate a `the-framework.yml` body into a {@link FrameworkFileConfig}.
+ * An empty document is `{}`. Throws on a non-map document or a mistyped field so
+ * {@link loadFrameworkConfig} can surface it as a warning.
+ */
+export function parseFrameworkConfig(raw, source = 'the-framework.yml') {
+    const data = parseYaml(raw);
+    if (data == null)
+        return {};
+    if (typeof data !== 'object' || Array.isArray(data)) {
+        throw new Error(`${source} must be a YAML map of settings`);
+    }
+    const obj = data;
+    const config = {};
+    // The one key with a closed set (B5), so it is checked by its values rather than by its type: a
+    // typo — or a leftover `handoff: true` — has to be an error, not a silently ignored rung that
+    // leaves the repo publishing more than its file says.
+    if (obj['handoff'] !== undefined) {
+        if (!isHandoffLevel(obj['handoff'])) {
+            throw new Error(`${source}: "handoff" must be one of ${HANDOFF_LEVELS.join(' | ')}`);
+        }
+        config.handoff = obj['handoff'];
+    }
+    for (const key of BOOLEAN_CONFIG_KEYS) {
+        if (obj[key] !== undefined) {
+            if (typeof obj[key] !== 'boolean')
+                throw new Error(`${source}: "${key}" must be a boolean`);
+            config[key] = obj[key];
+        }
+    }
+    return config;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/consumption-guard.d.ts

@@ -0,0 +1,53 @@
+import { QuotaPoller } from './quota-poller.js';
+import type { Driver } from './driver/index.js';
+/** A live quota gate, and the polling behind it. */
+export interface ConsumptionGuard {
+    /**
+     * Pass as `consumptionGate` to a run. Answers from the poller's cached
+     * readings, so it is cheap enough to ask between every turn. The label of the
+     * window that reached the limit in force (the boundary plus its half-day
+     * cushion, #960 Edit), or null while there is room.
+     */
+    gate: () => string | null;
+    /** The poller feeding it, exposed so a caller can read the windows off it. */
+    poller: QuotaPoller;
+    /** Stop polling. Always call this when the run ends. */
+    stop: () => void;
+}
+/** Options for {@link startConsumptionGuard}. */
+export interface StartConsumptionGuardOptions {
+    /** The wrapped agent. Must be able to report its quota, or there's nothing to guard with. */
+    driver: Driver;
+    /** The model the run is on. Brings that model's own weekly window into the gate (#879). */
+    model?: string;
+    /**
+     * The user's spend-limit offset — the #960 slider — read fresh around each gate check so
+     * dragging it unblocks a parked run's next boundary check without a restart (#1490). It only
+     * ever LOOSENS the gate (see the gate's comment); absent or unreadable means the default
+     * policy, the same fallback the daemon's quota source uses.
+     */
+    limitOffset?: () => number | Promise<number>;
+    /** Clock, injectable for tests. */
+    now?: () => number;
+}
+/**
+ * Wire the quota boundary up for one run (#879): poll the agent's quota, and
+ * hand back the gate a run consults between turns.
+ *
+ * The boundary is derived from the account's own week, so there is nothing to
+ * configure and nothing to remember between restarts: it is a comparison of two
+ * numbers the agent reports, not a total we accumulate.
+ *
+ * Resolves `undefined` when there is nothing to guard with — the agent can't
+ * report a quota at all (the fake driver, or a second agent that has no such
+ * command). That is the fail-open Rom confirmed on #519: no reading means the
+ * work carries on, with the per-run budget cap still underneath it. The gate
+ * itself fails open for the same reason, which is the opposite of the auto-PM
+ * gate: this one guards work the user asked for.
+ *
+ * The first read is deliberately not awaited. It takes ~5s (it spawns the whole
+ * agent CLI), and making every run wait that long to *maybe* find out it has
+ * budget would be a poor trade. It lands a moment into the run instead.
+ */
+export declare function startConsumptionGuard(opts: StartConsumptionGuardOptions): ConsumptionGuard | undefined;
+//# sourceMappingURL=consumption-guard.d.ts.map

package/dist/consumption-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumption-guard.d.ts","sourceRoot":"","sources":["../src/consumption-guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAG/C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAA;AAE/C,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B;;;;;OAKG;IACH,IAAI,EAAE,MAAM,MAAM,GAAG,IAAI,CAAA;IACzB,8EAA8E;IAC9E,MAAM,EAAE,WAAW,CAAA;IACnB,wDAAwD;IACxD,IAAI,EAAE,MAAM,IAAI,CAAA;CACjB;AAED,iDAAiD;AACjD,MAAM,WAAW,4BAA4B;IAC3C,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAA;IACd,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC5C,mCAAmC;IACnC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,4BAA4B,GAAG,gBAAgB,GAAG,SAAS,CA4CtG"}

package/dist/consumption-guard.js

@@ -0,0 +1,69 @@
+import { QuotaPoller } from './quota-poller.js';
+import { quotaBoundaryStatus } from './quota-boundary.js';
+import { DEFAULT_SPEND_OFFSET } from './preference-defaults.js';
+/**
+ * Wire the quota boundary up for one run (#879): poll the agent's quota, and
+ * hand back the gate a run consults between turns.
+ *
+ * The boundary is derived from the account's own week, so there is nothing to
+ * configure and nothing to remember between restarts: it is a comparison of two
+ * numbers the agent reports, not a total we accumulate.
+ *
+ * Resolves `undefined` when there is nothing to guard with — the agent can't
+ * report a quota at all (the fake driver, or a second agent that has no such
+ * command). That is the fail-open Rom confirmed on #519: no reading means the
+ * work carries on, with the per-run budget cap still underneath it. The gate
+ * itself fails open for the same reason, which is the opposite of the auto-PM
+ * gate: this one guards work the user asked for.
+ *
+ * The first read is deliberately not awaited. It takes ~5s (it spawns the whole
+ * agent CLI), and making every run wait that long to *maybe* find out it has
+ * budget would be a poor trade. It lands a moment into the run instead.
+ */
+export function startConsumptionGuard(opts) {
+    const readQuota = opts.driver.readQuota?.bind(opts.driver);
+    if (!readQuota)
+        return undefined;
+    const now = opts.now ?? (() => Date.now());
+    const poller = new QuotaPoller({ read: () => readQuota(), now });
+    poller.start();
+    // The slider's latest resolved value. The gate stays synchronous — it answers from cached
+    // readings — so the offset is refreshed in the background around each check and the check
+    // uses the last value that landed: one turn behind at worst, which is also how fresh the
+    // quota reading itself is.
+    let userOffset = DEFAULT_SPEND_OFFSET;
+    const refreshOffset = () => {
+        if (!opts.limitOffset)
+            return;
+        void Promise.resolve()
+            .then(opts.limitOffset)
+            .then(value => {
+            if (Number.isFinite(value))
+                userOffset = value;
+        })
+            .catch(() => { }); // an unreadable registry means the default policy
+    };
+    refreshOffset();
+    return {
+        poller,
+        stop: () => poller.stop(),
+        gate: () => {
+            refreshOffset();
+            const windows = poller.current().lastGood?.windows;
+            if (!windows)
+                return null;
+            // The same half-day cushion unattended work gets by default (#960 Edit). The continuous
+            // boundary starts the week at zero, so without one the first integer percent the agent
+            // reports outruns it and the user's own first run of the week is paused over ordinary
+            // rounding — the stepped line this replaces always kept the current day's seventh in hand.
+            // The user's slider joins the gate only when it LOOSENS it (#1490): raising the limit must
+            // unblock the runs the Usage bar says have room — the bar and this gate disagreeing is the
+            // exact thing #960 forbids — but lowering it sets where *unattended* work stands down, and
+            // holding it back must never tighten the gate on work the user asked for.
+            const limitOffset = Math.max(DEFAULT_SPEND_OFFSET, userOffset);
+            const status = quotaBoundaryStatus({ windows, now: now(), limitOffset, ...(opts.model ? { model: opts.model } : {}) });
+            return status?.reached?.label ?? null;
+        },
+    };
+}
+//# sourceMappingURL=consumption-guard.js.map

package/dist/consumption-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consumption-guard.js","sourceRoot":"","sources":["../src/consumption-guard.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzD,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AAmC/D;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAkC;IACtE,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC1D,IAAI,CAAC,SAAS;QAAE,OAAO,SAAS,CAAA;IAEhC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;IAC1C,MAAM,MAAM,GAAG,IAAI,WAAW,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,EAAE,GAAG,EAAE,CAAC,CAAA;IAChE,MAAM,CAAC,KAAK,EAAE,CAAA;IAEd,0FAA0F;IAC1F,0FAA0F;IAC1F,yFAAyF;IACzF,2BAA2B;IAC3B,IAAI,UAAU,GAAG,oBAAoB,CAAA;IACrC,MAAM,aAAa,GAAG,GAAG,EAAE;QACzB,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,OAAM;QAC7B,KAAK,OAAO,CAAC,OAAO,EAAE;aACnB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC;aACtB,IAAI,CAAC,KAAK,CAAC,EAAE;YACZ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,UAAU,GAAG,KAAK,CAAA;QAChD,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA,CAAC,kDAAkD;IACvE,CAAC,CAAA;IACD,aAAa,EAAE,CAAA;IAEf,OAAO;QACL,MAAM;QACN,IAAI,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE;QACzB,IAAI,EAAE,GAAG,EAAE;YACT,aAAa,EAAE,CAAA;YACf,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,OAAO,CAAA;YAClD,IAAI,CAAC,OAAO;gBAAE,OAAO,IAAI,CAAA;YACzB,wFAAwF;YACxF,uFAAuF;YACvF,sFAAsF;YACtF,2FAA2F;YAC3F,2FAA2F;YAC3F,2FAA2F;YAC3F,2FAA2F;YAC3F,0EAA0E;YAC1E,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,oBAAoB,EAAE,UAAU,CAAC,CAAA;YAC9D,MAAM,MAAM,GAAG,mBAAmB,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE,WAAW,EAAE,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;YACtH,OAAO,MAAM,EAAE,OAAO,EAAE,KAAK,IAAI,IAAI,CAAA;QACvC,CAAC;KACF,CAAA;AACH,CAAC"}