@loopover/engine 1.0.0

package/dist/issue-rag-query.d.ts

@@ -0,0 +1,12 @@
+/** Skip retrieval for a trivially-short query (e.g. a one-word scope string): not worth an embed +
+ *  a vector query, and the matches would be noise. Single source of truth — `src/review/rag.ts`
+ *  re-exports this so the retrieval guard and the query builder can never drift apart. (#cloud-opt) */
+export declare const MIN_QUERY_CHARS = 40;
+export type IssueRagQueryInput = {
+    title: string;
+    body?: string | undefined;
+    labels?: string[] | undefined;
+};
+export declare function buildIssueRagQuery(input: IssueRagQueryInput): {
+    queryText: string;
+};

package/dist/issue-rag-query.js

@@ -0,0 +1,35 @@
+// Issue-centric RAG query composition (#2320), extracted from `src/review/issue-rag-wire.ts` (#4254) so the
+// gittensory-miner analyze phase can build the identical retrieval query without importing the review stack.
+// Pure, string-only: the miner has no PR diff yet, so retrieval is fed from the issue's title/body/labels
+// while the RAG engine itself stays unchanged (retrieveContext remains Vectorize/D1-bound in `src/review/rag.ts`
+// and is intentionally NOT part of this module).
+/** Skip retrieval for a trivially-short query (e.g. a one-word scope string): not worth an embed +
+ *  a vector query, and the matches would be noise. Single source of truth — `src/review/rag.ts`
+ *  re-exports this so the retrieval guard and the query builder can never drift apart. (#cloud-opt) */
+export const MIN_QUERY_CHARS = 40;
+const MAX_ISSUE_BODY_CHARS = 4000;
+const MAX_ISSUE_LABELS = 20;
+function cleanLabels(labels) {
+    if (!labels)
+        return [];
+    return labels
+        .map((label) => label.trim())
+        .filter(Boolean)
+        .slice(0, MAX_ISSUE_LABELS);
+}
+export function buildIssueRagQuery(input) {
+    const sections = [];
+    const title = input.title.trim();
+    if (title)
+        sections.push(title);
+    const body = (input.body ?? "").trim().slice(0, MAX_ISSUE_BODY_CHARS);
+    if (body)
+        sections.push(body);
+    const labels = cleanLabels(input.labels);
+    if (labels.length > 0)
+        sections.push(`Labels: ${labels.join(", ")}`);
+    const queryText = sections.join("\n\n").trim();
+    if (queryText.length < MIN_QUERY_CHARS)
+        return { queryText: "" };
+    return { queryText };
+}

package/dist/local-scorer.d.ts

@@ -0,0 +1,34 @@
+export type LocalScorerChangedFile = {
+    path: string;
+    previousPath?: string | undefined;
+    additions?: number | undefined;
+    deletions?: number | undefined;
+    status?: "added" | "modified" | "deleted" | "renamed" | "copied" | "unknown" | undefined;
+    binary?: boolean | undefined;
+};
+export type LocalScorerValidation = {
+    command: string;
+    status: "passed" | "failed" | "not_run" | "skipped" | "focused" | "unknown";
+    summary?: string | undefined;
+    durationMs?: number | undefined;
+    exitCode?: number | undefined;
+};
+export type LocalScorerResult = {
+    mode: "metadata_only" | "external_command" | "gittensor_root";
+    activeModel?: string | undefined;
+    sourceTokenScore?: number | undefined;
+    totalTokenScore?: number | undefined;
+    sourceLines?: number | undefined;
+    testTokenScore?: number | undefined;
+    nonCodeTokenScore?: number | undefined;
+    warnings?: string[] | undefined;
+};
+/**
+ * Compute token scores from changed-file metadata + the local validation results. `isCodeFile` already excludes
+ * tests, so source / test / non-code are disjoint. Binary files carry no token value and are dropped. A failed
+ * validation does not change the scores (they describe the diff) but is surfaced as a warning. Pure.
+ */
+export declare function computeLocalScorerTokens(input: {
+    changedFiles: LocalScorerChangedFile[];
+    validation?: LocalScorerValidation[] | undefined;
+}): LocalScorerResult;

package/dist/local-scorer.js

