scoutline 0.23.0 → 0.24.1

package/README.md

@@ -416,7 +416,7 @@ executor preflight, Provider selection, and `doctor`.
 | `search` | Yes | Yes | Yes | Yes | Yes (incl. `type: "video"`) | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Parallel (declarative semantic), Jina (neural web search) |
 | `vision.interpret-image` (analyze) | Yes | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | Provider-specific media limits; uncached |
 | `vision.ui-artifact` (ui-to-code) | Yes | Available | No | No | No | No | No | No | No | No | No | No | No | No | No | Live-attested; conformance-gated |
-| `vision.extract-text` | Yes | Pending | No | No | No | No | No | No | No | No | No | No | No | No | No | Implemented, pending live conformance |
+| `vision.extract-text` | Yes (GLM-OCR engine: PDF ≤50MB, images ≤10MB, content-hash cached; exhaustion falls back to the vision model) | Pending | No | No | No | No | No | No | No | No | No | No | No | No | No | Implemented, pending live conformance |
 | `vision.diagnose-error` | Yes | Available | No | No | No | No | No | No | No | No | No | No | No | No | No | Live-attested; conformance-gated |
 | `vision.diagram` | Yes | Pending | No | No | No | No | No | No | No | No | No | No | No | No | No | Implemented, pending live conformance |
 | `vision.chart` | Yes | Pending | No | No | No | No | No | No | No | No | No | No | No | No | No | Implemented, pending live conformance |
@@ -428,6 +428,7 @@ executor preflight, Provider selection, and `doctor`.
 | `crawl` | **No** | **No** | Yes | No | No | Yes (async) | No | No | No | No | No | Yes (sync) | No | **No** | No | Tavily sync; Firecrawl async (resumable after Ctrl-C) |
 | `map` | **No** | **No** | Yes | No | No | Yes | No | No | No | No | No | Yes | No | **No** | No | URL-set discovery; no per-page content |
 | `research` | **No** | **No** | Yes | Yes | **No** | **No** | Yes | Yes | Yes | Yes | Yes | No | No | **No** | No | Tavily, Exa, Parallel, Perplexity (Agent API `high` preset), Jina DeepSearch, You.com, and Linkup research report synthesis |
+| `investigation` (EvidencePack) | Yes | **No** (no reader) | Yes | Yes | **No** (no reader) | Yes | Yes | **No** (no reader) | Yes | Yes | Yes | Yes | **No** (no reader) | **No** (no reader) | **No** (no reader) | Provider-composed — supplied by the search+reader supplier union (Z.AI, Tavily, Exa, Firecrawl, Parallel, Jina AI, You.com, Linkup, Spider.cloud); `--synthesize` is Z.AI-only |
 | `repo search` / `repo read` / `repo tree` / `repo brief` | Yes | **No** | **No** | **No** | **No** | **No** | **No** | **No** | **No** | No | No | No | No | No | No | Participates in selection; only Z.AI supplies `repository-exploration` |
 | `tools`, `tool`, `call` (Raw tools) | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | Z.AI-only; accepts but ignores `--provider` |
 | `code` (Code Mode) | Yes | No | No | No | No | No | No | No | No | No | No | No | No | No | No | Z.AI-only; accepts but ignores `--provider` |
@@ -525,6 +526,53 @@ the supplier wire supports them (rejected with `UNSUPPORTED_OPTION`
 elsewhere — never silently dropped). `science get <identifier>` fetches
 one work by bare DOI, numeric PMID, or arXiv id.
 
