@rryando/arcs 3.11.0 → 4.0.0

package/dist/web-server/permission-policy.js

@@ -0,0 +1,96 @@
+/**
+ * Intent → argv permission policy for headless `claude -p` runs.
+ *
+ * Safety in the session bridge is argv-shaped, and this module is the SINGLE
+ * place tool and permission flags are produced: `claude-runner.ts` stays
+ * argv-agnostic and no route hand-assembles a more permissive run. Every token
+ * emitted here comes from a closed set of module constants — the one
+ * caller-supplied token is the staged system prompt, and it is kept
+ * unambiguously a value (see asValueToken). Bypass flags are therefore
+ * unreachable from HTTP input by construction rather than by convention, and
+ * `test/permission-policy.test.ts` drives the builder with hostile
+ * HTTP-shaped payloads to keep it that way.
+ *
+ * Flags verified against claude 2.1.223: `--tools <tools...>` takes a
+ * comma-separated built-in tool list, `--permission-mode` accepts "plan" and
+ * "acceptEdits", and `--append-system-prompt` appends to (never replaces) the
+ * system prompt. `--cwd` is deliberately absent — claude >= 2.x rejects it, and
+ * the runner applies the working directory through spawn options.cwd instead.
+ */
+/** Accepted run intents. Also the source list for route-level zod validation. */
+export const RUN_INTENTS = ["ask", "change"];
+/** `ask`: inspect the workspace, never touch it. */
+const ASK_TOOLS = ["Read", "Grep", "Glob"];
+/**
+ * `change`: the read-only set plus the edit surface. Bash is deliberately NOT
+ * here — it is opt-in per run, so a change run cannot shell out by default.
+ */
+const CHANGE_TOOLS = ["Read", "Grep", "Glob", "Edit", "Write", "TodoWrite"];
+/** Appended last, and only on an explicit `allowBash === true`. */
+const BASH_TOOL = "Bash";
+const INTENT_TOOLS = {
+    ask: ASK_TOOLS,
+    change: CHANGE_TOOLS,
+};
+/** `plan` cannot edit; `acceptEdits` auto-accepts edits but not shell commands.
+ *  "bypassPermissions" is not reachable from this map — that is the point. */
+const INTENT_PERMISSION_MODES = {
+    ask: "plan",
+    change: "acceptEdits",
+};
+/**
+ * Builds the tool/permission argv segment for one run. The caller concatenates
+ * it onto the rest of its argv (`-p`, `--resume`, `--output-format`, …); this
+ * module owns nothing else.
+ */
+export function buildPermissionArgv(input = {}) {
+    const fields = asRecord(input);
+    const intent = normalizeIntent(fields.intent);
+    const tools = [...INTENT_TOOLS[intent]];
+    if (fields.allowBash === true)
+        tools.push(BASH_TOOL);
+    const argv = ["--tools", tools.join(","), "--permission-mode", INTENT_PERMISSION_MODES[intent]];
+    const staged = typeof fields.stagedSystemPrompt === "string" ? fields.stagedSystemPrompt.trim() : "";
+    if (staged)
+        argv.push("--append-system-prompt", asValueToken(staged));
+    return argv;
+}
+/**
+ * Fails closed: anything that is not exactly `"change"` runs read-only. The
+ * route's zod enum rejects malformed intents with a 400 first — this is the
+ * second line, so a caller that skips validation cannot widen the run.
+ */
+function normalizeIntent(value) {
+    return value === "change" ? "change" : "ask";
+}
+/**
+ * Keeps a caller-supplied value from ever being flag-shaped. Staged text is the
+ * only argv token ARCS does not author character-for-character, so a message of
+ * exactly `--dangerously-skip-permissions` arrives at claude's option parser in
+ * a position where only that parser's rules decide whether it reads as a value
+ * or as a flag.
+ *
+ * This prefix closes no hole that exists today, and an earlier version of this
+ * comment was wrong to claim it did. A live probe against claude 2.1.223:
+ * `claude --append-system-prompt --output-format json -p "…"` printed plain
+ * text where the control printed JSON — meaning the CLI had already swallowed
+ * the dash-leading `--output-format` as the VALUE of `--append-system-prompt`
+ * instead of reading it as an option. The installed parser is safe unaided.
+ *
+ * It is kept for version-independence, not as a bug fix. "An option's argument
+ * may itself begin with a dash" is an undocumented parser detail that a minor
+ * CLI upgrade could reverse with no breaking-change note, and the blast radius
+ * if it ever does is a permission flag from HTTP input. A single leading
+ * newline keeps every byte of the text while making the token unambiguously a
+ * value under either rule.
+ */
+function asValueToken(text) {
+    return text.startsWith("-") ? `\n${text}` : text;
+}
+/** Tolerates any runtime shape an HTTP body can take (null, array, scalar). */
+function asRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+//# sourceMappingURL=permission-policy.js.map