@@ -0,0 +1,36 @@
+// #782 deterministic local scorer, extracted from src/signals/local-scorer.ts (#4253) so the published
+// gittensory-mcp / gittensory-miner CLIs and the hosted Worker share one implementation. Replicates the
+// gittensor-root token-scoring view from changed-file METADATA (paths + line counts) — never source content,
+// so the no-upload boundary holds and it runs in every surface. It mirrors buildScorePreview's
+// source/test/non-code classification, so feeding its output back in as `localScorer` (mode external_command)
+// flips the preview off metadata-only with numbers it would otherwise have derived itself.
+//
+// The 3 dependent type shapes are narrowly duplicated here (the issue explicitly allows this) rather than
+// moving the large, Node-coupled local-branch.ts; they are structurally identical to local-branch.ts's
+// definitions. isCodeFile/isTestPath are the same portable classifiers local-branch.ts already delegates to.
+import { isCodeFile, isTestPath } from "./signals/test-evidence.js";
+const fileLines = (file) => Math.max(0, file.additions ?? 0) + Math.max(0, file.deletions ?? 0);
+/**
+ * Compute token scores from changed-file metadata + the local validation results. `isCodeFile` already excludes
+ * tests, so source / test / non-code are disjoint. Binary files carry no token value and are dropped. A failed
+ * validation does not change the scores (they describe the diff) but is surfaced as a warning. Pure.
+ */
+export function computeLocalScorerTokens(input) {
+    const files = input.changedFiles.filter((file) => !file.binary);
+    const testTokenScore = files.filter((file) => isTestPath(file.path)).reduce((sum, file) => sum + fileLines(file), 0);
+    const sourceTokenScore = files.filter((file) => isCodeFile(file.path)).reduce((sum, file) => sum + fileLines(file), 0);
+    const totalTokenScore = files.reduce((sum, file) => sum + fileLines(file), 0);
+    const nonCodeTokenScore = Math.max(0, totalTokenScore - sourceTokenScore - testTokenScore);
+    const failed = (input.validation ?? []).some((entry) => entry.status === "failed");
+    const warnings = failed ? ["Local validation reported failures — token scores describe the diff, not a passing build."] : [];
+    return {
+        mode: "external_command",
+        activeModel: "gittensory-deterministic",
+        sourceTokenScore,
+        totalTokenScore,
+        sourceLines: Math.max(1, sourceTokenScore || totalTokenScore || 1),
+        testTokenScore,
+        nonCodeTokenScore,
+        ...(warnings.length > 0 ? { warnings } : {}),
+    };
+}

package/dist/metadata-best-min-score.d.ts

@@ -0,0 +1,9 @@
+import type { MetadataCandidateIssue, MetadataRankContext } from "./opportunity-metadata.js";
+import type { OpportunityRankInput } from "./opportunity-ranker.js";
+/**
+ * Return the highest-scoring metadata candidate at or above `minScore`, or `null` when none qualify.
+ * Non-finite thresholds return `null`. Pure — delegates to {@link rankMetadataOpportunitiesAtOrAboveScore}.
+ */
+export declare function bestMetadataOpportunityAtOrAboveScore<T extends MetadataCandidateIssue>(candidates: readonly T[], context: MetadataRankContext, minScore: number): (T & OpportunityRankInput & {
+    rankScore: number;
+}) | null;

package/dist/metadata-best-min-score.js

@@ -0,0 +1,9 @@
+import { rankMetadataOpportunitiesAtOrAboveScore } from "./metadata-min-score.js";
+/**
+ * Return the highest-scoring metadata candidate at or above `minScore`, or `null` when none qualify.
+ * Non-finite thresholds return `null`. Pure — delegates to {@link rankMetadataOpportunitiesAtOrAboveScore}.
+ */
+export function bestMetadataOpportunityAtOrAboveScore(candidates, context, minScore) {
+    const survivors = rankMetadataOpportunitiesAtOrAboveScore(candidates, context, minScore);
+    return survivors[0] ?? null;
+}

package/dist/metadata-best-pick.d.ts