+### Investigation (`investigate`)
+
+`scoutline investigate <question>` runs a local, transparent,
+cache-resumable pipeline ([ADR-0013](https://github.com/vikasagarwal101/scoutline/blob/main/docs/adr/0013-local-investigation-pipeline.md)):
+plan sub-queries → fan-out search → Fusion merge → read the top
+`--sources` (default 5) → deterministic passage extraction → an
+EvidencePack (`schemaVersion` 1). No provider-side job runs — distinct
+from Research, an opaque billed provider job. The pack is data, not
+prose: agents consume it directly and text output modes fall back to
+JSON (agent-synthesis is the default; you write the prose). Warm re-runs
+replay the response cache (`coverage.cacheHits` reflects it).
+
+```bash
+scoutline investigate "rust async runtime benchmarks"
+scoutline investigate "rust async | rust tokio"    # pipes split explicit sub-queries
+scoutline investigate "topic" --provider tavily,exa --sources 8
+scoutline investigate "topic" --max-chars 20000 --synthesize
+```
+
+Sub-query planning precedence: explicit pipes (the `--merge` grammar) >
+`--context <path>` (a local notes file — it never leaves the machine,
+only the derived sub-query strings are searched) > deterministic
+templates of the bare question (original, key terms,
+overview/evidence/criticism; deduped, capped at 5). Provider selection
+reuses search's fan-out activation tiers verbatim (comma-list/`all`
+fan-out, single pin, `config set fanout true`). Cost is stated in one
+stderr notice before any billable work: N sub-queries × M arms billable
+searches + up to K reads.
+
+Controls: `--sources <n>`, `--max-chars <n>` (passages trim first, late
+sources drop; the full untrimmed pack is saved and recoverable via
+`scoutline history show <ref>`), `--no-cache`, `--no-journal`, `--save`,
+`--isolated`. Sources surfaced but unread land in `coverage.unread` with
+a reason code — never silently dropped. `--synthesize` attaches an
+additive `brief` via Z.AI chat (Z.AI-only; absent by default; a
+synthesis failure is the run's terminal error, never a degraded pack).
+`--depth`, `--arms`, and `--budget-tokens` are rejected with
+`VALIDATION_ERROR` by design.
+
+`--verify` turns the positional into a statement: sentence-claims
+(≤ 8, fail-loud) are searched verbatim and matched to the extracted
+passages; the pack gains an additive `verify` block — per claim, a
+verdict (`corroborated` / `contradicted` / `unresolved`), evidence
+pointers, and a negation-cue count. `contradicted` is a disclosed
+negation-cue heuristic (hint-grade), not semantic judgment;
+`--context` + `--verify` is a mode-conflict VALIDATION_ERROR.
+
 ## Usage
 
 The CLI is self-documenting. Use `--help` at any level:

package/dist/capabilities/investigation.d.ts

@@ -0,0 +1,134 @@
+/**
+ * EvidencePack schema + total decoder (T1, docs/plans/investigate-pipeline
+ * PRD AC-6; ADR-0013 §7).
+ *
+ * The EvidencePack is the self-contained deliverable of an Investigation
+ * (CONTEXT.md glossary): question, sub-queries, sources with per-source
+ * content hashes and extracted passages, and a coverage block. The pack is
+ * data, not prose — agent-synthesis is the contract; `--synthesize` (T7)
+ * attaches a `brief` additively and is not part of this schema.
+ *
+ * This module declares the pack type, its total decoder, and the
+ * contentSha256 shape predicate. It imports NOTHING from other src modules
+ * (self-contained by ticket contract; hashing itself lands in T5 — this
+ * module only validates hash *shape*).
+ *
+ * Decoder discipline mirrors capabilities/reader.ts exactly:
+ *   - accepts `unknown`, returns the pack or `null`, never throws,
+ *     never trusts a generic cast;
+ *   - reject primitives and arrays at the top level;
+ *   - `schemaVersion` MUST be the literal number 1 (rejects "1", 1.5,
+ *     bigints, any future version);
+ *   - `title: null` is a valid decoded value (reader parity);
+ *   - optional fields preserved verbatim when present.
+ */
+/** `[start, end)` character offsets into the source `content` string. */
+export type CharRange = readonly [number, number];
+/**
+ * One extracted passage. `quote` is pinned to the content by `charRange`:
+ * `content.slice(...charRange) === quote` for every passage (D4). The pin
+ * is enforced where content is available (assembly in T5, extraction in
+ * T3); the decoder enforces the shape so a decoded pack is at least
+ * structurally sound.
+ */
+export interface EvidencePassage {
+    readonly quote: string;
+    readonly charRange: CharRange;
+}
+/** One read source: reader-envelope fields + passages. */
+export interface EvidenceSource {
+    readonly url: string;
+    /** The URL the Reader actually fetched (provider rewrite possible). */
+    readonly finalUrl: string;
+    /** Page title if the provider returned one; `null` if absent (reader parity). */
+    readonly title: string | null;
+    /** ISO-8601 UTC Z timestamp captured when the read resolved (D5). */
+    readonly fetchedAt: string;
+    /** Provider id that surfaced the source (search-arm winner). */
+    readonly provider: string;
+    /** Mirrors the read `format`; `"markdown"` or `"text"`. */
+    readonly contentFormat: "markdown" | "text";
+    /** Lowercase hex SHA-256 of the UTF-8 normalized content string (D5). */
+    readonly contentSha256: string;
+    readonly passages: readonly EvidencePassage[];
+}
+/** Coverage block: how much of the planned grid actually produced evidence. */
+export interface EvidenceCoverage {
+    /** Number of planned sub-queries. */
+    readonly subQueries: number;
+    /** Number of search arms actually used. */
+    readonly armsUsed: number;
+    /** Number of post-cluster candidate sources surfaced. */
+    readonly sourcesConsidered: number;
+    /** Number of sources whose read resolved successfully. */
+    readonly sourcesRead: number;
+    /** Count of search arms + reads served warm from cache (D5). */
+    readonly cacheHits: number;
+    /**
+     * Sources surfaced but not read, each with a reason code only —
+     * redacted, no error prose crossing the interface (house rule, D5).
+     */
+    readonly unread: readonly {
+        readonly url: string;
+        readonly reason: string;
+    }[];
+}
+/** The self-contained Investigation deliverable (PRD AC-6). */
+export interface EvidencePack {
+    readonly schemaVersion: 1;
+    readonly question: string;
+    readonly subQueries: readonly string[];
+    readonly sources: readonly EvidenceSource[];
+    readonly coverage: EvidenceCoverage;
+    /**
+     * investigate-verify lane T2 (PRD AC-6): the additive claim-
+     * corroboration block. ABSENT on question-mode packs (byte-identity
+     * pin); present only when `investigate --verify` assembled the pack.
+     */
+    readonly verify?: VerifyBlock;
+}
+/** The deterministic verdict vocabulary (cue heuristic, PRD AC-5). */
+export type ClaimVerdict = "corroborated" | "contradicted" | "unresolved";
+/** One evidence pointer into the pack's own `sources` array. */
+export interface ClaimEvidencePointer {
+    readonly sourceIndex: number;
+    readonly passageIndex: number;
+}
+/**
+ * One claim row: the claim text, its verdict, the count of cue-bearing
+ * matching passages (agent re-judgment input — the cue heuristic is
+ * DISCLOSED hint-grade), and first-encounter evidence pointers.
+ */
+export interface ClaimRow {
+    readonly text: string;
+    readonly verdict: ClaimVerdict;
+    readonly negationCues: number;
+    readonly evidence: readonly ClaimEvidencePointer[];
+}
+/** The additive verify block: the statement plus one row per claim. */
+export interface VerifyBlock {
+    readonly statement: string;
+    readonly claims: readonly ClaimRow[];
+}
+/**
+ * `contentSha256` validity: a 64-character lowercase hex string —
+ * the exact shape of `createHash("sha256")…digest("hex")` output.
+ * Ruling (ticket T1): hex-shape is enforced at decode, so an
+ * uppercased, truncated, or non-hex string fails closed. Full
+ * recompute-vs-content binding belongs to assembly (T5), which is the
+ * only place the paired content string exists.
+ */
+export declare function isValidContentSha256(value: unknown): value is string;
+/**
+ * Decode an `unknown` value into a canonical `EvidencePack`. Returns the
+ * typed pack on success, `null` for any malformed value. NEVER throws,
+ * NEVER trusts a generic cast.
+ *
+ * `title: null` is valid (reader parity). `sources` and `passages` may be
+ * empty arrays (a pack whose every read failed is still a valid, sad pack).
+ * `brief` (T7) is additive: unknown keys are NOT rejected — a decoded pack
+ * carries exactly the AC-6 keys, and an input carrying extra keys decodes
+ * to the canonical subset.
+ */
+export declare function decodeInvestigationPack(value: unknown): EvidencePack | null;
+//# sourceMappingURL=investigation.d.ts.map

package/dist/capabilities/investigation.d.ts.map

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

package/dist/capabilities/investigation.js

@@ -0,0 +1,278 @@
+/**
+ * EvidencePack schema + total decoder (T1, docs/plans/investigate-pipeline
+ * PRD AC-6; ADR-0013 §7).
+ *
+ * The EvidencePack is the self-contained deliverable of an Investigation
+ * (CONTEXT.md glossary): question, sub-queries, sources with per-source
+ * content hashes and extracted passages, and a coverage block. The pack is
+ * data, not prose — agent-synthesis is the contract; `--synthesize` (T7)
+ * attaches a `brief` additively and is not part of this schema.
+ *
+ * This module declares the pack type, its total decoder, and the
+ * contentSha256 shape predicate. It imports NOTHING from other src modules
+ * (self-contained by ticket contract; hashing itself lands in T5 — this
+ * module only validates hash *shape*).
+ *
+ * Decoder discipline mirrors capabilities/reader.ts exactly:
+ *   - accepts `unknown`, returns the pack or `null`, never throws,
+ *     never trusts a generic cast;
+ *   - reject primitives and arrays at the top level;
+ *   - `schemaVersion` MUST be the literal number 1 (rejects "1", 1.5,
+ *     bigints, any future version);
+ *   - `title: null` is a valid decoded value (reader parity);
+ *   - optional fields preserved verbatim when present.
+ */
+// ---------------------------------------------------------------------------
+// Field predicates
+// ---------------------------------------------------------------------------
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+/**
+ * `contentSha256` validity: a 64-character lowercase hex string —
+ * the exact shape of `createHash("sha256")…digest("hex")` output.
+ * Ruling (ticket T1): hex-shape is enforced at decode, so an
+ * uppercased, truncated, or non-hex string fails closed. Full
+ * recompute-vs-content binding belongs to assembly (T5), which is the
+ * only place the paired content string exists.
+ */
+export function isValidContentSha256(value) {
+    if (typeof value !== "string" || value.length !== 64)
+        return false;
+    for (const ch of value) {
+        const code = ch.charCodeAt(0);
+        const isDigit = code >= 48 && code <= 57;
+        const isLowerHex = (code >= 97 && code <= 102) || isDigit;
+        if (!isLowerHex)
+            return false;
+    }
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Total decoder
+// ---------------------------------------------------------------------------
+function decodeCharRange(value) {
+    // PR #264 F2: the documented `[start, end)` invariant, enforced at
+    // decode — safe integers, non-negative start, strictly increasing
+    // (an empty range cannot quote a non-empty passage).
+    return (Array.isArray(value) &&
+        value.length === 2 &&
+        Number.isSafeInteger(value[0]) &&
+        Number.isSafeInteger(value[1]) &&
+        value[0] >= 0 &&
+        value[1] > value[0]);
+}
+function decodePassage(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (!isNonEmptyString(value.quote))
+        return null;
+    if (!decodeCharRange(value.charRange))
+        return null;
+    return { quote: value.quote, charRange: [value.charRange[0], value.charRange[1]] };
+}
+function decodeSource(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (!isNonEmptyString(value.url))
+        return null;
+    if (!isNonEmptyString(value.finalUrl))
+        return null;
+    const title = value.title;
+    if (title !== null && typeof title !== "string")
+        return null;
+    if (!isNonEmptyString(value.fetchedAt))
+        return null;
+    if (!isNonEmptyString(value.provider))
+        return null;
+    if (value.contentFormat !== "markdown" && value.contentFormat !== "text")
+        return null;
+    if (!isValidContentSha256(value.contentSha256))
+        return null;
+    if (!Array.isArray(value.passages))
+        return null;
+    const passages = [];
+    for (const raw of value.passages) {
+        const passage = decodePassage(raw);
+        if (passage === null)
+            return null;
+        passages.push(passage);
+    }
+    return {
+        url: value.url,
+        finalUrl: value.finalUrl,
+        title: title,
+        fetchedAt: value.fetchedAt,
+        provider: value.provider,
+        contentFormat: value.contentFormat,
+        contentSha256: value.contentSha256,
+        passages,
+    };
+}
+function decodeCoverage(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (!isFiniteNumber(value.subQueries))
+        return null;
+    if (!isFiniteNumber(value.armsUsed))
+        return null;
+    if (!isFiniteNumber(value.sourcesConsidered))
+        return null;
+    if (!isFiniteNumber(value.sourcesRead))
+        return null;
+    if (!isFiniteNumber(value.cacheHits))
+        return null;
+    if (!Array.isArray(value.unread))
+        return null;
+    const unread = [];
+    for (const raw of value.unread) {
+        if (!isPlainObject(raw))
+            return null;
+        if (!isNonEmptyString(raw.url))
+            return null;
+        if (!isNonEmptyString(raw.reason))
+            return null;
+        unread.push({ url: raw.url, reason: raw.reason });
+    }
+    return {
+        subQueries: value.subQueries,
+        armsUsed: value.armsUsed,
+        sourcesConsidered: value.sourcesConsidered,
+        sourcesRead: value.sourcesRead,
+        cacheHits: value.cacheHits,
+        unread,
+    };
+}
+/**
+ * Decode an `unknown` value into a canonical `EvidencePack`. Returns the
+ * typed pack on success, `null` for any malformed value. NEVER throws,
+ * NEVER trusts a generic cast.
+ *
+ * `title: null` is valid (reader parity). `sources` and `passages` may be
+ * empty arrays (a pack whose every read failed is still a valid, sad pack).
+ * `brief` (T7) is additive: unknown keys are NOT rejected — a decoded pack
+ * carries exactly the AC-6 keys, and an input carrying extra keys decodes
+ * to the canonical subset.
+ */
+export function decodeInvestigationPack(value) {
+    // PR #264 F1: total containment for the never-throws contract — a
+    // throwing getter or Proxy trap on untrusted input must surface as
+    // a fail-closed null, never as an exception out of the decoder.
+    try {
+        return decodeInvestigationPackInner(value);
+    }
+    catch {
+        return null;
+    }
+}
+function decodeInvestigationPackInner(value) {
+    if (!isPlainObject(value))
+        return null;
+    if (value.schemaVersion !== 1)
+        return null;
+    if (!isNonEmptyString(value.question))
+        return null;
+    if (!Array.isArray(value.subQueries))
+        return null;
+    for (const q of value.subQueries) {
+        if (!isNonEmptyString(q))
+            return null;
+    }
+    if (!Array.isArray(value.sources))
+        return null;
+    const sources = [];
+    for (const raw of value.sources) {
+        const source = decodeSource(raw);
+        if (source === null)
+            return null;
+        sources.push(source);
+    }
+    const coverage = decodeCoverage(value.coverage);
+    if (coverage === null)
+        return null;
+    // investigate-verify lane T2 (D4): additive-optional `verify` — absent
+    // keeps the canonical subset (question-mode byte identity); present is
+    // validated row-by-row and fails closed on any malformed row.
+    const verify = decodeVerifyBlock(value.verify, sources.length, (sourceIndex) => sources[sourceIndex] === undefined ? 0 : sources[sourceIndex].passages.length);
+    if (verify === undefined)
+        return null;
+    return {
+        schemaVersion: 1,
+        question: value.question,
+        subQueries: [...value.subQueries],
+        sources,
+        coverage,
+        ...(verify !== null ? { verify } : {}),
+    };
+}
+const CLAIM_VERDICTS = ["corroborated", "contradicted", "unresolved"];
+/**
+ * Decode the additive verify block. `undefined` = malformed (the caller
+ * fails closed); `null` = absent (the canonical subset stands); the
+ * decoded block = present + valid.
+ *
+ * PR #270 babysit: pointer RANGE is cross-checked against the decoded
+ * sources of the SAME pack (sourceIndex < sourceCount; passageIndex <
+ * that source's passage count) — a shape-safe but out-of-range pointer
+ * is malformed, INCLUDING any pointer into a zero-source pack (it can
+ * never dereference; assembly emits empty evidence there by
+ * construction, so only hand-built input reaches that arm).
+ */
+function decodeVerifyBlock(value, sourceCount, passageCountAt) {
+    if (value === undefined)
+        return null;
+    if (!isPlainObject(value))
+        return undefined;
+    if (!isNonEmptyString(value.statement))
+        return undefined;
+    if (!Array.isArray(value.claims))
+        return undefined;
+    const claims = [];
+    for (const raw of value.claims) {
+        if (!isPlainObject(raw))
+            return undefined;
+        if (!isNonEmptyString(raw.text))
+            return undefined;
+        if (typeof raw.verdict !== "string" || !CLAIM_VERDICTS.includes(raw.verdict)) {
+            return undefined;
+        }
+        if (typeof raw.negationCues !== "number" ||
+            !Number.isSafeInteger(raw.negationCues) ||
+            raw.negationCues < 0) {
+            return undefined;
+        }
+        if (!Array.isArray(raw.evidence))
+            return undefined;
+        const evidence = [];
+        for (const pointer of raw.evidence) {
+            if (!isPlainObject(pointer))
+                return undefined;
+            if (!isSafeIndex(pointer.sourceIndex) || !isSafeIndex(pointer.passageIndex)) {
+                return undefined;
+            }
+            if (pointer.sourceIndex >= sourceCount ||
+                pointer.passageIndex >= passageCountAt(pointer.sourceIndex)) {
+                return undefined;
+            }
+            evidence.push({ sourceIndex: pointer.sourceIndex, passageIndex: pointer.passageIndex });
+        }
+        claims.push({
+            text: raw.text,
+            verdict: raw.verdict,
+            negationCues: raw.negationCues,
+            evidence,
+        });
+    }
+    return { statement: value.statement, claims };
+}
+/** Finite, safe, non-negative integer index (evidence pointer guard). */
+function isSafeIndex(value) {
+    return (typeof value === "number" && Number.isSafeInteger(value) && value >= 0);
+}
+//# sourceMappingURL=investigation.js.map

package/dist/capabilities/investigation.js.map

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

package/dist/commands/archive.d.ts

@@ -80,6 +80,13 @@ export declare function fetchWithArchiveBackoff<T = Response>(url: string, optio
     timeout?: number;
     headers?: Record<string, string>;
     sleep?: (ms: number) => Promise<void>;
+    /**
+     * Abort-timer seam (the flake class: rows exercising non-timeout
+     * paths must not arm raceable real timers against local mocks —
+     * inject a recording never-fires stub; the default is the real
+     * setTimeout). The returned handle flows to clearTimeout verbatim.
+     */
+    armTimer?: (ms: number, abort: () => void) => ReturnType<typeof setTimeout>;
 }, consumer?: (res: Response) => Promise<T>): Promise<T>;
 /**
  * Enumerate captures via CDX server.
@@ -171,8 +178,18 @@ export declare function parseArchiveArgs(args: readonly string[]): {
     readonly flags: Record<string, string | boolean>;
     readonly showHelp: boolean;
 };
+export declare function parseArchiveTokens(tokens: readonly string[]): {
+    readonly subcommand?: string;
+    readonly positional: readonly string[];
+    readonly flags: Record<string, string | boolean>;
+    readonly showHelp: boolean;
+};
 /**
- * Dispatcher handler for `archive` in `src/index.ts`.
+ * Dispatcher handler for `archive` in `src/index.ts`. INPUT CONTRACT:
+ * `args` are main()-normalized dispatch tokens (the equals-form seam has
+ * run). Raw-argv callers use {@link parseArchiveArgs} — the normalizing
+ * boundary; re-normalizing here would re-split produced values that
+ * start with `--` (the double-application defect, PR-278 review).
  */
 export declare function handleArchive(args: string[], outputMode: OutputMode, deps: HandlerDependencies, forceRaw?: boolean): Promise<number>;
 //# sourceMappingURL=archive.d.ts.map

package/dist/commands/archive.d.ts.map

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

package/dist/commands/archive.js

@@ -18,6 +18,7 @@
 import { invokeCommand } from "../command-invocation.js";
 import { ValidationError, TimeoutError, NetworkError } from "../lib/errors.js";
 import { rejectSmuggledMaxChars } from "../lib/output-budget.js";
+import { normalizeEqualsFormFlags } from "../lib/equals-form.js";
 import { MAX_BUFFERED_RESPONSE_BYTES, readBoundedResponseBody } from "../lib/bounded-body.js";
 import { DEFAULT_USER_AGENT, DEFAULT_FETCH_TIMEOUT_MS } from "./fetch.js";
 import { extractSections, extractSectionsHashOnly, diffDocuments, isHtmlContentType, } from "../lib/section-diff.js";
@@ -58,11 +59,12 @@ export const DEFAULT_ARCHIVE_TIMEOUT_MS = 30000;
 export async function fetchWithArchiveBackoff(url, options = {}, consumer) {
     const timeoutMs = options.timeout ?? DEFAULT_ARCHIVE_TIMEOUT_MS;
     const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const armTimer = options.armTimer ?? ((ms, abort) => setTimeout(abort, ms));
     const maxRetries = 3;
     let delay = 1000;
     for (let attempt = 0; attempt <= maxRetries; attempt++) {
         const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const timer = armTimer(timeoutMs, () => controller.abort());
         try {
             const res = await fetch(url, {
                 headers: {
@@ -766,12 +768,21 @@ export async function archiveDiffCommand(url, options = {}) {
  * Parse CLI args for archive command.
  */
 export function parseArchiveArgs(args) {
+    // #263: `--flag=value` ≡ `--flag value` (central seam). The EXPORTED
+    // entry normalizes for direct raw-argv callers (tests); main()'s
+    // dispatch path calls parseArchiveTokens with already-normalized
+    // tokens — the seam is single-application by construction (a second
+    // pass would re-split a produced VALUE that starts with `--` and
+    // contains `=`, breaking value preservation: `--foo=--bar=baz`).
+    return parseArchiveTokens(normalizeEqualsFormFlags(args));
+}
+export function parseArchiveTokens(tokens) {
     let showHelp = false;
     const flags = {};
     const positional = [];
     let i = 0;
-    while (i < args.length) {
-        const arg = args[i];
+    while (i < tokens.length) {
+        const arg = tokens[i];
         if (arg === undefined)
             break;
         if (arg === "--help" || arg === "-h") {
@@ -779,14 +790,8 @@ export function parseArchiveArgs(args) {
             i++;
         }
         else if (arg.startsWith("--")) {
-            if (arg.includes("=")) {
-                // The `--flag=value` form is not supported: without this gate the
-                // token parses as a boolean flag under a garbage key
-                // ("timeout=300") and is silently dropped (#172 review F6).
-                throw new ValidationError(`Invalid flag "${arg}": the --flag=value form is not supported; pass the value as the next argument.`);
-            }
             const key = arg.slice(2);
-            const next = args[i + 1];
+            const next = tokens[i + 1];
             if (next && !next.startsWith("-")) {
                 flags[key] = next;
                 i += 2;
@@ -841,10 +846,16 @@ function parseArchiveTimeout(raw) {
     return undefined;
 }
 /**
- * Dispatcher handler for `archive` in `src/index.ts`.
+ * Dispatcher handler for `archive` in `src/index.ts`. INPUT CONTRACT:
+ * `args` are main()-normalized dispatch tokens (the equals-form seam has
+ * run). Raw-argv callers use {@link parseArchiveArgs} — the normalizing
+ * boundary; re-normalizing here would re-split produced values that
+ * start with `--` (the double-application defect, PR-278 review).
  */
 export async function handleArchive(args, outputMode, deps, forceRaw = false) {
-    const { subcommand, positional, flags, showHelp } = parseArchiveArgs(args);
+    // Single-application: main() normalized argv before dispatch; raw
+    // argv callers use parseArchiveArgs (the normalizing wrapper).
+    const { subcommand, positional, flags, showHelp } = parseArchiveTokens(args);
     if (showHelp || subcommand === undefined) {
         deps.invocation.writeStdout(ARCHIVE_HELP);
         return 0;