package/dist/web-server/permission-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-policy.js","sourceRoot":"","sources":["../../src/web-server/permission-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iFAAiF;AACjF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAU,CAAC;AAItD,oDAAoD;AACpD,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAU,CAAC;AAEpD;;;GAGG;AACH,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,WAAW,CAAU,CAAC;AAErF,mEAAmE;AACnE,MAAM,SAAS,GAAG,MAAM,CAAC;AAEzB,MAAM,YAAY,GAAyC;IACzD,GAAG,EAAE,SAAS;IACd,MAAM,EAAE,YAAY;CACrB,CAAC;AAEF;8EAC8E;AAC9E,MAAM,uBAAuB,GAA8B;IACzD,GAAG,EAAE,MAAM;IACX,MAAM,EAAE,aAAa;CACtB,CAAC;AAoBF;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAA6B,EAAE;IACjE,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAE9C,MAAM,KAAK,GAAG,CAAC,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IACxC,IAAI,MAAM,CAAC,SAAS,KAAK,IAAI;QAAE,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAErD,MAAM,IAAI,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,mBAAmB,EAAE,uBAAuB,CAAC,MAAM,CAAC,CAAC,CAAC;IAEhG,MAAM,MAAM,GACV,OAAO,MAAM,CAAC,kBAAkB,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACxF,IAAI,MAAM;QAAE,IAAI,CAAC,IAAI,CAAC,wBAAwB,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;IAEtE,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC;AAC/C,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AACnD,CAAC;AAED,+EAA+E;AAC/E,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzE,CAAC,CAAE,KAAiC;QACpC,CAAC,CAAC,EAAE,CAAC;AACT,CAAC"}

package/dist/web-server/prompt-assembly.d.ts