@@ -0,0 +1,9 @@
+import { type MetadataCandidateIssue, type MetadataRankContext } from "./opportunity-metadata.js";
+import type { OpportunityRankInput } from "./opportunity-ranker.js";
+/**
+ * Return the highest-scoring metadata candidate, or `null` when none are targetable/ranked.
+ * Pure — delegates to {@link rankMetadataOpportunities} for scoring and tie-breaking.
+ */
+export declare function bestMetadataOpportunity<T extends MetadataCandidateIssue>(candidates: readonly T[], context: MetadataRankContext): (T & OpportunityRankInput & {
+    rankScore: number;
+}) | null;

package/dist/metadata-best-pick.js

@@ -0,0 +1,9 @@
+import { rankMetadataOpportunities, } from "./opportunity-metadata.js";
+/**
+ * Return the highest-scoring metadata candidate, or `null` when none are targetable/ranked.
+ * Pure — delegates to {@link rankMetadataOpportunities} for scoring and tie-breaking.
+ */
+export function bestMetadataOpportunity(candidates, context) {
+    const ranked = rankMetadataOpportunities(candidates, context);
+    return ranked[0] ?? null;
+}

package/dist/metadata-min-score.d.ts

@@ -0,0 +1,9 @@
+import { type MetadataCandidateIssue, type MetadataRankContext } from "./opportunity-metadata.js";
+import type { OpportunityRankInput } from "./opportunity-ranker.js";
+/**
+ * Rank metadata candidates and keep only those whose rank score is at or above `minScore`.
+ * Non-finite thresholds return an empty list. Pure — delegates to {@link rankMetadataOpportunities}.
+ */
+export declare function rankMetadataOpportunitiesAtOrAboveScore<T extends MetadataCandidateIssue>(candidates: readonly T[], context: MetadataRankContext, minScore: number): Array<T & OpportunityRankInput & {
+    rankScore: number;
+}>;

package/dist/metadata-min-score.js

@@ -0,0 +1,13 @@
+import { rankMetadataOpportunities, } from "./opportunity-metadata.js";
+/**
+ * Rank metadata candidates and keep only those whose rank score is at or above `minScore`.
+ * Non-finite thresholds return an empty list. Pure — delegates to {@link rankMetadataOpportunities}.
+ */
+export function rankMetadataOpportunitiesAtOrAboveScore(candidates, context, minScore) {
+    if (!Number.isFinite(minScore))
+        return [];
+    if (candidates.length === 0)
+        return [];
+    const threshold = Math.min(1, Math.max(0, minScore));
+    return rankMetadataOpportunities(candidates, context).filter((entry) => entry.rankScore >= threshold);
+}

package/dist/metadata-top-min-score.d.ts

@@ -0,0 +1,9 @@
+import type { MetadataCandidateIssue, MetadataRankContext } from "./opportunity-metadata.js";
+import type { OpportunityRankInput } from "./opportunity-ranker.js";
+/**
+ * Rank metadata candidates, drop entries below `minScore`, and return the top `limit` survivors.
+ * Non-finite limits return an empty list. Pure — delegates to {@link rankMetadataOpportunitiesAtOrAboveScore}.
+ */
+export declare function pickTopMetadataOpportunitiesAtOrAboveScore<T extends MetadataCandidateIssue>(candidates: readonly T[], context: MetadataRankContext, minScore: number, limit: number): Array<T & OpportunityRankInput & {
+    rankScore: number;
+}>;

package/dist/metadata-top-min-score.js

@@ -0,0 +1,13 @@
+import { rankMetadataOpportunitiesAtOrAboveScore } from "./metadata-min-score.js";
+/**
+ * Rank metadata candidates, drop entries below `minScore`, and return the top `limit` survivors.
+ * Non-finite limits return an empty list. Pure — delegates to {@link rankMetadataOpportunitiesAtOrAboveScore}.
+ */
+export function pickTopMetadataOpportunitiesAtOrAboveScore(candidates, context, minScore, limit) {
+    if (!Number.isFinite(limit))
+        return [];
+    const safeLimit = Math.max(0, Math.trunc(limit));
+    if (safeLimit === 0)
+        return [];
+    return rankMetadataOpportunitiesAtOrAboveScore(candidates, context, minScore).slice(0, safeLimit);
+}

package/dist/metadata-top-pick.d.ts

