ai-foreman 1.5.0 → 1.6.0

package/dist/tickets/delivery.d.ts

@@ -0,0 +1,38 @@
+import type { TicketDef } from "./ticketSchema.js";
+import type { TicketState } from "./stateDb.js";
+import type { TicketBuildCompletionMode, TicketBuildMergeMethod, TicketBuildProvider } from "./setupConfig.js";
+export declare const DELIVERY_FILE = ".tickets/delivery.yaml";
+export type DeliveryBranchMode = "current" | "per-ticket" | "shared";
+export type DeliveryDependencyMode = "combine" | "wait" | "stack";
+export interface DeliveryUnit {
+    id: string;
+    tickets: string[];
+    branch_mode: DeliveryBranchMode;
+    completion?: TicketBuildCompletionMode;
+    provider?: TicketBuildProvider;
+    pr_ready?: boolean;
+    merge_method?: TicketBuildMergeMethod;
+    cleanup?: boolean;
+    depends_on?: string[];
+    dependency_mode?: DeliveryDependencyMode;
+}
+export interface DeliveryConfig {
+    version: 1;
+    units: DeliveryUnit[];
+}
+export interface DeliveryIssue {
+    path: string;
+    message: string;
+}
+export declare function loadDeliveryConfig(projectDir: string): DeliveryConfig | undefined;
+export declare function normalizeDeliveryConfig(raw: unknown): DeliveryConfig;
+export declare function validateDeliveryConfig(raw: unknown, ticketDefs?: TicketDef[]): DeliveryIssue[];
+export interface DeliveryUnitProgress {
+    unit: DeliveryUnit;
+    completed: number;
+    remaining: string[];
+    state: "complete" | "ready" | "waiting" | "resume";
+}
+export declare function deliveryProgress(config: DeliveryConfig, states: Map<string, TicketState>): DeliveryUnitProgress[];
+export declare function formatDeliverySummary(config: DeliveryConfig, states: Map<string, TicketState>): string[];
+export declare function selectDeliveryUnitForRun(config: DeliveryConfig, states: Map<string, TicketState>, skipUnitIds?: readonly string[]): DeliveryUnitProgress | undefined;

