@sayknow-cli/coding-agent 0.3.16 → 0.4.1

package/src/tools/bash-allowed-prefixes.ts

@@ -1,3 +1,11 @@
+import {
+	classifyStateArgv,
+	STATE_ACTION_NAMES,
+	type StateAction,
+	type StateArgvClassification,
+} from "../skc-runtime/state-argv";
+import { CANONICAL_SKC_WORKFLOW_SKILLS } from "../skill-state/canonical-skills";
+
 export interface BashAllowedPrefixesCheck {
 	allowed: boolean;
 	reason?: string;
@@ -11,9 +19,8 @@ export interface BashRestrictionOptions {
 
 const SHELL_CONTROL_CHARS = new Set([";", "|", "&", "<", ">", "(", ")"]);
 const UNSAFE_UNQUOTED_EXPANSION_CHARS = new Set(["$", "*", "?", "[", "]", "{", "}", "~"]);
-const STATE_FLAGS_WITH_VALUES = new Set(["--input", "--mode", "--session-id", "--thread-id", "--turn-id", "--to"]);
-const STATE_ACTIONS = new Set(["read", "write", "clear", "contract", "handoff"]);
 const ALLOWED_STATE_ACTIONS = new Set(["read", "write", "contract"]);
+const CANONICAL_STATE_TARGETS = new Set<string>(CANONICAL_SKC_WORKFLOW_SKILLS);
 const READ_ONLY_COMMANDS = new Set(["grep", "rg", "tree", "ls", "pwd", "wc", "du", "file", "stat"]);
 
 function parseShellWords(command: string): { words: string[]; reason?: string } {
@@ -21,6 +28,7 @@ function parseShellWords(command: string): { words: string[]; reason?: string }
 	let current = "";
 	let quote: "single" | "double" | null = null;
 
+	let wordStarted = false;
 	for (let index = 0; index < command.length; index += 1) {
 		const char = command[index]!;
 		const next = command[index + 1];
@@ -54,10 +62,12 @@ function parseShellWords(command: string): { words: string[]; reason?: string }
 
 		if (char === "'") {
 			quote = "single";
+			wordStarted = true;
 			continue;
 		}
 		if (char === '"') {
 			quote = "double";
+			wordStarted = true;
 			continue;
 		}
 		if (char === "`" || (char === "$" && next === "(")) {
@@ -73,9 +83,10 @@ function parseShellWords(command: string): { words: string[]; reason?: string }
 			return { words, reason: `shell expansion character '${char}' is not allowed in restricted bash commands` };
 		}
 		if (/\s/u.test(char)) {
-			if (current.length > 0) {
+			if (wordStarted) {
 				words.push(current);
 				current = "";
+				wordStarted = false;
 			}
 			continue;
 		}
@@ -83,12 +94,13 @@ function parseShellWords(command: string): { words: string[]; reason?: string }
 			return { words, reason: "backslash escapes are not allowed in restricted bash commands" };
 		}
 		current += char;
+		wordStarted = true;
 	}
 
 	if (quote !== null) {
 		return { words, reason: "unterminated quote in restricted bash command" };
 	}
-	if (current.length > 0) words.push(current);
+	if (wordStarted) words.push(current);
 	return { words };
 }
 
@@ -101,28 +113,62 @@ function wordsStartWith(words: readonly string[], prefix: readonly string[]): bo
 	return prefix.every((word, index) => words[index] === word);
 }
 
-function parseStateAction(words: readonly string[]): string | undefined {
-	const args = words.slice(2);
-	const positional: string[] = [];
-	let skipNext = false;
-	for (const arg of args) {
-		if (skipNext) {
-			skipNext = false;
-			continue;
-		}
-		if (STATE_FLAGS_WITH_VALUES.has(arg)) {
-			skipNext = true;
-			continue;
-		}
-		if (!arg.startsWith("-")) positional.push(arg);
+function malformedStateShape(): StateActionClassification {
+	return { reason: "restricted role-agent bash only allows documented `skc state` action shapes" };
+}
+
+interface ParsedStateAction {
+	action: string;
+	target: string;
+}
+
+interface StateActionClassification {
+	parsed?: ParsedStateAction;
+	reason?: string;
+}
+
+function hasDocumentedStatePositionals(classification: StateArgvClassification): boolean {
+	const [first, second, third] = classification.positionals;
+	if (third) return false;
+	if (!second) return true;
+	return STATE_ACTION_NAMES.has(first as StateAction) || STATE_ACTION_NAMES.has(second as StateAction);
+}
+
+function classifyStateAction(words: readonly string[]): StateActionClassification {
+	const classification = classifyStateArgv(words.slice(2));
+	if (
+		classification.unknownFlags.length > 0 ||
+		classification.flags.some(flag => flag.malformed) ||
+		!hasDocumentedStatePositionals(classification)
+	) {
+		return malformedStateShape();
+	}
+
+	const modeFlags = classification.flags.filter(flag => flag.name === "--mode");
+	const inputFlags = classification.flags.filter(flag => flag.name === "--input");
+	if (modeFlags.length > 1 || inputFlags.length > 1) {
+		return { reason: "restricted role-agent bash rejects repeated or conflicting `skc state` target selectors" };
+	}
+	if (classification.inputs.some(input => input.kind === "file")) {
+		return { reason: "restricted role-agent bash does not allow file-backed `skc state --input` values" };
 	}
+	if (classification.inputs.some(input => input.kind === "invalid")) return malformedStateShape();
 
-	const [first, second, third] = positional;
-	if (!first) return "read";
-	if (STATE_ACTIONS.has(first)) return second ? undefined : first;
-	if (!second) return "read";
-	if (!STATE_ACTIONS.has(second)) return undefined;
-	return third ? undefined : second;
+	const runtimeTarget = classification.runtimeSelectorCandidates.find(candidate => candidate.value)?.value;
+	const suppliedTargets = classification.selectorCandidates
+		.map(candidate => candidate.value)
+		.filter((target): target is string => target !== undefined);
+	const distinctTargets = new Set(suppliedTargets);
+	if (distinctTargets.size > 1 || (runtimeTarget && suppliedTargets.some(target => target !== runtimeTarget))) {
+		return {
+			reason:
+				"restricted role-agent bash rejects conflicting `skc state` selectors that disagree with runtime precedence",
+		};
+	}
+	if (!runtimeTarget || !CANONICAL_STATE_TARGETS.has(runtimeTarget)) {
+		return { reason: "restricted role-agent bash requires a canonical workflow skill for `skc state` commands" };
+	}
+	return { parsed: { action: classification.effectiveAction, target: runtimeTarget } };
 }
 
 function optionWords(words: readonly string[]): string[] {
@@ -189,15 +235,19 @@ function validateMatchedSkcCommand(words: readonly string[]): BashAllowedPrefixe
 	}
 
 	if (words[1] === "state") {
-		const action = parseStateAction(words);
-		if (!action) {
+		const classification = classifyStateAction(words);
+		if (!classification.parsed) {
 			return {
 				allowed: false,
-				reason: "restricted role-agent bash only allows documented `skc state` action shapes",
+				reason:
+					classification.reason ?? "restricted role-agent bash only allows documented `skc state` action shapes",
 			};
 		}
-		if (!ALLOWED_STATE_ACTIONS.has(action)) {
-			return { allowed: false, reason: `restricted role-agent bash does not allow \`skc state ${action}\`` };
+		if (!ALLOWED_STATE_ACTIONS.has(classification.parsed.action)) {
+			return {
+				allowed: false,
+				reason: `restricted role-agent bash does not allow \`skc state ${classification.parsed.action}\``,
+			};
 		}
 		return { allowed: true };
 	}

package/src/tools/bash-skill-urls.ts

@@ -1,7 +1,7 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import type { Skill } from "../extensibility/skills";
-import { type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
+import { initializeLocalRoot, type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
 import { validateRelativePath } from "../internal-urls/skill-protocol";
 import type { InternalResource } from "../internal-urls/types";
 import { normalizeLocalScheme } from "./path-utils";
@@ -162,12 +162,23 @@ async function resolveInternalUrlToPath(
 		return resolveSkillUrlToPath(url, skills);
 	}
 
+	// Managed artifact and agent resources carry session authority. Expanding
+	// either into a subprocess command would let that subprocess reopen, replace,
+	// or unlink the managed object by pathname. Keep those resources behind the
+	// internal reader boundary.
+	if (scheme === "artifact" || scheme === "agent") {
+		throw new ToolError(
+			`${scheme}:// URLs cannot be expanded in bash commands; read them through the internal reader instead.`,
+		);
+	}
+
 	if (scheme === "local") {
 		if (!localOptions) {
 			throw new ToolError(
 				"Cannot resolve local:// URL in bash command: local protocol options are unavailable for this session.",
 			);
 		}
+		await initializeLocalRoot(localOptions);
 		const resolvedLocalPath = resolveLocalUrlToPath(url, localOptions);
 		if (ensureLocalParentDirs) {
 			await fs.mkdir(path.dirname(resolvedLocalPath), { recursive: true });
@@ -215,8 +226,8 @@ export function expandSkillUrls(command: string, skills: readonly Skill[]): stri
 }
 
 /**
- * Expand supported internal URLs in a bash command string to shell-escaped absolute paths.
- * Supported schemes: skill://, agent://, artifact://, memory://, rule://, local://
+ * Expand filesystem-safe internal URLs in a bash command string. `agent://` and
+ * `artifact://` remain internal-reader-only and are rejected before resolution.
  */
 export async function expandInternalUrls(command: string, options: InternalUrlExpansionOptions): Promise<string> {
 	if (!command.includes("://") && !command.includes("local:/")) return command;

package/src/tools/bash.ts

@@ -99,6 +99,43 @@ export interface BashToolDetails {
 	};
 }
 
+/** Project only a bare executable name; commands and their output are never notification-safe. */
+export function summarizeBashToolActivity(kind: "args" | "result", value: unknown): string | undefined {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+	const record = value as Record<string, unknown>;
+	if (kind === "args") {
+		const command = record.command;
+		if (typeof command !== "string") return undefined;
+		const program = command.trim().match(/^([A-Za-z][A-Za-z0-9_.+-]*)\b/)?.[1];
+		if (
+			!program ||
+			program.length > 80 ||
+			/(?:api[-_ ]?key|access[-_ ]?token|bearer|secret|password|\b(?:sk|pk|rk)-)/i.test(program)
+		) {
+			return undefined;
+		}
+		return program;
+	}
+
+	const output =
+		typeof record.output === "string"
+			? record.output
+			: Array.isArray(record.content)
+				? record.content
+						.filter(
+							(block): block is { type: unknown; text: unknown } =>
+								typeof block === "object" && block !== null && "type" in block && "text" in block,
+						)
+						.filter(block => block.type === "text" && typeof block.text === "string")
+						.map(block => block.text as string)
+						.join("\n")
+				: undefined;
+	if (output === undefined) return undefined;
+	const exitCode = typeof record.exitCode === "number" ? `exit=${record.exitCode}` : "completed";
+	const lines = output.length === 0 ? 0 : output.split("\n").length;
+	return `${exitCode}, ${lines} lines, ${Buffer.byteLength(output, "utf-8")} bytes`;
+}
+
 export interface BashToolOptions {}
 
 type ManagedBashJobCompletion =
@@ -248,6 +285,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 	readonly parameters: BashToolSchema;
 	readonly concurrency = "exclusive";
 	readonly strict = true;
+	readonly safeSummary = summarizeBashToolActivity;
 	readonly #asyncEnabled: boolean;
 	readonly #autoBackgroundEnabled: boolean;
 	readonly #autoBackgroundThresholdMs: number;
@@ -598,6 +636,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			internalRouter: InternalUrlRouter.instance(),
 			localOptions: {
 				getArtifactsDir: this.session.getArtifactsDir,
+				isManagedDestination: this.session.isManagedSessionDestination,
 				getSessionId: this.session.getSessionId,
 			},
 		};
@@ -605,7 +644,6 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			...internalUrlOptions,
 			ensureLocalParentDirs: this.session.bashRestrictionProfile !== "read-only",
 		});
-		const sessionFile = this.session.getSessionFile?.() ?? null;
 		const expandedEnv = env
 			? Object.fromEntries(
 					await Promise.all(
@@ -624,7 +662,7 @@ export class BashTool implements AgentTool<BashToolSchema, BashToolDetails> {
 			: undefined;
 		const resolvedEnv = {
 			...buildSkcRuntimeSessionEnv({
-				sessionFile,
+				sessionFile: null,
 				sessionId: this.session.getSessionId?.(),
 				cwd: this.session.cwd,
 			}),

package/src/tools/browser/STEALTH-THIRD-PARTY-NOTICES.md

@@ -0,0 +1,26 @@
+# Stealth Third-Party Notices
+
+Per the approved plan, anti-detection evasions are **reimplemented/adapted** as
+first-party code (no vendored source tree, no runtime dependency). This file
+records provenance for evasion techniques whose semantics were informed by the
+following open-source projects. Each individual reimplemented script also
+carries an attributing header comment.
+
+| Source project | License | Techniques referenced |
+|----------------|---------|-----------------------|
+| rebrowser-patches | MIT | CDP `Runtime.enable` leak mitigation (data-driven; landed only if the offline baseline shows a runtime/CDP leak signal) |
+| puppeteer-extra-plugin-stealth | MIT | Fingerprint evasion signal set (navigator/webgl/plugins/permissions/webrtc surfaces) overlapping and complementing the existing injection scripts |
+| fingerprint-suite (fingerprint-injector / generator) | Apache-2.0 | Coherent fingerprint attribute generation ideas |
+
+No source files from these projects are copied into this repository. Only the
+observable behaviors/signal semantics were reimplemented against `puppeteer-core`
+after being confirmed by the offline benchmark suite
+(`test/fixtures/stealth-detectors/`, `src/tools/browser/benchmark/`).
+
+## Detector fixtures
+
+The offline detector fixtures under `test/fixtures/stealth-detectors/` are
+first-party probes modeled on the public boolean signal sets used by
+`bot.sannysoft.com` and CreepJS. They are self-contained (inline JS, zero
+network) and are not verbatim copies of those sites. See that directory's
+`MANIFEST.json` for the refresh procedure.

package/src/tools/browser/benchmark/detector-report.ts

@@ -0,0 +1,157 @@
+/**
+ * Offline stealth-detector benchmark model.
+ *
+ * Pure, deterministic logic for the anti-detection benchmark suite: it converts
+ * a browser-collected fingerprint probe into a normalized per-detector verdict,
+ * implements the falsifiable CI gate (see plan Phase 1 / R-T3), and renders a
+ * before/after report. No browser or network access lives here so it can be
+ * unit-tested deterministically; the harness that drives the real browser tool
+ * against vendored detector fixtures feeds its output into these functions.
+ */
+
+export type SignalStatus = "pass" | "fail";
+
+/** A single boolean fingerprint signal, e.g. "navigator.webdriver is undefined". */
+export interface DetectorSignal {
+	/** Stable identifier, used to diff across runs. */
+	id: string;
+	/** Human-readable label for the report. */
+	label: string;
+	/** `pass` means the signal looks human; `fail` means it leaks automation. */
+	status: SignalStatus;
+	/** Optional observed value for debugging. */
+	detail?: string;
+}
+
+export type AutomatedVerdict = "human" | "bot" | "unknown";
+
+/** Normalized result for one detector (e.g. bot.sannysoft, CreepJS). */
+export interface DetectorResult {
+	detector: string;
+	signals: DetectorSignal[];
+	/** Overall automated/not classification when the detector exposes one. */
+	automatedVerdict: AutomatedVerdict;
+	/** Absolute trust score (observability-only, never a hard gate). */
+	trustScore: number | null;
+}
+
+/** Shape emitted by the offline probe fixture on `window.__stealthProbe`. */
+export interface RawProbe {
+	detector: string;
+	signals: Array<{ id: string; label: string; pass: boolean; detail?: string }>;
+	automatedVerdict?: AutomatedVerdict;
+	trustScore?: number | null;
+}
+
+/** Convert a raw browser-collected probe into a normalized {@link DetectorResult}. */
+export function parseProbe(raw: RawProbe): DetectorResult {
+	if (!raw || typeof raw.detector !== "string" || !Array.isArray(raw.signals)) {
+		throw new Error("invalid stealth probe payload");
+	}
+	const signals: DetectorSignal[] = raw.signals.map(s => ({
+		id: s.id,
+		label: s.label,
+		status: s.pass ? "pass" : "fail",
+		...(s.detail !== undefined ? { detail: s.detail } : {}),
+	}));
+	return {
+		detector: raw.detector,
+		signals,
+		automatedVerdict: raw.automatedVerdict ?? "unknown",
+		trustScore: raw.trustScore ?? null,
+	};
+}
+
+function passCount(result: DetectorResult): number {
+	return result.signals.filter(s => s.status === "pass").length;
+}
+
+function failingSignalIds(result: DetectorResult): Set<string> {
+	return new Set(result.signals.filter(s => s.status === "fail").map(s => s.id));
+}
+
+export interface GateOutcome {
+	pass: boolean;
+	reasons: string[];
+}
+
+/**
+ * Falsifiable CI gate (plan Phase 1 / R-T3, R-C1, R-C2):
+ *   (a) zero failing signals in the current run, AND
+ *       current pass-count >= baseline pass-count (no silent regression), AND
+ *   (b) either at least one signal that failed at baseline now passes,
+ *       OR the baseline was already all-green (empty-gap regression lock).
+ * The absolute `trustScore` is never consulted here; it is observability-only.
+ */
+export function evaluateGate(baseline: DetectorResult, current: DetectorResult): GateOutcome {
+	const reasons: string[] = [];
+	const currentFail = failingSignalIds(current);
+	if (currentFail.size > 0) {
+		reasons.push(
+			`${current.detector}: ${currentFail.size} signal(s) still leak automation: ${[...currentFail].join(", ")}`,
+		);
+	}
+
+	const baselinePass = passCount(baseline);
+	const currentPass = passCount(current);
+	if (currentPass < baselinePass) {
+		reasons.push(`${current.detector}: pass-count regressed (${currentPass} < baseline ${baselinePass})`);
+	}
+
+	const baselineFail = failingSignalIds(baseline);
+	const currentPassIds = new Set(current.signals.filter(s => s.status === "pass").map(s => s.id));
+	const newlyPassing = [...baselineFail].filter(id => currentPassIds.has(id));
+	const baselineAllGreen = baselineFail.size === 0;
+	if (!baselineAllGreen && newlyPassing.length === 0) {
+		reasons.push(`${current.detector}: no baseline-failing signal was fixed (improvement required)`);
+	}
+
+	return { pass: reasons.length === 0, reasons };
+}
+
+/** Aggregate gate across every detector; passes only when all detectors pass. */
+export function evaluateSuiteGate(
+	baseline: readonly DetectorResult[],
+	current: readonly DetectorResult[],
+): GateOutcome {
+	const reasons: string[] = [];
+	const currentByName = new Map(current.map(r => [r.detector, r]));
+	for (const base of baseline) {
+		const now = currentByName.get(base.detector);
+		if (!now) {
+			reasons.push(`${base.detector}: missing from current run`);
+			continue;
+		}
+		reasons.push(...evaluateGate(base, now).reasons);
+	}
+	return { pass: reasons.length === 0, reasons };
+}
+
+/** Render a deterministic before/after markdown report for one run. */
+export function renderReport(baseline: readonly DetectorResult[], current: readonly DetectorResult[]): string {
+	const lines: string[] = ["# Stealth Benchmark Report", ""];
+	const gate = evaluateSuiteGate(baseline, current);
+	lines.push(`Gate: ${gate.pass ? "PASS" : "FAIL"}`, "");
+	const currentByName = new Map(current.map(r => [r.detector, r]));
+	for (const base of baseline) {
+		const now = currentByName.get(base.detector);
+		lines.push(`## ${base.detector}`);
+		lines.push(
+			`- Automated verdict: ${base.automatedVerdict} -> ${now?.automatedVerdict ?? "n/a"}`,
+			`- Trust score (observability): ${base.trustScore ?? "n/a"} -> ${now?.trustScore ?? "n/a"}`,
+			`- Passing signals: ${passCount(base)} -> ${now ? passCount(now) : "n/a"} of ${base.signals.length}`,
+			"",
+			"| Signal | Baseline | Current |",
+			"|--------|----------|---------|",
+		);
+		for (const sig of base.signals) {
+			const nowSig = now?.signals.find(s => s.id === sig.id);
+			lines.push(`| ${sig.label} | ${sig.status} | ${nowSig?.status ?? "n/a"} |`);
+		}
+		lines.push("");
+	}
+	if (!gate.pass) {
+		lines.push("## Blocking reasons", ...gate.reasons.map(r => `- ${r}`), "");
+	}
+	return lines.join("\n");
+}

package/src/tools/browser/benchmark/run-suite.ts

@@ -0,0 +1,39 @@
+/**
+ * Offline stealth benchmark harness (plan Phase 1).
+ *
+ * Drives a puppeteer Page (already stealth-patched by the browser tool) against
+ * self-contained offline detector fixtures and collects normalized results. The
+ * navigation/evaluation is injected so this stays unit-testable without a real
+ * browser; the integration test wires a live puppeteer Page.
+ */
+
+import type { Page } from "puppeteer-core";
+import type { DetectorResult, RawProbe } from "./detector-report";
+import { parseProbe } from "./detector-report";
+
+/** Minimal surface of a puppeteer Page that the harness needs. */
+export type SuitePage = Pick<Page, "goto" | "evaluate">;
+
+export interface SuiteFixture {
+	/** file:// (or http://) URL of the offline detector fixture. */
+	url: string;
+}
+
+/** Read the probe the fixture placed on `window.__stealthProbe`. */
+function readProbe(): RawProbe {
+	// Runs in the browser context.
+	const probe = (globalThis as unknown as { __stealthProbe?: RawProbe }).__stealthProbe;
+	if (!probe) throw new Error("fixture did not expose window.__stealthProbe");
+	return probe;
+}
+
+/** Navigate to each fixture and collect a normalized DetectorResult per fixture. */
+export async function runOfflineSuite(page: SuitePage, fixtures: readonly SuiteFixture[]): Promise<DetectorResult[]> {
+	const results: DetectorResult[] = [];
+	for (const fixture of fixtures) {
+		await page.goto(fixture.url, { waitUntil: "load" });
+		const raw = await page.evaluate(readProbe);
+		results.push(parseProbe(raw));
+	}
+	return results;
+}

package/src/tools/browser/dead-tab-recovery.ts

@@ -0,0 +1,78 @@
+export type DeadTabRecoveryConsumeStatus = "consumed" | "expired_or_missing" | "owner_mismatch";
+
+export interface DeadTabRecoveryConsumeResult<T> {
+	status: DeadTabRecoveryConsumeStatus;
+	descriptor?: T;
+}
+
+interface StoredDescriptor<T> {
+	descriptor: T;
+	ownerId: string | undefined;
+	expiresAt: number;
+}
+
+interface DeadTabRecoveryDeps {
+	now(): number;
+	onPeek(): void;
+}
+
+const DEFAULT_TTL_MS = 30_000;
+const descriptors = new Map<string, StoredDescriptor<unknown>>();
+let deps: DeadTabRecoveryDeps = { now: () => Date.now(), onPeek: () => {} };
+
+/** Store a short-lived immutable recovery descriptor for a dead tab worker. */
+export function registerDeadTabRecovery<T extends object>(
+	name: string,
+	ownerId: string | undefined,
+	descriptor: T,
+	ttlMs = DEFAULT_TTL_MS,
+): void {
+	descriptors.set(name, { descriptor: Object.freeze(descriptor), ownerId, expiresAt: deps.now() + ttlMs });
+}
+
+/**
+ * Check whether a recovery descriptor may be consumed by this owner. The test hook is
+ * intentionally synchronous: recovery must not yield between this check and consume.
+ */
+export function peekDeadTabRecovery<T>(name: string, ownerId: string | undefined): DeadTabRecoveryConsumeResult<T> {
+	const stored = descriptors.get(name);
+	const result: DeadTabRecoveryConsumeResult<T> =
+		!stored || stored.expiresAt <= deps.now()
+			? { status: "expired_or_missing" }
+			: stored.ownerId !== ownerId
+				? { status: "owner_mismatch" }
+				: { status: "consumed", descriptor: stored.descriptor as T };
+	deps.onPeek();
+	return result;
+}
+
+/** Consume only a live descriptor belonging to the expected owner. */
+export function consumeDeadTabRecovery<T>(name: string, ownerId: string | undefined): DeadTabRecoveryConsumeResult<T> {
+	const stored = descriptors.get(name);
+	if (!stored || stored.expiresAt <= deps.now()) {
+		if (stored) descriptors.delete(name);
+		return { status: "expired_or_missing" };
+	}
+	if (stored.ownerId !== ownerId) return { status: "owner_mismatch" };
+	descriptors.delete(name);
+	return { status: "consumed", descriptor: stored.descriptor as T };
+}
+
+export function discardDeadTabRecovery(name: string): void {
+	descriptors.delete(name);
+}
+
+/** Whether an unconsumed descriptor remains live at the supplied policy clock. */
+export function isDeadTabRecoveryLive(name: string, now: number): boolean {
+	const stored = descriptors.get(name);
+	return stored !== undefined && stored.expiresAt > now;
+}
+
+export function __setDeadTabRecoveryDepsForTest(overrides: Partial<DeadTabRecoveryDeps>): void {
+	deps = { ...deps, ...overrides };
+}
+
+export function __resetDeadTabRecoveryForTest(): void {
+	descriptors.clear();
+	deps = { now: () => Date.now(), onPeek: () => {} };
+}