@@ -0,0 +1,9 @@
+import { type MetadataCandidateIssue, type MetadataRankContext } from "./opportunity-metadata.js";
+import type { OpportunityRankInput } from "./opportunity-ranker.js";
+/**
+ * Rank metadata candidates and return the top `limit` entries. Non-finite or negative limits return an empty list.
+ * Pure — delegates to {@link rankMetadataOpportunities} for target filtering, scoring, and tie-breaking.
+ */
+export declare function pickTopMetadataOpportunities<T extends MetadataCandidateIssue>(candidates: readonly T[], context: MetadataRankContext, limit: number): Array<T & OpportunityRankInput & {
+    rankScore: number;
+}>;

package/dist/metadata-top-pick.js

@@ -0,0 +1,13 @@
+import { rankMetadataOpportunities, } from "./opportunity-metadata.js";
+/**
+ * Rank metadata candidates and return the top `limit` entries. Non-finite or negative limits return an empty list.
+ * Pure — delegates to {@link rankMetadataOpportunities} for target filtering, scoring, and tie-breaking.
+ */
+export function pickTopMetadataOpportunities(candidates, context, limit) {
+    if (!Number.isFinite(limit))
+        return [];
+    const safeLimit = Math.max(0, Math.trunc(limit));
+    if (safeLimit === 0 || candidates.length === 0)
+        return [];
+    return rankMetadataOpportunities(candidates, context).slice(0, safeLimit);
+}

package/dist/miner/acceptance-criteria.d.ts

@@ -0,0 +1,43 @@
+import { type PromptPacket } from "../prompt-packet.js";
+import type { FeasibilityGateResult, FeasibilityVerdict } from "../feasibility.js";
+/** Fixed on-disk filename for the per-attempt acceptance-criteria document written into the attempt worktree. */
+export declare const ACCEPTANCE_CRITERIA_FILENAME = "acceptance-criteria.json";
+/** Schema version of the serialized document; bump on any field-shape change. */
+export declare const ACCEPTANCE_CRITERIA_VERSION = 1;
+/** Inputs to the composer: the sanitized prompt packet and the feasibility verdict for this attempt. */
+export type AcceptanceCriteriaInput = {
+    promptPacket: PromptPacket;
+    feasibility: FeasibilityGateResult;
+};
+/** The composed, immutable per-attempt success bar. All fields are read-only; the document is frozen once built. */
+export type AcceptanceCriteria = {
+    readonly version: number;
+    readonly verdict: FeasibilityVerdict;
+    /** Whether this attempt is authorized to start (and therefore the file should be written): `verdict === "go"`. */
+    readonly writable: boolean;
+    readonly taskBrief: string;
+    readonly constraints: string;
+    readonly feasibilityNotes: string;
+    readonly retrievalContext: string;
+    readonly feasibilitySummary: string;
+    readonly avoidReasons: readonly string[];
+    readonly raiseReasons: readonly string[];
+};
+/**
+ * Only a `go` feasibility verdict authorizes the attempt to start, so only `go` gets an acceptance-criteria file
+ * written to the worktree. `raise`/`avoid` should be handled upstream (the attempt does not begin) — this predicate
+ * is the single source of truth for that gate.
+ */
+export declare function shouldWriteAcceptanceCriteria(verdict: FeasibilityVerdict): boolean;
+/**
+ * Pure builder: compose a {@link PromptPacket} and a {@link FeasibilityGateResult} into one immutable
+ * acceptance-criteria document. Text fields are re-sanitized with {@link sanitizePromptPacketField} (idempotent),
+ * and the returned document is deep-frozen so it cannot be mutated for the lifetime of the attempt.
+ */
+export declare function buildAcceptanceCriteria(input: AcceptanceCriteriaInput): AcceptanceCriteria;
+/**
+ * Deterministic canonical JSON serialization of a built document: fixed key order (independent of the input
+ * object's own key order) plus a trailing newline, so a checksum recorded alongside the file stays byte-stable
+ * across processes. `JSON.parse` round-trips it back to the same field values.
+ */
+export declare function serializeAcceptanceCriteria(doc: AcceptanceCriteria): string;

package/dist/miner/acceptance-criteria.js