package/dist/tickets/delivery.js

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+export const DELIVERY_FILE = ".tickets/delivery.yaml";
+export function loadDeliveryConfig(projectDir) {
+    const path = join(projectDir, DELIVERY_FILE);
+    if (!existsSync(path))
+        return undefined;
+    const raw = parse(readFileSync(path, "utf8"));
+    const issues = validateDeliveryConfig(raw);
+    if (issues.length > 0) {
+        throw new Error(`${DELIVERY_FILE}:\n${issues.map((issue) => `- ${issue.path}: ${issue.message}`).join("\n")}`);
+    }
+    return normalizeDeliveryConfig(raw);
+}
+export function normalizeDeliveryConfig(raw) {
+    const value = raw;
+    return {
+        version: 1,
+        units: value.units.map((unit) => ({
+            id: String(unit.id),
+            tickets: [...unit.tickets],
+            branch_mode: unit.branch_mode,
+            ...(unit.completion ? { completion: unit.completion } : {}),
+            ...(unit.provider ? { provider: unit.provider } : {}),
+            ...(typeof unit.pr_ready === "boolean" ? { pr_ready: unit.pr_ready } : {}),
+            ...(unit.merge_method ? { merge_method: unit.merge_method } : {}),
+            ...(typeof unit.cleanup === "boolean" ? { cleanup: unit.cleanup } : {}),
+            ...(Array.isArray(unit.depends_on) ? { depends_on: [...unit.depends_on] } : {}),
+            ...(unit.dependency_mode ? { dependency_mode: unit.dependency_mode } : {}),
+        })),
+    };
+}
+export function validateDeliveryConfig(raw, ticketDefs) {
+    const issues = [];
+    if (!raw || typeof raw !== "object" || Array.isArray(raw))
+        return [{ path: "$", message: "expected an object" }];
+    const value = raw;
+    if (value.version !== undefined && value.version !== 1)
+        issues.push({ path: "version", message: "expected 1" });
+    if (!Array.isArray(value.units))
+        return [...issues, { path: "units", message: "expected an array" }];
+    const unitIds = new Set();
+    const assigned = new Map();
+    const knownTickets = ticketDefs ? new Set(ticketDefs.map((ticket) => ticket.id)) : undefined;
+    for (let index = 0; index < value.units.length; index++) {
+        const path = `units[${index}]`;
+        const unit = value.units[index];
+        if (!unit || typeof unit !== "object" || Array.isArray(unit)) {
+            issues.push({ path, message: "expected an object" });
+            continue;
+        }
+        const u = unit;
+        if (typeof u.id !== "string" || !/^[A-Za-z][A-Za-z0-9-_]*$/.test(u.id))
+            issues.push({ path: `${path}.id`, message: "expected a stable identifier" });
+        else if (unitIds.has(u.id))
+            issues.push({ path: `${path}.id`, message: `duplicate unit ID: ${u.id}` });
+        else
+            unitIds.add(u.id);
+        if (!Array.isArray(u.tickets) || u.tickets.length === 0 || !u.tickets.every((id) => typeof id === "string" && id.length > 0)) {
+            issues.push({ path: `${path}.tickets`, message: "expected a non-empty ticket ID array" });
+        }
+        else {
+            for (const id of u.tickets) {
+                if (knownTickets && !knownTickets.has(id))
+                    issues.push({ path: `${path}.tickets`, message: `unknown ticket: ${id}` });
+                const prior = assigned.get(id);
+                if (prior)
+                    issues.push({ path: `${path}.tickets`, message: `${id} is already assigned to ${prior}` });
+                else
+                    assigned.set(id, typeof u.id === "string" ? u.id : path);
+            }
+        }
+        enumValue(issues, `${path}.branch_mode`, u.branch_mode, ["current", "per-ticket", "shared"], true);
+        enumValue(issues, `${path}.completion`, u.completion, ["pr", "auto-merge", "direct-merge", "none"]);
+        enumValue(issues, `${path}.provider`, u.provider, ["auto", "github", "gitlab", "local"]);
+        enumValue(issues, `${path}.merge_method`, u.merge_method, ["squash", "merge", "rebase"]);
+        enumValue(issues, `${path}.dependency_mode`, u.dependency_mode, ["combine", "wait", "stack"]);
+        for (const field of ["pr_ready", "cleanup"]) {
+            if (u[field] !== undefined && typeof u[field] !== "boolean")
+                issues.push({ path: `${path}.${field}`, message: "expected a boolean" });
+        }
+        if (u.depends_on !== undefined && (!Array.isArray(u.depends_on) || !u.depends_on.every((id) => typeof id === "string"))) {
+            issues.push({ path: `${path}.depends_on`, message: "expected a unit ID array" });
+        }
+    }
+    const units = value.units.filter((unit) => Boolean(unit && typeof unit === "object" && !Array.isArray(unit)));
+    for (const unit of units) {
+        for (const dep of Array.isArray(unit.depends_on) ? unit.depends_on : []) {
+            if (!unitIds.has(String(dep)))
+                issues.push({ path: `units[${String(unit.id)}].depends_on`, message: `unknown unit: ${String(dep)}` });
+            if (dep === unit.id)
+                issues.push({ path: `units[${String(unit.id)}].depends_on`, message: "unit cannot depend on itself" });
+        }
+    }
+    for (const cycle of deliveryCycles(units))
+        issues.push({ path: "units", message: `dependency cycle: ${cycle}` });
+    return issues;
+}
+function enumValue(issues, path, value, allowed, required = false) {
+    if (value === undefined && !required)
+        return;
+    if (typeof value !== "string" || !allowed.includes(value))
+        issues.push({ path, message: `expected one of: ${allowed.join(", ")}` });
+}
+function deliveryCycles(units) {
+    const deps = new Map(units.map((unit) => [String(unit.id), (Array.isArray(unit.depends_on) ? unit.depends_on : []).map(String)]));
+    const visited = new Set();
+    const stack = new Set();
+    const cycles = [];
+    const walk = (id, path) => {
+        if (stack.has(id)) {
+            cycles.push([...path.slice(path.indexOf(id)), id].join(" -> "));
+            return;
+        }
+        if (visited.has(id))
+            return;
+        visited.add(id);
+        stack.add(id);
+        for (const dep of deps.get(id) ?? [])
+            if (deps.has(dep))
+                walk(dep, [...path, id]);
+        stack.delete(id);
+    };
+    for (const id of deps.keys())
+        walk(id, []);
+    return cycles;
+}
+export function deliveryProgress(config, states) {
+    const completedUnits = new Set(config.units.filter((unit) => unit.tickets.every((id) => ["done", "canceled"].includes(states.get(id)?.status ?? "planned"))).map((unit) => unit.id));
+    const out = [];
+    for (const unit of config.units) {
+        const remaining = unit.tickets.filter((id) => !["done", "canceled"].includes(states.get(id)?.status ?? "planned"));
+        const started = unit.tickets.some((id) => ["in_progress", "blocked", "done"].includes(states.get(id)?.status ?? "planned"));
+        const waiting = (unit.depends_on ?? []).some((id) => !completedUnits.has(id));
+        out.push({
+            unit,
+            completed: unit.tickets.length - remaining.length,
+            remaining,
+            state: remaining.length === 0 ? "complete" : waiting ? "waiting" : started ? "resume" : "ready",
+        });
+    }
+    return out;
+}
+export function formatDeliverySummary(config, states) {
+    return deliveryProgress(config, states).map(({ unit, completed, remaining, state }) => `${unit.id}: ${completed}/${unit.tickets.length} complete; ${remaining.length} remaining; ${unit.branch_mode}; ${unit.completion ?? "repository default"}; ${state}${(unit.depends_on ?? []).length ? `; depends on ${(unit.depends_on ?? []).join(", ")}` : ""}`);
+}
+export function selectDeliveryUnitForRun(config, states, skipUnitIds = []) {
+    const skipped = new Set(skipUnitIds);
+    const progress = deliveryProgress(config, states).filter((item) => !skipped.has(item.unit.id));
+    return progress.find((item) => item.state === "resume") ?? progress.find((item) => item.state === "ready");
+}