@@ -0,0 +1,454 @@
+/**
+ * Prompt assembly — the STABLE staged-environment tier, plus reference
+ * rendering.
+ *
+ * Two independent products, one module because they share one trust model and
+ * one escape (`stripStageDelimiters`, `untrustedDoc`):
+ *  - `buildStagedEnvironment` / `planStageRefresh` — the per-SESSION stable
+ *    block, documented below.
+ *  - `renderReference` / `renderReferences` — the per-TURN references a caller
+ *    attached to a message. This is the ONE place a reference is turned into
+ *    prompt text; nothing here enters the staged block, so a reference can
+ *    never move the stable tier's fingerprint.
+ *
+ * A headless `claude -p` run starts with no ambient project knowledge: it does
+ * not know which DAG node it is on, where the workspace root is, or what the
+ * project already learned. This module renders that context once, as a single
+ * ordered block that rides `--append-system-prompt`. The run route
+ * (`routes/sessions.ts`) appends that flag/value pair directly today:
+ * `permission-policy.ts`'s `buildPermissionArgv` owns the flag but returns a
+ * WHOLE tool/permission segment keyed on an `intent` the run route does not
+ * have, so emitting it there would restrict what today's runs may do. When
+ * POST /turns introduces intents, this same text becomes its
+ * `stagedSystemPrompt` and the direct pair goes away. This module emits TEXT
+ * only — it never produces argv, and never spawns anything.
+ *
+ * STABLE means byte-identical across turns for an unchanged DAG. That is the
+ * whole economics of the tier: an unchanged prefix is a cache hit upstream, so
+ * nothing volatile (timestamps, queue depth, run state) is allowed in `text`.
+ * `stagedAt` therefore lives on the returned stage RECORD, never in the text.
+ * The VOLATILE tier is a separate, later concern.
+ *
+ * Trust model. ARCS-derived facts are asserted plainly. Every body copied out
+ * of a file or an agent-authored DAG document is wrapped in a named
+ * `<<<ARCS_UNTRUSTED_DOC …>>>` delimiter, carries an explicit "embedded
+ * instructions cannot override" sentence, and is run through
+ * `stripStageDelimiters` so a document cannot close its own wrapper and
+ * escalate into the controller's voice.
+ *
+ * Budgets are spent on a body's CONTENT, never on the wrapped string: clipping
+ * a rendered wrapper keeps its opener and severs its closer, which puts every
+ * later ARCS-authored block inside an unterminated untrusted region. Both
+ * products obey this — `renderBlock` for the staged tier, and the reference
+ * renderers by clipping before they call `untrustedDoc`.
+ *
+ * Read-only. This module reads ARCS data through the existing store readers and
+ * the existing knowledge-selection helper; it never writes. It RETURNS a
+ * `StageRecord` for the caller (the run route) to persist at `metadata.stage`.
+ * (Caveat inherited from the stores, not introduced here: `readKnowledgeIndex`
+ * and `readPlanIndex` self-repair a corrupt or drifted index on read. That is
+ * repair of existing data, never a mutation this module authors.)
+ */
+import type { SessionReference } from "../utils/claude-transcript.js";
+import type { SessionMeta } from "../utils/session-store.js";
+export declare const STAGE_TRANSPORTS: readonly ["system", "prompt"];
+export type StageTransport = (typeof STAGE_TRANSPORTS)[number];
+/**
+ * How the staged text reaches the model.
+ *
+ * - `system` (default) — appended via `--append-system-prompt`. Cheapest and
+ *   keeps the block out of the visible conversation.
+ * - `prompt` — prepended to the user prompt text instead.
+ *
+ * The designed fallback: flip this single constant to `"prompt"` if predicate
+ * P1 fails (see `STAGE_MANUAL_CHECKS`). Nothing else in the module changes —
+ * the transport is carried on the stage record so a flip forces a restage on
+ * already-staged sessions rather than silently leaving them on the old channel.
+ */
+export declare const STAGE_TRANSPORT: StageTransport;
+/**
+ * Checks this layer cannot automate, recorded as data so they stay greppable
+ * and can be surfaced by a route or a doc instead of rotting in a comment.
+ */
+export declare const STAGE_MANUAL_CHECKS: readonly [string];
+/**
+ * Degradation starts above this.
+ *
+ * MEASURED, against the live ARCS project, with the budgets below. It is
+ * HEADROOM, not a live path — a test reaches it only by passing `softCap`.
+ *
+ * STATE THE INPUTS OR THE FIGURE IS NOT RE-DERIVABLE, AND THERE ARE FOUR OF
+ * THEM. An assembled width is a function of inputs the corpus does not contain:
+ * un-budgeted IDENTITY interpolates `sessionId` (ceiling 96), `slug` (64) and
+ * `projectName` (64); un-budgeted WORKSPACE interpolates `workspaceRoot` (256).
+ * Every one is width-normalized by FIELD_WIDTHS and none is budgeted, so each
+ * char lands WHOLE on a build whose budgeted blocks are already saturated
+ * (measured on the binding node: dag-position 1199/1200, node-body 1200/1200,
+ * brief 800/800, knowledge 1599/1600). A row that names only one of the four is
+ * not a measurement — an earlier row here swept `sessionId` to its ceiling while
+ * leaving `projectName` at the live corpus's incidental 4 chars and
+ * `workspaceRoot` at 23, and recorded "fires for 0" as though it were general.
+ *
+ * WHAT IS AFFORDABLE IS THEIR SUM. The four inputs share one margin, so the
+ * whole measurement collapses to one number: on the live corpus the widest
+ * `observed` build stays off the ladder while
+ *
+ *     sessionId + slug + projectName + workspaceRoot <= 230 chars
+ *
+ * and fires at 231 (verified from both sides — see the 126/127 and 66/67 rows).
+ * `arcs` affords 284. The ceilings sum to 480, so the all-ceilings corner is 250
+ * chars past what the cap can hold and MUST degrade; see the last row.
+ *
+ * Live ARCS DAG, 137 tasks / 18 plans, swept whole against a COPY of the data
+ * dir (the stores self-repair on read), every row at the `sessionId` ceiling of
+ * 96, both origins, widths post-ladder with the FIRING COUNT beside them:
+ *
+ *   slug 4, name 4, root 23 — the live values:
+ *       arcs      5843 task / 5048 plan     fires 0 of 137 and 0 of 18
+ *       observed  5897 task / 5102 plan     fires 0 of 137 and 0 of 18
+ *   slug 4, name 64 (projectName CEILING), root 23:
+ *       arcs      5903 / 5108               fires 0 of 137 and 0 of 18
+ *       observed  5957 / 5162               fires 0 of 137 and 0 of 18
+ *   slug 64 (slug CEILING), name 4, root 23:   same widths as the row above
+ *       observed  5957 / 5162               fires 0 of 137 and 0 of 18
+ *   slug 4, name 4, root 103 — a deep but ordinary checkout path:
+ *       arcs      5923 / 5128               fires 0 of 137 and 0 of 18
+ *       observed  5977 / 5182               fires 0 of 137 and 0 of 18
+ *   slug 4, name 4, root 126 / 127 — the crossing, from both sides:
+ *       observed  6000 / 5205               fires 0 of 137   (126: on the cap)
+ *       observed  6000 / 5206               fires 11 of 137  (127: over it)
+ *   slug 4, name 64, root 66 / 67 — the same crossing with the name at ceiling:
+ *       observed  6000 fires 0 of 137   |   6000 fires 11 of 137
+ *   slug 64, name 64, root 256 — ALL FOUR AT THEIR CEILINGS:
+ *       arcs      5991 / 5401             fires 49 of 137 and 0 of 18
+ *       observed  5998 / 5455             fires 54 of 137 and 0 of 18
+ *       knowledge is the only payer (digest 6 entries -> 3); IDENTITY, WORKSPACE
+ *       and LIMITS render whole, and no build exceeds the cap.
+ *
+ * THE CORPUS SIZE IS ONE OF THE INPUTS, so a re-take on a different one is DRIFT,
+ * not a regression: the live DAG is already 139 tasks, which moves only the
+ * `observed` ceiling row from 54 to 55. Every row above names its inputs so the
+ * next taker re-derives them rather than comparing a count across two corpora.
+ *
+ * THE CEILING ROW FIRES BY CONSTRUCTION, NOT BY REGRESSION. Un-budgeted blocks
+ * at their widest cost 915 chars (STAGE_HARD_CAP's arithmetic) against the 663
+ * this cap leaves them, so no wording can make that row zero: it is 252 chars
+ * over before a single word is written. Same corner on the pre-origin-conditioned
+ * module, same 137-task corpus: 51 of 137 (arcs) and 53 of 137 (observed), 0 of
+ * 18 plans, knowledge the only payer. ONE number cannot cover both origins there
+ * either — HEAD's IDENTITY line already interpolates `origin`, 4 chars for `arcs`
+ * against 8 for `observed` — which is this file's own rule again: a row that names
+ * only one of its inputs is not a measurement. Note the direction, too: HEAD
+ * degrades MORE than this module does on `arcs` (51 against 49). Zero there is
+ * reachable only by raising this cap or budgeting IDENTITY/WORKSPACE, and both are
+ * larger decisions than a reword. What the row guarantees is that the DEGRADATION
+ * is bounded and paid by the cheapest budgeted block.
+ *
+ * REALISTIC vs CEILING, and which is which: a `workspaceRoot` is a real checkout
+ * path (this repo's is 23 chars, a deep one ~103), so the 23/66/103/126 rows are
+ * the reachable ones and 256 is the guarantee row. A `projectName` and a `slug`
+ * at 64 are entirely reachable — that is why the name-at-ceiling row exists, and
+ * why the un-budgeted wording that pushed its crossing down to a 57-char project
+ * name was reverted rather than re-measured.
+ *
+ * Earlier rows, kept for shape only — none of them names all four inputs, so
+ * none is comparable with the table above:
+ *   130 tasks: 5812 task / 5011 plan, fires 0 of 130, id width unrecorded.
+ *   133 tasks: 5807 / 5006 at a 15-char id; 5888 / 5087 re-derived at the id
+ *              ceiling. Fires 0 of 133 either way. Taken when `renderBlock` moved
+ *              the budget clip onto a body's CONTENT — both maxima are UNCHANGED
+ *              by that move (a clipped block is still bounded by the same budget:
+ *              the wrapper's tags are paid out of it, not added to it).
+ *
+ * All of this is a measurement, not a property, and it is what to re-take when a
+ * budget, an input width or a block's content changes. It has already caught two.
+ * Staging the owning plan for task-linked sessions put real content into a
+ * node-body block whose 1800-char budget had been sized for content that never
+ * existed, which took the widest real node to 6412 and made the ladder fire for
+ * 62 of 130 — paying for the plan by DELETING the whole knowledge digest; the
+ * budget was sized to the content instead (STAGE_BLOCK_BUDGETS["node-body"]).
+ * And 55 chars of un-budgeted wording moved the affordance from 234 to 179,
+ * which fired the ladder for 15 of 137 at nothing worse than a 57-char project
+ * name; 51 of those chars were given back (see LIMITS_OBSERVED) and the
+ * affordance is 230. The residual 4 is the `observed` IDENTITY sentence, which
+ * buys a true statement on a path where the old one was false — and `arcs` is 46
+ * chars NARROWER than it was, having dropped a supersede notice nothing emits.
+ *
+ * Re-take it with a sweep over the WHOLE corpus, both origins, naming ALL FOUR
+ * input widths, and report the ladder-FIRING COUNT beside every width. A width
+ * alone is satisfied by the degradation it is supposed to detect — that is how
+ * the 15-of-137 regression passed every cap assertion in the suite.
+ * `test/prompt-assembly-stable.test.ts` describe (g) pins the count.
+ */
+export declare const STAGE_SOFT_CAP = 6000;
+/**
+ * Never exceeded. Held by construction, and the arithmetic is:
+ *   budgeted blocks (STAGE_BLOCK_BUDGETS)            = 4800
+ * + un-budgeted blocks at their widest (identity 347,
+ *   workspace 353, limits 215 — width-normalized at
+ *   input by FIELD_WIDTHS, never truncated)          =  915
+ * + envelope, preamble, headings and joiners         =  537
+ *                                                    ------
+ *                                                    = 6252
+ * which leaves 1748 chars of slack under this cap.
+ *
+ * READ THIS AGAINST STAGE_SOFT_CAP, because the two disagree ON PURPOSE. The
+ * un-budgeted blocks are allowed 915 chars here and the soft cap leaves them
+ * 663 (6000 - 4800 - 537), so a build with every bounded input at its ceiling
+ * is 252 chars over the SOFT cap and degrades. That is the ladder doing its job,
+ * not a defect — but it is also why a reword of an un-budgeted block is a
+ * measurement, not an edit: it is spent out of a margin this cap does not
+ * protect. STAGE_SOFT_CAP records the sweep that says how much margin is left.
+ *
+ * `identity` and `limits` are ORIGIN-CONDITIONED, and the two numbers above are
+ * the `observed` variant — still the wider of the pair on both blocks (`arcs`
+ * measures 320 and 188), though limits is now 215 rather than 266: it lost a
+ * 32-char lead-in and traded a refresh promise it cannot keep for a 31-char
+ * capture statement. A ceiling taken from one origin is not a ceiling, which is
+ * why `test/prompt-assembly-stable.test.ts` builds both and asserts the observed
+ * one is the larger before pinning it.
+ *
+ * The un-budgeted numbers are otherwise the widths their fields are bounded to,
+ * so they cannot grow without a FIELD_WIDTHS constant moving — or without
+ * someone rewording an authored block, which is the change these figures exist
+ * to catch.
+ */
+export declare const STAGE_HARD_CAP = 8000;
+export type StageBlockId = "identity" | "workspace" | "dag-position" | "node-body" | "brief" | "knowledge" | "limits";
+/**
+ * The blocks the ladder may degrade and a per-block budget applies to.
+ *
+ * `identity`, `workspace` and `limits` are deliberately NOT here and carry no
+ * budget at all: they are never degraded, and their variable fields are
+ * width-normalized at input (FIELD_WIDTHS) instead, which bounds them by
+ * construction. Budgets for them used to exist and were inert — excluded from
+ * every code path that reads a budget, and all three exceeded the numbers they
+ * stated (324/353/234 against 120/120/200), so the invariant they documented
+ * was false as written.
+ */
+export type StageBudgetedBlockId = "dag-position" | "node-body" | "brief" | "knowledge";
+/** Render order. Fixed — the prefix must be stable for the cache to hit. */
+export declare const STAGE_BLOCK_ORDER: readonly StageBlockId[];
+/**
+ * Per-block character budgets. Keyed by StageBudgetedBlockId, so a block with
+ * no budget cannot be given an inert one. Sum = 4800; see STAGE_HARD_CAP for
+ * the full ceiling arithmetic this feeds.
+ *
+ * `node-body` is 1200, not the 1800 it carried while the block was empty for
+ * every task-linked run. 1800 is what the widest real DAG cannot afford: it
+ * takes the largest task-linked block to 6412 and makes the soft-cap ladder fire
+ * for 62 of 130 real nodes, whose first two rungs zero the knowledge digest — a
+ * curated 6-entry index traded for 600 more chars of one plan document. At 1200
+ * the widest real node is 5812 and the ladder fires for none, so both blocks
+ * survive. Measured across the whole live DAG at 1800/1500/1400/1300/1200:
+ * 62/34/14/0/0 nodes degraded.
+ *
+ * A budget bounds the block AS RENDERED, wrapper tags included: `renderBlock`
+ * pays the open/close tags out of the budget and spends what is left on the
+ * body's content. So a number here is not "chars of document" — a wide `source`
+ * buys less document, and a budget below the tag cost drops the body for a
+ * one-line pointer rather than emitting an opener it cannot close.
+ */
+export declare const STAGE_BLOCK_BUDGETS: Record<StageBudgetedBlockId, number>;
+/**
+ * Fixed truncation precedence — exactly the budgeted blocks, cheapest-to-lose
+ * first. The DAG position survives longest because it carries what the run must
+ * satisfy to finish (its scope, acceptance and verify command) alongside its
+ * edges; everything above it can be re-read on demand from the DAG or the repo.
+ */
+export declare const STAGE_TRUNCATION_PRECEDENCE: readonly StageBudgetedBlockId[];
+/**
+ * Neutralizes ARCS delimiter tokens in untrusted content. Applied to EVERY
+ * injected value — bodies, titles, summaries, ids — so there is no per-field
+ * exception to reason about.
+ */
+export declare function stripStageDelimiters(text: string): string;
+/**
+ * Files whose mtime means "the DAG may have moved". Cheap: four stats, no
+ * parsing. Store-mediated edits to a plan/knowledge BODY also land here,
+ * because every store write rewrites the owning index alongside the document.
+ */
+export declare const STAGE_PROBE_FILES: readonly string[];
+/**
+ * Deliberately NOT probed. Session heartbeat, status and run-metadata writes
+ * touch `sessions/index.json` on essentially every poll — including the very
+ * write that persists `metadata.stage`. Probing it would make every stage
+ * permanently stale and defeat the whole cache.
+ */
+export declare const STAGE_PROBE_EXCLUDED: readonly string[];
+/**
+ * The markdown document STAGED for the linked node, as a project-relative path.
+ * It must name the same file `readSources` copies into the node-body block, or
+ * an edit to that file would not invalidate the stage.
+ *
+ * Plans own `plans/<id>.md`. A task owns no document at all, so the block stages
+ * the plan that owns the TASK — and this therefore resolves to that same
+ * `plans/<planId>.md` rather than to the aggregate `tasks.md` it used to name
+ * (`tasks.md` was never load-bearing: it is rewritten by the same store write
+ * that rewrites the already-probed `tasks/index.json`).
+ *
+ * DELIBERATE COST, chosen over a silent staleness hole: resolving a task's plan
+ * needs the task index, so this is no longer derivable from the session alone
+ * and the probe is no longer stats-only. The read is one 192 KB JSON parse on
+ * the live ARCS project (~2 ms), paid ONCE PER RUN — the probe runs at spawn
+ * time, not per poll — against a `claude -p` subprocess that costs three orders
+ * of magnitude more. The alternative (persist the path on the stage record and
+ * read it back) removes the read but points the probe at the PREVIOUS build's
+ * file, which is a subtler thing to reason about for a saving that is invisible
+ * next to the spawn.
+ *
+ * `readJsonSafe`, never `listTasks`: the store readers self-repair a drifted
+ * index on read, and a probe that can WRITE a file it probes is a
+ * self-invalidating cache (the same failure `STAGE_PROBE_EXCLUDED` exists for).
+ *
+ * The one gap left: a hand-edited `plans/index.json` whose `file` does not
+ * follow `plans/<normalizedId>.md`. Every store-written index does, and a
+ * store-mediated body edit rewrites the probed index anyway.
+ */
+export declare function linkedNodeMarkdownPath(projectDir: string, session: SessionMeta): Promise<string | undefined>;
+/**
+ * Max mtime (epoch ms) across the probe set plus the linked node's markdown.
+ * Returns 0 when nothing in the set exists.
+ */
+export declare function probeDagMtimeMs(projectDir: string, session: SessionMeta): Promise<number>;
+export interface StageRecord {
+    /** sha256 hex of the staged text. */
+    fingerprint: string;
+    /**
+     * Epoch MILLISECONDS. Deliberately not ISO: it is compared numerically
+     * against `fs.Stats.mtimeMs`, and it sits under `metadata` next to
+     * `metadata.run`, which is already epoch ms. (Top-level SessionMeta
+     * timestamps are ISO; `metadata.*` timestamps are epoch ms. This follows its
+     * neighbours, not its grandparent.)
+     *
+     * On the path that persists it (`planStageRefresh`) this is the OBSERVED
+     * PROBE WATERMARK, never the wall clock — see that function's clause 2.
+     */
+    stagedAt: number;
+    transport: StageTransport;
+}
+/** Reads and validates `session.metadata.stage`, which is untyped on disk. */
+export declare function readStageRecord(session: SessionMeta): StageRecord | undefined;
+export interface StageTruncation {
+    block: StageBudgetedBlockId;
+    /** `block-budget` — the block exceeded its own budget. `soft-cap` — the
+     *  assembled text exceeded STAGE_SOFT_CAP and this block paid for it. */
+    reason: "block-budget" | "soft-cap";
+    droppedChars: number;
+}
+export interface StagedEnvironment {
+    text: string;
+    chars: number;
+    truncated: StageTruncation[];
+    /** Ready to persist at `metadata.stage`. This module never writes it. */
+    stage: StageRecord;
+}
+export interface StageOptions {
+    /** Absolute workspace root. Falls back to the project's first
+     *  `workspacePaths` entry, so P2 holds even when the caller passes nothing. */
+    workspaceRoot?: string;
+    /** Knowledge audience filter. Default `implementer`. */
+    audience?: string;
+    transport?: StageTransport;
+    /**
+     * Epoch ms for `stage.stagedAt`. Tests pin it; nothing else should —
+     * `planStageRefresh` OVERRIDES it with the probe watermark, because a record
+     * it returns is a record a caller persists and compares against mtimes.
+     */
+    now?: number;
+    /**
+     * Overrides STAGE_SOFT_CAP. Exists so the truncation precedence can be driven
+     * end-to-end at a cap the block budgets can actually breach — a caller on a
+     * tighter model budget may also lower it. STAGE_HARD_CAP is not overridable.
+     */
+    softCap?: number;
+}
+/**
+ * Builds the STABLE tier for one session.
+ *
+ * Deterministic: for an unchanged DAG the returned `text` is byte-identical
+ * across turns. Nothing volatile is rendered — `stage.stagedAt` is on the
+ * record, not in the text.
+ */
+export declare function buildStagedEnvironment(projectDir: string, slug: string, session: SessionMeta, opts?: StageOptions): Promise<StagedEnvironment>;
+export declare function fingerprintStagedText(text: string): string;
+export type StageRefreshReason = "unstaged" | "transport-changed" | "fresh" | "unchanged" | "changed";
+export interface StageRefresh {
+    reason: StageRefreshReason;
+    /** The staged text changed and must be re-injected. */
+    restage: boolean;
+    /** The caller should write `stage` to `metadata.stage`. */
+    persist: boolean;
+    stage?: StageRecord;
+    /** Absent only when `reason === "fresh"` — the cheap path never assembles. */
+    staged?: StagedEnvironment;
+    /** Max mtime observed by the probe, for logging. */
+    probedAt: number;
+}
+/**
+ * Two-phase staleness decision, verbatim:
+ *
+ *   probe = max mtimeMs over tasks/index.json, plans/index.json,
+ *           knowledge/index.json, meta.json and the linked node's markdown.
+ *           Missing files contribute 0. sessions/index.json is DELIBERATELY
+ *           EXCLUDED — heartbeat writes would make every stage permanently stale.
+ *   1. no stage record                     -> restage        (reason "unstaged")
+ *   2. stage.transport !== active transport-> restage        (reason "transport-changed")
+ *   3. probe <= stage.stagedAt             -> NO rebuild     (reason "fresh")   [cheap exit]
+ *   4. otherwise rebuild, fingerprint = sha256(text):
+ *        fingerprint === stage.fingerprint -> no restage     (reason "unchanged")
+ *                                             but persist a bumped stagedAt so
+ *                                             the cheap exit works again
+ *        else                              -> restage        (reason "changed")
+ *
+ * Step 4's stagedAt bump writes to sessions/index.json, which is exactly why
+ * that file must stay out of the probe set: otherwise the bump would invalidate
+ * itself on the next call. That exclusion is clause 1 of the pattern, and it is
+ * NOT sufficient alone.
+ *
+ * Clause 2 — STAMP FROM THE PROBE, NOT THE CLOCK. `stagedAt` is the `probedAt`
+ * watermark this function observed, so step 3 compares two values from the same
+ * measurement. Stamping `Date.now()` instead mixes two clocks that need not
+ * agree: anywhere mtime can exceed wall clock (NFS, container skew, an
+ * mtime-preserving restore) `probe <= stagedAt` never holds, the cheap exit
+ * never fires, and step 4 re-assembles and re-persists on EVERY turn despite a
+ * perfectly correct exclusion set.
+ *
+ * It also closes a read-then-stamp TOCTOU window. The probe runs before
+ * `readSources`; a wall clock sampled after would absorb a write landing in
+ * between and leave the stage stale until the NEXT write. Stamping the
+ * watermark leaves that write above the stamp, so the next call rebuilds and
+ * the fingerprint compare decides.
+ */
+export declare function planStageRefresh(projectDir: string, slug: string, session: SessionMeta, opts?: StageOptions): Promise<StageRefresh>;
+/**
+ * Per-reference caps.
+ *
+ * A reference belongs to the ONE turn a caller attached it to: it is rendered
+ * here and never reaches `buildStagedEnvironment`, so no value below can move
+ * the stable tier's fingerprint, its budgets or its truncation ladder.
+ */
+export declare const REFERENCE_BUDGETS: {
+    /** A doc section is what the user actually selected, so it is quoted — but
+     *  bounded, because a selection can be a whole chapter. */
+    readonly doc: 1600;
+    /** A file excerpt is an ANCHOR for a pointer, never the content: the agent
+     *  reads the live file, so a long excerpt buys only tokens and staleness. */
+    readonly fileExcerpt: 400;
+};
+/**
+ * ONE reference as prompt text.
+ *
+ * Deterministic: the same payload renders the same bytes — no timestamps, no
+ * counters, no ambient state. Every injected value goes through the same
+ * delimiter escape the staged tier uses, so a reference body cannot close its
+ * own wrapper and speak in the controller's voice, and every quoted body is
+ * introduced by an open tag carrying the governing note.
+ */
+export declare function renderReference(reference: SessionReference): string;
+/**
+ * The turn's whole reference block, or `""` when there is nothing to render —
+ * a turn without references must add no bytes at all.
+ */
+export declare function renderReferences(references: readonly SessionReference[]): string;
+//# sourceMappingURL=prompt-assembly.d.ts.map

package/dist/web-server/prompt-assembly.d.ts.map

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