@@ -0,0 +1,77 @@
+import { sanitizePromptPacketField } from "../prompt-packet.js";
+// Acceptance-criteria composer (#4271). Before a coding-agent driver (#4262's interface; #4266/#4267's
+// implementations) starts editing, the miner pins down — immutably, so the agent cannot quietly redefine its own
+// success bar mid-attempt — what "done" means for this attempt. This module is the pure composition step: it folds
+// the two already-shipped Phase 2 primitives — the sanitized `PromptPacket` (prompt-packet.ts, the analyze→coding-
+// agent "boundary membrane") and the `FeasibilityGateResult` go/raise/avoid verdict (feasibility.ts) — into one
+// document. Producing the document is this module's job; actually writing it into the attempt's worktree is the
+// worktree primitive's (#4269), and handing it to the driver is the driver interface's (#4262) — neither is here,
+// so this stays pure and side-effect-free like the rest of gittensory-engine.
+//
+// DECISIONS this file makes (per the issue's open questions):
+// - Serialization format: JSON, not markdown. The acceptance criteria are an immutable, checksum-verifiable success
+//   bar consumed by tooling (a self-review step must be able to prove the target did not move across iterations), so
+//   a deterministic, canonically-ordered JSON document beats prose. `serializeAcceptanceCriteria` emits stable-key-
+//   order JSON with a trailing newline so a checksum recorded alongside stays byte-stable.
+// - Filename: a single fixed name, `ACCEPTANCE_CRITERIA_FILENAME`.
+// - Immutability: the built document is deep-frozen (`Object.freeze`, arrays copied+frozen) so it cannot be mutated
+//   in-memory for the lifetime of the attempt; the byte-stable serialization is what a caller checksums on disk.
+// - Written only on `go`: a `raise`/`avoid` verdict means the attempt should not start, so no criteria file is
+//   written. The builder still returns a document (with `writable: false`) so a caller can log *why* it was skipped;
+//   `shouldWriteAcceptanceCriteria` is the gate for the write itself.
+//
+// Redaction is delegated to `sanitizePromptPacketField` rather than re-implemented: this document is exactly as
+// exposed to a prompt-injectable coding-agent session as the prompt packet, so it gets the same scrub (idempotent
+// on already-sanitized packet text).
+/** Fixed on-disk filename for the per-attempt acceptance-criteria document written into the attempt worktree. */
+export const ACCEPTANCE_CRITERIA_FILENAME = "acceptance-criteria.json";
+/** Schema version of the serialized document; bump on any field-shape change. */
+export const ACCEPTANCE_CRITERIA_VERSION = 1;
+/**
+ * Only a `go` feasibility verdict authorizes the attempt to start, so only `go` gets an acceptance-criteria file
+ * written to the worktree. `raise`/`avoid` should be handled upstream (the attempt does not begin) — this predicate
+ * is the single source of truth for that gate.
+ */
+export function shouldWriteAcceptanceCriteria(verdict) {
+    return verdict === "go";
+}
+/**
+ * Pure builder: compose a {@link PromptPacket} and a {@link FeasibilityGateResult} into one immutable
+ * acceptance-criteria document. Text fields are re-sanitized with {@link sanitizePromptPacketField} (idempotent),
+ * and the returned document is deep-frozen so it cannot be mutated for the lifetime of the attempt.
+ */
+export function buildAcceptanceCriteria(input) {
+    const { promptPacket, feasibility } = input;
+    return Object.freeze({
+        version: ACCEPTANCE_CRITERIA_VERSION,
+        verdict: feasibility.verdict,
+        writable: shouldWriteAcceptanceCriteria(feasibility.verdict),
+        taskBrief: sanitizePromptPacketField(promptPacket.taskBrief),
+        constraints: sanitizePromptPacketField(promptPacket.constraints),
+        feasibilityNotes: sanitizePromptPacketField(promptPacket.feasibilityNotes),
+        retrievalContext: sanitizePromptPacketField(promptPacket.retrievalContext),
+        feasibilitySummary: feasibility.summary,
+        avoidReasons: Object.freeze([...feasibility.avoidReasons]),
+        raiseReasons: Object.freeze([...feasibility.raiseReasons]),
+    });
+}
+/**
+ * Deterministic canonical JSON serialization of a built document: fixed key order (independent of the input
+ * object's own key order) plus a trailing newline, so a checksum recorded alongside the file stays byte-stable
+ * across processes. `JSON.parse` round-trips it back to the same field values.
+ */
+export function serializeAcceptanceCriteria(doc) {
+    const ordered = {
+        version: doc.version,
+        verdict: doc.verdict,
+        writable: doc.writable,
+        taskBrief: doc.taskBrief,
+        constraints: doc.constraints,
+        feasibilityNotes: doc.feasibilityNotes,
+        retrievalContext: doc.retrievalContext,
+        feasibilitySummary: doc.feasibilitySummary,
+        avoidReasons: [...doc.avoidReasons],
+        raiseReasons: [...doc.raiseReasons],
+    };
+    return `${JSON.stringify(ordered, null, 2)}\n`;
+}