package/dist/tickets/importer.js

@@ -348,6 +348,10 @@ function importedItemToTicket(item, id, order, existing) {
             key: item.key ?? null,
             url: item.url ?? null,
         }),
+        source_refs: [
+            ...(existing?.source_refs ?? []).filter((ref) => !(ref.source === item.provider && ref.item === item.providerId)),
+            { source: item.provider, item: item.providerId, url: item.url ?? null },
+        ],
     };
 }
 function buildImportedNotes(item) {

package/dist/tickets/renderMarkdown.js

@@ -2,6 +2,7 @@ import { writeFileSync, readFileSync, existsSync, mkdirSync, renameSync } from "
 import { dirname, join } from "node:path";
 import { DateTime } from "luxon";
 import { buildNextQueue, buildActiveStatusRows } from "./queue.js";
+import { formatDeliverySummary, loadDeliveryConfig } from "./delivery.js";
 // ── Table helpers ─────────────────────────────────────────────────────────────
 function esc(v) {
     return v.replace(/\|/g, "\\|").replace(/\r?\n/g, "<br>");
@@ -90,6 +91,14 @@ export function renderProgressDoc(input) {
         ["Remaining Tickets", String(queueRows.length > 0 ? "≥" + queueRows.length : "0")],
     ])));
     lines.push("");
+    // Delivery units are optional; repositories without delivery.yaml retain legacy defaults.
+    const delivery = loadDeliveryConfig(projectDir);
+    if (delivery) {
+        lines.push("## Delivery Units");
+        const deliveryRows = formatDeliverySummary(delivery, states);
+        lines.push(section("DELIVERY_UNITS", deliveryRows.length > 0 ? deliveryRows.map((row) => `- ${row}`).join("\n") : "_No delivery units configured._"));
+        lines.push("");
+    }
     // Rules
     if (config.rendering.includeRulesInProgressDoc) {
         lines.push(rulesContent);

package/dist/tickets/setupConfig.d.ts

@@ -20,6 +20,9 @@ export type TicketSourceConfig = {
     email_env: string;
     token_env: string;
     jql: string;
+} | {
+    type: "url";
+    url: string;
 };
 export interface TicketPopulateSetupConfig {
     source_handling: "saved" | "prompt" | "manual";
@@ -74,6 +77,11 @@ export declare function configuredPlanningSources(projectDir: string): string[];
 export declare function externalSources(setup: TicketsSetupConfig | undefined): Extract<TicketSourceConfig, {
     type: "linear" | "jira";
 }>[];
+export declare function urlSources(setup: TicketsSetupConfig | undefined): Extract<TicketSourceConfig, {
+    type: "url";
+}>[];
+export declare function normalizedSourceKey(source: TicketSourceConfig): string;
+export declare function dedupeTicketSources(sources: TicketSourceConfig[]): TicketSourceConfig[];
 export declare function configuredDocsRoot(projectDir: string): string | undefined;
 export declare function configuredAppName(projectDir: string): string | undefined;
 export declare function configuredHarnessTargets(projectDir: string): HarnessTarget[] | undefined;

package/dist/tickets/setupConfig.js

@@ -4,7 +4,7 @@ import { join } from "node:path";
 import { parse, stringify } from "yaml";
 import { loadDefaults } from "special-agents";
 export const RAFI_CONFIG_FILE = "rafi-config.yaml";
-const AGENT_NAMES = ["builder", "qa", "planner", "ticket-maker"];
+const AGENT_NAMES = ["builder", "qa", "planner", "ticket-maker", "uninstaller"];
 const SKILL_NAMES = [
     "better-sqlite3-rebuild",
     "grill-me",
@@ -121,6 +121,34 @@ export function configuredPlanningSources(projectDir) {
 export function externalSources(setup) {
     return (setup?.sources ?? []).filter((source) => source.type === "linear" || source.type === "jira");
 }
+export function urlSources(setup) {
+    return (setup?.sources ?? []).filter((source) => source.type === "url");
+}
+export function normalizedSourceKey(source) {
+    if (source.type === "local")
+        return `local:${unique(source.paths.map((path) => path.trim())).sort().join("|")}`;
+    if (source.type === "url") {
+        const url = new URL(source.url);
+        url.hash = "";
+        url.hostname = url.hostname.toLowerCase();
+        if ((url.protocol === "https:" && url.port === "443") || (url.protocol === "http:" && url.port === "80"))
+            url.port = "";
+        return `url:${url.toString()}`;
+    }
+    if (source.type === "linear")
+        return `linear:${source.api_key_env}:${source.team_key ?? ""}:${source.filter ?? ""}`;
+    return `jira:${source.site.replace(/\/+$/, "").toLowerCase()}:${source.jql}`;
+}
+export function dedupeTicketSources(sources) {
+    const seen = new Set();
+    return sources.filter((source) => {
+        const key = normalizedSourceKey(source);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
 export function configuredDocsRoot(projectDir) {
     const raw = loadRafiConfigObject(projectDir);
     const docs = raw?.docs;
@@ -271,7 +299,24 @@ function normalizeSource(value, label) {
             jql,
         };
     }
-    throw new Error(`${label}.type: expected local, linear, or jira`);
+    if (raw.type === "url") {
+        const url = stringField(raw.url);
+        if (!url)
+            throw new Error(`${label}.url: expected a public HTTP(S) URL`);
+        let parsed;
+        try {
+            parsed = new URL(url);
+        }
+        catch {
+            throw new Error(`${label}.url: expected a valid URL`);
+        }
+        if ((parsed.protocol !== "http:" && parsed.protocol !== "https:") || parsed.username || parsed.password) {
+            throw new Error(`${label}.url: expected HTTP(S) without embedded credentials`);
+        }
+        parsed.hash = "";
+        return { type: "url", url: parsed.toString() };
+    }
+    throw new Error(`${label}.type: expected local, linear, jira, or url`);
 }
 function normalizePopulate(value, label) {
     const raw = objectOrEmpty(value, label);

package/dist/tickets/sourceFetch.d.ts

@@ -0,0 +1,24 @@
+export interface SourceFetchLimits {
+    timeoutMs: number;
+    maxBytes: number;
+    maxRedirects: number;
+}
+export declare const DEFAULT_SOURCE_FETCH_LIMITS: SourceFetchLimits;
+export interface FetchedSource {
+    requestedUrl: string;
+    finalUrl: string;
+    contentType: "html" | "text" | "markdown" | "pdf";
+    text: string;
+    bytes: number;
+    fingerprint: string;
+    snapshotPath: string;
+    metadataPath: string;
+    fetchedAt: string;
+}
+export declare function fetchAndSnapshotUrl(projectDir: string, input: string, limits?: Partial<SourceFetchLimits>): Promise<FetchedSource>;
+export declare function normalizePublicHttpUrl(input: string): string;
+export declare function assertPublicDestination(input: string): Promise<void>;
+export declare function isPublicAddress(address: string): boolean;
+export declare function htmlToText(html: string): string;
+/** Snapshot a local file outside the repository so absolute paths are never persisted. */
+export declare function snapshotExternalLocalFile(projectDir: string, inputPath: string): string;

package/dist/tickets/sourceFetch.js

@@ -0,0 +1,246 @@
+import { createHash } from "node:crypto";
+import { copyFileSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from "node:fs";
+import { lookup as dnsLookup } from "node:dns/promises";
+import { isIP } from "node:net";
+import { basename, extname, isAbsolute, join, relative, resolve } from "node:path";
+import { readdirSync } from "node:fs";
+import { parse as parseHtml } from "parse5";
+export const DEFAULT_SOURCE_FETCH_LIMITS = {
+    timeoutMs: 15_000,
+    maxBytes: 10 * 1024 * 1024,
+    maxRedirects: 5,
+};
+export async function fetchAndSnapshotUrl(projectDir, input, limits = {}) {
+    const effective = { ...DEFAULT_SOURCE_FETCH_LIMITS, ...limits };
+    const requested = normalizePublicHttpUrl(input);
+    let current = requested;
+    let response;
+    for (let redirects = 0; redirects <= effective.maxRedirects; redirects++) {
+        await assertPublicDestination(current);
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), effective.timeoutMs);
+        try {
+            response = await fetch(current, {
+                redirect: "manual",
+                signal: controller.signal,
+                headers: { Accept: "text/html,text/plain,text/markdown,application/pdf;q=0.9" },
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (response.status >= 300 && response.status < 400) {
+            const location = response.headers.get("location");
+            if (!location)
+                throw new Error(`URL redirect ${response.status} did not include Location`);
+            if (redirects === effective.maxRedirects)
+                throw new Error(`URL exceeded ${effective.maxRedirects} redirects`);
+            current = normalizePublicHttpUrl(new URL(location, current).toString());
+            continue;
+        }
+        break;
+    }
+    if (!response)
+        throw new Error("URL fetch did not produce a response");
+    if (!response.ok)
+        throw new Error(`URL fetch failed with HTTP ${response.status}`);
+    const declaredLength = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declaredLength) && declaredLength > effective.maxBytes)
+        throw new Error(`URL content exceeds ${effective.maxBytes} byte limit`);
+    const bytes = await readLimitedBody(response, effective.maxBytes);
+    const kind = detectContentType(response.headers.get("content-type"), bytes, current);
+    const text = await extractSourceText(kind, bytes);
+    const fetchedAt = new Date().toISOString();
+    const fingerprint = createHash("sha256").update(bytes).digest("hex");
+    const importsDir = join(resolve(projectDir), ".tickets", "imports");
+    mkdirSync(importsDir, { recursive: true });
+    const stamp = fetchedAt.replace(/[:.]/g, "-");
+    const stem = `url-${stamp}-${fingerprint.slice(0, 12)}`;
+    const snapshotPath = join(importsDir, `${stem}.md`);
+    const metadataPath = join(importsDir, `${stem}.json`);
+    writeFileSync(snapshotPath, `${text.trimEnd()}\n`, "utf8");
+    writeFileSync(metadataPath, `${JSON.stringify({ requestedUrl: requested, finalUrl: current, fetchedAt, bytes: bytes.length, contentType: kind, fingerprint }, null, 2)}\n`, "utf8");
+    return { requestedUrl: requested, finalUrl: current, contentType: kind, text, bytes: bytes.length, fingerprint, snapshotPath: relative(resolve(projectDir), snapshotPath), metadataPath: relative(resolve(projectDir), metadataPath), fetchedAt };
+}
+export function normalizePublicHttpUrl(input) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new Error(`invalid URL: ${input}`);
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw new Error("URL source must use HTTP or HTTPS");
+    if (url.username || url.password)
+        throw new Error("URL source must not contain credentials");
+    if (!url.hostname)
+        throw new Error("URL source must include a hostname");
+    url.hash = "";
+    return url.toString();
+}
+export async function assertPublicDestination(input) {
+    const url = new URL(normalizePublicHttpUrl(input));
+    const addresses = isIP(url.hostname)
+        ? [{ address: url.hostname }]
+        : await dnsLookup(url.hostname, { all: true, verbatim: true });
+    if (addresses.length === 0)
+        throw new Error(`URL hostname did not resolve: ${url.hostname}`);
+    for (const { address } of addresses) {
+        if (!isPublicAddress(address))
+            throw new Error(`URL destination is not public: ${url.hostname} resolved to ${address}`);
+    }
+}
+export function isPublicAddress(address) {
+    const normalized = address.toLowerCase().split("%")[0];
+    if (normalized === "::1" || normalized === "::" || normalized.startsWith("fe80:") || normalized.startsWith("fc") || normalized.startsWith("fd"))
+        return false;
+    if (normalized.startsWith("::ffff:"))
+        return isPublicAddress(normalized.slice(7));
+    if (isIP(normalized) === 6) {
+        return !(normalized.startsWith("ff") ||
+            normalized.startsWith("fe8") || normalized.startsWith("fe9") || normalized.startsWith("fea") || normalized.startsWith("feb") ||
+            normalized.startsWith("fc") || normalized.startsWith("fd") ||
+            normalized.startsWith("fec") || normalized.startsWith("fed") || normalized.startsWith("fee") || normalized.startsWith("fef") ||
+            normalized.startsWith("2001:db8:") || normalized.startsWith("2001:10:") || normalized.startsWith("2001:2:") ||
+            normalized.startsWith("100:") || normalized.startsWith("64:ff9b:1:"));
+    }
+    const parts = normalized.split(".").map(Number);
+    if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part) || part < 0 || part > 255))
+        return false;
+    const [a, b] = parts;
+    return !(a === 0 || a === 10 || a === 127 || a >= 224 ||
+        (a === 169 && b === 254) || (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && (b === 0 || b === 88 || b === 168)) ||
+        (a === 100 && b >= 64 && b <= 127) || (a === 198 && (b === 18 || b === 19 || b === 51)) ||
+        (a === 203 && b === 0));
+}
+async function readLimitedBody(response, maxBytes) {
+    if (!response.body)
+        return new Uint8Array();
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.length;
+        if (total > maxBytes) {
+            await reader.cancel();
+            throw new Error(`URL content exceeds ${maxBytes} byte limit`);
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+function detectContentType(header, bytes, url) {
+    const mime = (header ?? "").split(";", 1)[0].trim().toLowerCase();
+    const magic = Buffer.from(bytes.subarray(0, 8)).toString("latin1");
+    if (magic.startsWith("%PDF-")) {
+        if (mime && mime !== "application/pdf" && mime !== "application/octet-stream")
+            throw new Error(`content-type ${mime} conflicts with PDF magic bytes`);
+        return "pdf";
+    }
+    if (["application/pdf"].includes(mime))
+        throw new Error("response claimed PDF but PDF magic bytes were missing");
+    if (["text/html", "application/xhtml+xml"].includes(mime))
+        return "html";
+    if (["text/markdown", "text/x-markdown"].includes(mime) || /\.md(?:own)?$/i.test(new URL(url).pathname))
+        return "markdown";
+    if (!mime || mime.startsWith("text/") || mime === "application/octet-stream") {
+        if (bytes.subarray(0, Math.min(bytes.length, 1024)).includes(0))
+            throw new Error("binary URL content is not supported");
+        if ((!mime || mime === "application/octet-stream") && /^\s*(?:<!doctype\s+html|<html\b)/i.test(Buffer.from(bytes.subarray(0, 1024)).toString("utf8")))
+            return "html";
+        return "text";
+    }
+    throw new Error(`unsupported URL content-type: ${mime}`);
+}
+async function extractSourceText(kind, bytes) {
+    if (kind === "pdf") {
+        const pdfjs = await import("pdfjs-dist/legacy/build/pdf.mjs");
+        const document = await pdfjs.getDocument({ data: bytes, useWorkerFetch: false, isEvalSupported: false }).promise;
+        const pages = [];
+        for (let pageNumber = 1; pageNumber <= document.numPages; pageNumber++) {
+            const page = await document.getPage(pageNumber);
+            const content = await page.getTextContent();
+            pages.push(content.items.map((item) => "str" in item ? item.str : "").join(" "));
+            page.cleanup();
+        }
+        await document.destroy();
+        return pages.join("\n\n");
+    }
+    const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    return kind === "html" ? htmlToText(decoded) : decoded;
+}
+export function htmlToText(html) {
+    const doc = parseHtml(html);
+    const blocks = new Set(["address", "article", "aside", "blockquote", "br", "div", "footer", "h1", "h2", "h3", "h4", "h5", "h6", "header", "li", "main", "p", "section", "table", "tr"]);
+    const skip = new Set(["script", "style", "noscript", "svg"]);
+    const out = [];
+    const walk = (node) => {
+        const named = node;
+        const name = named.nodeName?.toLowerCase();
+        if (name && skip.has(name))
+            return;
+        if (name === "#text" && named.value)
+            out.push(named.value);
+        for (const child of named.childNodes ?? [])
+            walk(child);
+        if (name && blocks.has(name))
+            out.push("\n");
+    };
+    for (const child of doc.childNodes)
+        walk(child);
+    return out.join(" ").replace(/[ \t]+/g, " ").replace(/ *\n */g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+/** Snapshot a local file outside the repository so absolute paths are never persisted. */
+export function snapshotExternalLocalFile(projectDir, inputPath) {
+    const root = realpathSync(resolve(projectDir));
+    const file = realpathSync(resolve(inputPath));
+    const rel = relative(root, file);
+    if (!rel.startsWith("..") && !isAbsolute(rel))
+        return rel;
+    if (statSync(file).isDirectory()) {
+        const hash = createHash("sha256").update(file).digest("hex").slice(0, 12);
+        const targetRoot = join(root, ".tickets", "imports", `local-${hash}-${basename(file).replace(/[^A-Za-z0-9._-]/g, "-")}`);
+        let count = 0;
+        let bytes = 0;
+        const copyDirectory = (source, target) => {
+            mkdirSync(target, { recursive: true });
+            for (const entry of readdirSync(source, { withFileTypes: true })) {
+                if (entry.isSymbolicLink())
+                    continue;
+                const from = join(source, entry.name);
+                const to = join(target, entry.name);
+                if (entry.isDirectory())
+                    copyDirectory(from, to);
+                else if (entry.isFile()) {
+                    count++;
+                    bytes += statSync(from).size;
+                    if (count > 1000 || bytes > DEFAULT_SOURCE_FETCH_LIMITS.maxBytes)
+                        throw new Error("external local source directory exceeds snapshot limits");
+                    copyFileSync(from, to);
+                }
+            }
+        };
+        copyDirectory(file, targetRoot);
+        return relative(root, targetRoot);
+    }
+    if (!statSync(file).isFile())
+        throw new Error(`local source is not a file or directory: ${inputPath}`);
+    const bytes = readFileSync(file);
+    const hash = createHash("sha256").update(bytes).digest("hex").slice(0, 12);
+    const dir = join(root, ".tickets", "imports");
+    mkdirSync(dir, { recursive: true });
+    const target = join(dir, `local-${hash}-${basename(file).replace(/[^A-Za-z0-9._-]/g, "-")}${extname(file) ? "" : ".txt"}`);
+    copyFileSync(file, target);
+    return relative(root, target);
+}

package/dist/tickets/stateDb.d.ts

@@ -81,6 +81,14 @@ export interface ReviewRecommendation {
     source_json: string;
     updated_at: string | null;
 }
+export interface OperationReceipt {
+    operation_id: string;
+    operation_type: string;
+    ticket_id: string | null;
+    run_id: string;
+    completed_at: string;
+    payload_json: string;
+}
 export declare class StateDb {
     private db;
     constructor(dbPath: string);
@@ -103,5 +111,7 @@ export declare class StateDb {
     getReviewRecommendations(status?: ReviewRecommendationStatus): ReviewRecommendation[];
     getReviewRecommendation(id: number): ReviewRecommendation | undefined;
     updateReviewRecommendationStatus(id: number, status: ReviewRecommendationStatus, updatedAt: string): void;
+    getOperationReceipt(operationId: string): OperationReceipt | undefined;
+    recordOperationReceipt(receipt: OperationReceipt): boolean;
     transaction<T>(fn: () => T): T;
 }

package/dist/tickets/stateDb.js

@@ -96,12 +96,22 @@ CREATE TABLE IF NOT EXISTS review_recommendations (
   CHECK (status IN ('pending','accepted','deferred','dismissed'))
 );
 
+CREATE TABLE IF NOT EXISTS operation_receipts (
+  operation_id TEXT PRIMARY KEY,
+  operation_type TEXT NOT NULL,
+  ticket_id TEXT,
+  run_id TEXT NOT NULL,
+  completed_at TEXT NOT NULL,
+  payload_json TEXT NOT NULL DEFAULT '{}'
+);
+
 CREATE INDEX IF NOT EXISTS idx_ticket_state_status ON ticket_state(status);
 CREATE INDEX IF NOT EXISTS idx_ticket_events_ticket_id ON ticket_events(ticket_id);
 CREATE INDEX IF NOT EXISTS idx_ticket_events_timestamp ON ticket_events(timestamp);
 CREATE INDEX IF NOT EXISTS idx_validation_snapshots_timestamp ON validation_snapshots(timestamp);
 CREATE INDEX IF NOT EXISTS idx_future_work_disposition ON future_work(disposition);
 CREATE INDEX IF NOT EXISTS idx_review_recommendations_status ON review_recommendations(status);
+CREATE INDEX IF NOT EXISTS idx_operation_receipts_run ON operation_receipts(run_id);
 `;
 export class StateDb {
     db;
@@ -291,6 +301,20 @@ export class StateDb {
             .prepare("UPDATE review_recommendations SET status = ?, updated_at = ? WHERE id = ?")
             .run(status, updatedAt, id);
     }
+    // ── operation_receipts ───────────────────────────────────────────────────
+    getOperationReceipt(operationId) {
+        return this.db.prepare("SELECT * FROM operation_receipts WHERE operation_id = ?").get(operationId);
+    }
+    recordOperationReceipt(receipt) {
+        const result = this.db.prepare(`
+      INSERT OR IGNORE INTO operation_receipts (
+        operation_id,operation_type,ticket_id,run_id,completed_at,payload_json
+      ) VALUES (
+        @operation_id,@operation_type,@ticket_id,@run_id,@completed_at,@payload_json
+      )
+    `).run(receipt);
+        return result.changes === 1;
+    }
     // ── transactions ──────────────────────────────────────────────────────────
     transaction(fn) {
         return this.db.transaction(fn)();