package/dist/miner/agent-sdk-driver.d.ts

@@ -0,0 +1,39 @@
+import type { CodingAgentDriver } from "./coding-agent-driver.js";
+/**
+ * Opaque hook registration forwarded verbatim to the SDK session (`Options['hooks']` — keyed by hook event name,
+ * e.g. `PreToolUse`). Typed loosely on purpose: the hook contract belongs to the SDK and to the policy module that
+ * registers the hooks, not to this driver.
+ */
+export type AgentSdkHooks = Record<string, unknown>;
+/** The exact option subset this driver puts on a `query()` session. */
+export type AgentSdkQueryOptions = {
+    cwd: string;
+    maxTurns: number;
+    permissionMode: "acceptEdits";
+    hooks?: AgentSdkHooks | undefined;
+};
+/**
+ * Injected `query()`-shaped function — mirrors the injected-`SpawnFn` testability convention from #4262/#4266 so
+ * tests drive the driver with a fake async-iterable and CI never makes a real model call. Messages are consumed
+ * structurally (plain records), matching how the defensive fold below reads them.
+ */
+export type AgentSdkQueryFn = (input: {
+    prompt: string;
+    options: AgentSdkQueryOptions;
+}) => AsyncIterable<Record<string, unknown>>;
+export type CreateAgentSdkDriverOptions = {
+    /** Injected `query()` loop; defaults to the real `@anthropic-ai/claude-agent-sdk` export. */
+    query?: AgentSdkQueryFn | undefined;
+    /** Forwarded verbatim to the SDK session — the #2343 `PreToolUse` interception point. */
+    hooks?: AgentSdkHooks | undefined;
+    /** Injected changed-file enumerator; defaults to git diff over the worktree. */
+    listChangedFiles?: ((cwd: string) => Promise<string[]>) | undefined;
+};
+/**
+ * A `CodingAgentDriver` that runs the attempt through an in-process Agent-SDK `query()` session in the task's
+ * working directory. Mirrors the CLI-subprocess driver's contract: structured failure results (never a throw),
+ * `changedFiles` reported only on success (the CLI driver cannot know them on failure, and #4296's parity suite
+ * holds both implementations to the same shape), and `task.instructions` forwarded verbatim as the prompt — the
+ * acceptance-criteria document already lives inside the worktree at `task.acceptanceCriteriaPath` (#4271).
+ */
+export declare function createAgentSdkCodingAgentDriver(options?: CreateAgentSdkDriverOptions): CodingAgentDriver;

package/dist/miner/agent-sdk-driver.js

@@ -0,0 +1,162 @@
+// Agent-SDK `CodingAgentDriver` (#4267): the second implementation of the #4262 seam, driving the coding agent
+// in-process via `@anthropic-ai/claude-agent-sdk`'s `query()` async-iterable loop instead of shelling out to a CLI
+// binary (#4266). The streamed SDK message/tool-use events are folded into the shared `CodingAgentDriverResult`
+// right here — no SDK-specific event type leaks into the interface, so the iterate-loop orchestrator (#2333) can
+// swap this driver for the CLI-subprocess one with no caller-side changes.
+//
+// The SDK session's hook surface is deliberately NOT encapsulated: callers pass `hooks` (e.g. a `PreToolUse`
+// matcher, #2343's stated attachment point) and this driver forwards them verbatim onto the `query()` options, so
+// house-rule enforcement can intercept every tool call before execution without this module knowing the rules.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { redactSecrets } from "../subprocess-env.js";
+const execFileAsync = promisify(execFile);
+/** Ceiling for any redacted free text surfaced on the result (error detail, summary) — one named place. */
+const MAX_REDACTED_TEXT_LENGTH = 500;
+/* v8 ignore start -- real-SDK path: imports @anthropic-ai/claude-agent-sdk and spawns a live session; tests
+   inject a fake AgentSdkQueryFn instead (same convention as the CLI driver's injected SpawnFn). */
+const defaultQuery = (input) => {
+    async function* stream() {
+        const sdk = (await import("@anthropic-ai/claude-agent-sdk"));
+        for await (const message of sdk.query({ prompt: input.prompt, options: input.options })) {
+            yield message;
+        }
+    }
+    return stream();
+};
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? value : null;
+}
+async function listWorktreeChangedFiles(cwd) {
+    const [tracked, untracked] = await Promise.all([
+        execFileAsync("git", ["-C", cwd, "diff", "--name-only", "HEAD", "--"]),
+        execFileAsync("git", ["-C", cwd, "ls-files", "--others", "--exclude-standard"]),
+    ]);
+    return Array.from(new Set([tracked.stdout, untracked.stdout]
+        .join("\n")
+        .split(/\r?\n/)
+        .map((file) => file.trim())
+        .filter(Boolean)));
+}
+/** Fold one assistant message's content blocks into the transcript/changed-file accumulators. */
+function foldAssistantMessage(message, transcript, changedFiles) {
+    const content = asRecord(message.message)?.content;
+    if (!Array.isArray(content))
+        return;
+    for (const rawBlock of content) {
+        const block = asRecord(rawBlock);
+        if (!block)
+            continue;
+        if (block.type === "text" && typeof block.text === "string") {
+            transcript.push(block.text);
+        }
+        else if (block.type === "tool_use" && typeof block.name === "string") {
+            const filePath = asRecord(block.input)?.file_path;
+            if (typeof filePath === "string")
+                changedFiles.add(filePath);
+        }
+    }
+}
+/**
+ * A `CodingAgentDriver` that runs the attempt through an in-process Agent-SDK `query()` session in the task's
+ * working directory. Mirrors the CLI-subprocess driver's contract: structured failure results (never a throw),
+ * `changedFiles` reported only on success (the CLI driver cannot know them on failure, and #4296's parity suite
+ * holds both implementations to the same shape), and `task.instructions` forwarded verbatim as the prompt — the
+ * acceptance-criteria document already lives inside the worktree at `task.acceptanceCriteriaPath` (#4271).
+ */
+export function createAgentSdkCodingAgentDriver(options = {}) {
+    const query = options.query ?? defaultQuery;
+    const listChangedFiles = options.listChangedFiles ?? listWorktreeChangedFiles;
+    return {
+        async run(task) {
+            const transcriptParts = [];
+            const changedFiles = new Set();
+            let resultMessage = null;
+            try {
+                const stream = query({
+                    prompt: task.instructions,
+                    options: {
+                        cwd: task.workingDirectory,
+                        maxTurns: task.maxTurns,
+                        // Same edit-permission scope as the CLI-subprocess driver (#4266): `--permission-mode acceptEdits`
+                        // there, `acceptEdits` here — file edits run unattended inside the scoped worktree, nothing broader.
+                        permissionMode: "acceptEdits",
+                        hooks: options.hooks,
+                    },
+                });
+                for await (const message of stream) {
+                    if (message.type === "assistant") {
+                        foldAssistantMessage(message, transcriptParts, changedFiles);
+                    }
+                    else if (message.type === "result") {
+                        resultMessage = message;
+                    }
+                }
+            }
+            catch (error) {
+                const detail = redactSecrets(error instanceof Error ? error.message : String(error)).slice(0, MAX_REDACTED_TEXT_LENGTH);
+                return {
+                    ok: false,
+                    changedFiles: [],
+                    summary: "agent sdk session threw",
+                    transcript: redactSecrets(transcriptParts.join("\n")),
+                    error: `agent_sdk_thrown: ${detail}`,
+                };
+            }
+            const turnsUsed = typeof resultMessage?.num_turns === "number" ? resultMessage.num_turns : undefined;
+            // Real dollar cost: the SDK's own SDKResultSuccess/SDKResultError message types both declare
+            // `total_cost_usd: number` unconditionally -- present whenever a result message arrived at all, success
+            // or not (the session was billed either way), absent only when the stream produced no result message.
+            const costUsd = typeof resultMessage?.total_cost_usd === "number" ? resultMessage.total_cost_usd : undefined;
+            const resultText = typeof resultMessage?.result === "string" ? redactSecrets(resultMessage.result) : "";
+            const transcript = redactSecrets([...transcriptParts, ...(resultText ? [resultText] : [])].join("\n"));
+            // A stream that ends without a `result` frame is a protocol failure, not a silent success.
+            if (!resultMessage) {
+                return {
+                    ok: false,
+                    changedFiles: [],
+                    summary: "agent sdk stream ended without a result message",
+                    transcript,
+                    error: "agent_sdk_no_result",
+                };
+            }
+            if (resultMessage.subtype !== "success" || resultMessage.is_error === true) {
+                const subtype = typeof resultMessage.subtype === "string" ? resultMessage.subtype : "unknown";
+                return {
+                    ok: false,
+                    changedFiles: [],
+                    summary: "agent sdk session did not complete successfully",
+                    transcript,
+                    turnsUsed,
+                    costUsd,
+                    error: `agent_sdk_${subtype === "success" ? "errored" : subtype}`,
+                };
+            }
+            let worktreeChangedFiles;
+            try {
+                worktreeChangedFiles = await listChangedFiles(task.workingDirectory);
+            }
+            catch (error) {
+                const detail = redactSecrets(error instanceof Error ? error.message : String(error)).slice(0, MAX_REDACTED_TEXT_LENGTH);
+                return {
+                    ok: false,
+                    changedFiles: [],
+                    summary: "agent sdk changed-file enumeration failed",
+                    transcript,
+                    turnsUsed,
+                    costUsd,
+                    error: `agent_sdk_changed_files_unavailable: ${detail}`,
+                };
+            }
+            const allChangedFiles = Array.from(new Set([...changedFiles, ...worktreeChangedFiles]));
+            return {
+                ok: true,
+                changedFiles: allChangedFiles,
+                summary: resultText.slice(0, MAX_REDACTED_TEXT_LENGTH) || `coding agent completed with ${allChangedFiles.length} changed file(s)`,
+                transcript,
+                turnsUsed,
+                costUsd,
+            };
+        },
+    };
+}

package/dist/miner/attempt-log.d.ts

@@ -0,0 +1,29 @@
+import type { CodingAgentExecutionMode } from "./coding-agent-mode.js";
+export declare const ATTEMPT_LOG_EVENT_TYPES: readonly ["attempt_started", "attempt_tool_edit", "attempt_shadow", "attempt_succeeded", "attempt_failed", "attempt_aborted"];
+export type AttemptLogEventType = (typeof ATTEMPT_LOG_EVENT_TYPES)[number];
+export type AttemptLogEvent = {
+    eventType: AttemptLogEventType;
+    attemptId: string;
+    actionClass: string;
+    mode: CodingAgentExecutionMode;
+    reason: string;
+    payload?: Record<string, unknown> | undefined;
+};
+export type NormalizedAttemptLogEvent = {
+    eventType: AttemptLogEventType;
+    attemptId: string;
+    actionClass: string;
+    mode: CodingAgentExecutionMode;
+    reason: string;
+    payloadJson: string;
+};
+/** Validate and normalize an attempt-log row before append. Fail-closed on unknown types/modes. */
+export declare function normalizeAttemptLogEvent(input: unknown): NormalizedAttemptLogEvent;
+/** Serialize normalized events as JSONL (one attempt's trace). Pure. */
+export declare function formatAttemptLogJsonl(events: readonly NormalizedAttemptLogEvent[]): string;
+/** In-memory appender for tests and local tooling — production persistence uses `gittensory-miner/lib/attempt-log.js`. */
+export declare function createAttemptLogBuffer(): {
+    append: (event: AttemptLogEvent) => NormalizedAttemptLogEvent;
+    events: () => readonly NormalizedAttemptLogEvent[];
+    jsonl: () => string;
+};