toolroll 0.9.63 → 0.9.67

package/dist/run-efficiency.d.ts

@@ -0,0 +1,73 @@
+/**
+ * How a run went (docs/plans/run-efficiency.md): derived from the run's own records, display only. It never changes a
+ * completion, an approval, a charge or a check verdict, and it claims nothing its sources don't hold — an unreported
+ * number is unknown (null, shown as a dash), never zero.
+ *
+ * Sources, and what each can say: the run row (wall times, tokens, the provider's raw usage with its cache counts, the
+ * agent's turns where reported) is kept with the run; the live records (`<evidence>/live/<run>.jsonl`, display-only,
+ * kept 24 hours) are read once, bounded, through the descriptor-safe live reader, for step counts and observed step
+ * times. No command text is ever stored here: repeats are counted, never quoted.
+ */
+import type { Run, Store } from "./store.js";
+import type { LiveActivityKind, LiveRecord } from "./live-records.js";
+export declare const RUN_EFFICIENCY_VERSION = 3;
+/** Budgets for one derivation: never more than the live file's own cap, and a bounded record count. */
+export declare const EFFICIENCY_READ_BYTES: number;
+export declare const EFFICIENCY_RECORDS = 20000;
+export type StepsState = "complete" | "truncated" | "expired" | "absent";
+export type RunEfficiency = {
+    version: number;
+    /** Waiting to start (claimed → provider started) and the agent (provider started → finished); null when unrecorded. */
+    time: {
+        waitMs: number | null;
+        agentMs: number | null;
+    };
+    turns: number | null;
+    /** Tokens in counts everything the model read (cached included); `cacheShare` is read-from-cache ÷ that, 0–1. */
+    usage: {
+        in: number | null;
+        out: number | null;
+        cacheRead: number | null;
+        cacheWrite: number | null;
+        cacheShare: number | null;
+        provider: string;
+        model: string | null;
+    };
+    steps: {
+        state: StepsState;
+        reason: string | null;
+        total: number | null;
+        failed: number | null;
+        unknownDuration: number | null;
+        byKind: Partial<Record<LiveActivityKind, number>>;
+        longest: {
+            kind: LiveActivityKind;
+            ms: number;
+        }[];
+        /** Repeated activity: the same step (kind and its full recorded input) at least three times. Null when the inputs
+         * can't be compared (command detail off, or a target hidden or shortened) — said, never guessed. */
+        repeats: {
+            kind: LiveActivityKind;
+            count: number;
+        }[] | null;
+        repeatsReason: string | null;
+    };
+};
+/** Tokens and cache from the provider's own usage report, read per provider (their counts mean different things). */
+export declare function usageOf(run: Pick<Run, "provider" | "model" | "tokensIn" | "tokensOut"> & {
+    usageJson?: string | null;
+}): RunEfficiency["usage"];
+/** The live records' steps, bounded: counts by kind, failures, observed times and repeats (never their words). */
+/** `measured`: the recorder saw this provider's steps start and end as they happened (Claude's stream does); for the
+ * others their times are partly made up (Codex reports a step when it completes, ACP agents may report late), so no
+ * duration is claimed for them. */
+export declare function stepsOf(records: Iterable<LiveRecord>, truncated: string | null, measured?: boolean): RunEfficiency["steps"];
+/** Derive a finished run's How it ran from its records. */
+export declare function deriveRunEfficiency(run: Run & {
+    usageJson?: string | null;
+}, evidenceRoot: string, now: Date): RunEfficiency;
+/**
+ * A finished run's How it ran: the saved one when it was derived by this version, else derived now and saved (once:
+ * a row whose steps were complete or have expired is final). An unfinished run is derived but never saved.
+ */
+export declare function runEfficiencyOf(store: Store, evidenceRoot: string, runId: number, now: Date): RunEfficiency | null;

package/dist/run-efficiency.js

@@ -0,0 +1,228 @@
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+import { LIVE_RETAIN_MS, legacyLiveLogPath, liveLogPath, liveWindowRecords } from "./live.js";
+export const RUN_EFFICIENCY_VERSION = 3;
+/** Budgets for one derivation: never more than the live file's own cap, and a bounded record count. */
+export const EFFICIENCY_READ_BYTES = 4 * 1024 * 1024;
+export const EFFICIENCY_RECORDS = 20_000;
+const LONGEST = 5;
+const num = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+const msBetween = (from, to) => {
+    if (from === null || to === null)
+        return null;
+    const ms = Date.parse(to) - Date.parse(from);
+    return Number.isFinite(ms) && ms >= 0 ? ms : null;
+};
+/** Tokens and cache from the provider's own usage report, read per provider (their counts mean different things). */
+export function usageOf(run) {
+    let raw = {};
+    try {
+        const parsed = run.usageJson == null ? null : JSON.parse(run.usageJson);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed))
+            raw = parsed;
+    }
+    catch {
+        raw = {};
+    }
+    const base = { provider: run.provider, model: run.model ?? null, out: num(raw["output_tokens"]) ?? run.tokensOut ?? null };
+    if (run.provider === "claude") {
+        // Claude's input_tokens leave out what was read from or written to the cache: the three add up to what it read, so
+        // all three must be reported before a total or a share is claimed (a missing one is unknown, never zero).
+        const input = num(raw["input_tokens"]), read = num(raw["cache_read_input_tokens"]), write = num(raw["cache_creation_input_tokens"]);
+        const total = input === null || read === null || write === null ? null : input + read + write;
+        return { ...base, in: total, cacheRead: read, cacheWrite: write, cacheShare: total === null || total === 0 ? null : read / total };
+    }
+    if (run.provider === "codex") {
+        // Codex's input_tokens already include what came from its cache: both reported, or no share.
+        const input = num(raw["input_tokens"]), read = num(raw["cached_input_tokens"]);
+        return { ...base, in: input ?? run.tokensIn ?? null, cacheRead: read, cacheWrite: null,
+            cacheShare: read === null || input === null || input === 0 || read > input ? null : read / input };
+    }
+    return { ...base, in: run.tokensIn ?? null, cacheRead: null, cacheWrite: null, cacheShare: null };
+}
+/** The live records' steps, bounded: counts by kind, failures, observed times and repeats (never their words). */
+/** `measured`: the recorder saw this provider's steps start and end as they happened (Claude's stream does); for the
+ * others their times are partly made up (Codex reports a step when it completes, ACP agents may report late), so no
+ * duration is claimed for them. */
+export function stepsOf(records, truncated, measured = true) {
+    let detail = "base";
+    const open = new Map();
+    const byKind = {};
+    const longest = [];
+    let total = 0, failed = 0, unknown = 0;
+    for (const record of records) {
+        if (record.k === "open")
+            detail = record.detail;
+        else if (record.k === "step") {
+            if (record.kind === "session" || record.kind === "message")
+                continue;
+            total++;
+            byKind[record.kind] = (byKind[record.kind] ?? 0) + 1;
+            open.set(record.id, { kind: record.kind, at: record.at, once: record.once === true });
+        }
+        else if (record.k === "done") {
+            const started = open.get(record.id);
+            if (started === undefined)
+                continue;
+            open.delete(record.id);
+            if (record.ok === false)
+                failed++;
+            // Not a measured time: a provider whose times the recorder can't see as they happen, a start and end made up
+            // together (`once`), a step the recorder closed itself when the run ended (outcome unknown), or no time between.
+            const ms = !measured || started.once || record.ok === null ? null : msBetween(started.at || null, record.at || null);
+            if (ms === null || ms === 0) {
+                unknown++;
+                continue;
+            }
+            longest.push({ kind: started.kind, ms });
+            longest.sort((a, b) => b.ms - a.ms);
+            if (longest.length > LONGEST)
+                longest.pop();
+        }
+    }
+    // Steps that never closed (the run ended, or the file was cut) have no measured time.
+    unknown += open.size;
+    // Repeats are never claimed: the step records keep a display form of each step (a file name, a host, a command with
+    // its shell wrapper taken off), so two different steps can read alike. Said, not guessed.
+    const repeatsReason = detail === "commands"
+        ? "Repeats can't be told apart: the step records keep a short form of each step, not its whole input."
+        : "Repeats can't be told apart: this project doesn't record step details.";
+    const repeats = null;
+    return { state: truncated === null ? "complete" : "truncated", reason: truncated, total, failed, unknownDuration: unknown, byKind, longest, repeats, repeatsReason };
+}
+const noSteps = (state, reason) => ({ state, reason, total: null, failed: null, unknownDuration: null, byKind: {}, longest: [], repeats: null, repeatsReason: null });
+/** Read the run's live records once, strictly bounded: its own descriptor (no link followed, in a real live
+ * directory), measured once, and never more than the budget read whatever the file does meanwhile; then parsed line by
+ * line. A file over the budget, in the older text format, with lines that don't read, or cut or capped while the agent
+ * ran, says its steps are incomplete. Null when there is no step file at all. */
+function readRecords(evidenceRoot, runId) {
+    try {
+        const dir = lstatSync(join(evidenceRoot, "live"));
+        if (!dir.isDirectory() || dir.isSymbolicLink())
+            return null;
+    }
+    catch {
+        return null;
+    }
+    let fd;
+    try {
+        fd = openSync(liveLogPath(evidenceRoot, runId), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            return { unreadable: "The step records couldn't be read." };
+        // No records file: an older run's plain text file has no step detail; with neither, there is nothing.
+        try {
+            lstatSync(legacyLiveLogPath(evidenceRoot, runId));
+            return { unreadable: "This run's steps were recorded in an older format that has no step detail." };
+        }
+        catch {
+            return null;
+        }
+    }
+    let text, short = false;
+    try {
+        const stat = fstatSync(fd);
+        if (!stat.isFile())
+            return { unreadable: "The step records aren't a plain file, so they weren't read." };
+        if (stat.size > EFFICIENCY_READ_BYTES)
+            return { unreadable: "The step records are larger than they can be read here." };
+        // At most what it measured, and never past the budget: growth after the measure is not read.
+        const buffer = Buffer.alloc(stat.size);
+        let at = 0;
+        while (at < buffer.length) {
+            const got = readSync(fd, buffer, at, buffer.length - at, at);
+            if (got <= 0)
+                break;
+            at += got;
+        }
+        // Less than it measured: the file changed under the read.
+        short = at < buffer.length;
+        text = buffer.subarray(0, at).toString("utf8");
+    }
+    catch {
+        return { unreadable: "The step records couldn't be read." };
+    }
+    finally {
+        closeSync(fd);
+    }
+    const lines = text.split("\n");
+    // The last line may be unfinished (the agent's final write): it is read when it parses, never counted as a loss.
+    const unfinished = lines.at(-1) ?? "";
+    const whole = lines.slice(0, -1).filter(line => line.trim() !== "");
+    if (whole.length > EFFICIENCY_RECORDS)
+        whole.length = EFFICIENCY_RECORDS;
+    const keys = { inKey: false };
+    // One record per line: a whole line that doesn't read is a record lost.
+    const read = liveWindowRecords({ text: whole.length === 0 ? "" : `${whole.join("\n")}\n`, format: "records" }, keys);
+    const lost = whole.length - read.length;
+    // A finished run's last line without its newline is read like any other; one that doesn't read is a record lost.
+    const tail = unfinished.trim() === "" ? [] : liveWindowRecords({ text: `${unfinished}\n`, format: "records" }, keys);
+    const records = [...read, ...tail];
+    const lostAll = lost + (unfinished.trim() !== "" && tail.length === 0 ? 1 : 0);
+    if (records.length === 0 && text.trim() !== "")
+        return { unreadable: "The step records couldn't be read." };
+    const truncated = short ? "the step records changed while they were read"
+        : lines.length - 1 > EFFICIENCY_RECORDS ? `only the first ${EFFICIENCY_RECORDS.toLocaleString("en-US")} records were read`
+            : records.some(one => one.k === "cap") ? "the step records reached their size limit while the agent ran"
+                : records.some(one => one.k === "cut") ? "a step record was too long to keep"
+                    : lostAll > 0 ? `${lostAll} step record${lostAll === 1 ? "" : "s"} couldn't be read`
+                        : null;
+    return { records, truncated };
+}
+/** Derive a finished run's How it ran from its records. */
+export function deriveRunEfficiency(run, evidenceRoot, now) {
+    const finished = run.finishedAt;
+    const read = readRecords(evidenceRoot, run.id);
+    const steps = read !== null && "unreadable" in read ? noSteps("truncated", read.unreadable)
+        : read !== null ? stepsOf(read.records, read.truncated, run.provider === "claude")
+            : finished !== null && now.getTime() - Date.parse(finished) > LIVE_RETAIN_MS ? noSteps("expired", "Step details are kept for a day after a run; this one's have expired.")
+                : noSteps("absent", "No step records were kept for this run.");
+    return {
+        version: RUN_EFFICIENCY_VERSION,
+        time: { waitMs: msBetween(run.startedAt, run.providerStartedAt), agentMs: msBetween(run.providerStartedAt, finished) },
+        turns: run.agentTurns ?? null,
+        usage: usageOf(run),
+        steps,
+    };
+}
+/**
+ * A finished run's How it ran: the saved one when it was derived by this version, else derived now and saved (once:
+ * a row whose steps were complete or have expired is final). An unfinished run is derived but never saved.
+ */
+export function runEfficiencyOf(store, evidenceRoot, runId, now) {
+    const run = store.getRun(runId);
+    if (run === null)
+        return null;
+    const usageJson = store.handle.prepare("SELECT usage_json FROM run WHERE id = ?").get(runId)?.["usage_json"];
+    const full = { ...run, usageJson: typeof usageJson === "string" ? usageJson : null };
+    if (run.finishedAt === null)
+        return deriveRunEfficiency(full, evidenceRoot, now);
+    let saved;
+    try {
+        saved = store.handle.prepare("SELECT parser_version, payload_json FROM run_efficiency WHERE run = ?").get(runId);
+    }
+    catch {
+        saved = undefined;
+    }
+    if (saved !== undefined && Number(saved["parser_version"]) === RUN_EFFICIENCY_VERSION) {
+        try {
+            return JSON.parse(String(saved["payload_json"]));
+        }
+        catch { /* derived again below */ }
+    }
+    const derived = deriveRunEfficiency(full, evidenceRoot, now);
+    const payload = JSON.stringify(derived);
+    // A row too large for its column (it can't be: the counts are bounded) is shown, never saved.
+    // Saving is a convenience: a store that can't take the row (read-only, busy) still shows what was derived.
+    if (payload.length <= 16_384) {
+        try {
+            store.handle.prepare(`INSERT INTO run_efficiency (run, parser_version, steps, steps_reason, payload_json, derived_at) VALUES (?, ?, ?, ?, ?, ?)
+        ON CONFLICT(run) DO UPDATE SET parser_version = excluded.parser_version, steps = excluded.steps, steps_reason = excluded.steps_reason,
+          payload_json = excluded.payload_json, derived_at = excluded.derived_at`)
+                .run(runId, RUN_EFFICIENCY_VERSION, derived.steps.state, derived.steps.reason, payload, now.toISOString());
+        }
+        catch { /* shown, not saved: derived again next time */ }
+    }
+    return derived;
+}

package/dist/runner.d.ts

@@ -19,6 +19,8 @@
  * again. Reaping on the second tells you a *machine* is gone, and everything
  * it was holding — claims and worktrees alike — needs recovering together.
  */
+import { type AcpProviderId } from "./acp-agents.js";
+import type { AcpAttestation } from "./store.js";
 import type { Store, Mutation } from "./store.js";
 import { type ProviderId } from "./provider.js";
 import type { ReadinessObservation } from "./phase-routing.js";
@@ -264,7 +266,9 @@ export type ReadinessProbe = (file: string, args: readonly string[], options?: {
     notFound: boolean;
     timedOut: boolean;
 }>;
-export declare function observeProviderReadiness(probe: ReadinessProbe, env?: Record<string, string | undefined>, providers?: readonly ProviderId[]): Promise<Omit<ReadinessObservation, "runner" | "observedAt">[]>;
+export declare function observeProviderReadiness(probe: ReadinessProbe, env?: Record<string, string | undefined>, providers?: readonly ProviderId[], 
+/** An ACP agent's live check on this runner (store.acpAttestationFor), when the caller can read one. */
+acpChecked?: (provider: AcpProviderId) => AcpAttestation | null): Promise<Omit<ReadinessObservation, "runner" | "observedAt">[]>;
 /**
  * Record a runner's observations under its OWN authenticated name: the
  * credential is verified and the rows written in one transaction, so a

package/dist/runner.js

@@ -19,6 +19,9 @@
  * again. Reaping on the second tells you a *machine* is gone, and everything
  * it was holding — claims and worktrees alike — needs recovering together.
  */
+import { isAcpProvider } from "./acp-agents.js";
+import { verifyLaunch } from "./acp-attest.js";
+import { inspectAcpAgent, inspectionWords } from "./acp-inspect.js";
 import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
 import { resolve } from "node:path";
 import { canonicalProject } from "./project.js";
@@ -363,8 +366,26 @@ function sameDigest(left, right) {
     return a.length === b.length && timingSafeEqual(a, b);
 }
 const READINESS_PROBE_TIMEOUT_MS = 5_000;
-export async function observeProviderReadiness(probe, env = process.env, providers = PROVIDER_IDS) {
+export async function observeProviderReadiness(probe, env = process.env, providers = PROVIDER_IDS, 
+/** An ACP agent's live check on this runner (store.acpAttestationFor), when the caller can read one. */
+acpChecked) {
     return Promise.all(providers.map(async (provider) => {
+        // An ACP agent is looked at, never run, outside the gateway (acp-inspect.ts). It is ready only once its
+        // conformance check passed on this computer; until then it says so.
+        if (isAcpProvider(provider)) {
+            const checked = acpChecked?.(provider) ?? null;
+            if (checked !== null) {
+                // Ready only while every file its check bound is still the one that passed.
+                const verified = verifyLaunch(checked.launch);
+                return verified.ok
+                    ? { provider, state: "ready", reason: `${checked.agent.name} ${checked.agent.version}, checked ${checked.recordedAt.slice(0, 10)}`, probe: "version" }
+                    : { provider, state: "unavailable", reason: `${verified.problem}`, probe: "version" };
+            }
+            const seen = inspectAcpAgent(provider, env);
+            return seen.found
+                ? { provider, state: "unavailable", reason: `${inspectionWords(seen)}; not checked on this computer — run \`toolroll agents check ${provider}\``, probe: "version" }
+                : { provider, state: "unavailable", reason: inspectionWords(seen), probe: "version" };
+        }
         const facts = inspectionOf(provider);
         const version = await probe(facts.binary, ["--version"], { timeoutMs: READINESS_PROBE_TIMEOUT_MS, omitEnv: ALL_CREDENTIAL_ENV });
         if (version.notFound) {

package/dist/scope.d.ts

@@ -1,5 +1,9 @@
 export { ACCEPTANCE_LIMITS, EVIDENCE_KINDS, type EvidenceKind } from "./contracts/acceptance-terms.js";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { isAcpProfile, type AcpProviderId } from "./acp-agents.js";
+export { isAcpProfile };
+import { type NetworkProfile } from "./egress.js";
+import { type WritesMode } from "./writes-mode.js";
 import { type EvidenceKind } from "./contracts/acceptance-terms.js";
 import { type AcceptanceCriterion, type AcceptanceProblem, type ScopeTerms } from "./contracts/scope.js";
 import type { Store, Mutation } from "./store.js";
@@ -42,6 +46,13 @@ export declare const GEMINI_LIMITS: {
     readonly timeoutSeconds: 1200;
     readonly repairTimeoutSeconds: 300;
 };
+/** An ACP agent runs under two clocks at once: the whole attempt, and silence (no line from the agent). */
+export declare const ACP_LIMITS: {
+    readonly timeoutSeconds: 3600;
+    readonly idleTimeoutSeconds: 900;
+    readonly repairTimeoutSeconds: 900;
+    readonly repairIdleTimeoutSeconds: 300;
+};
 export type ClaudeProfile = {
     provider: "claude";
     /** The exact model string the argv carries. Never empty, never "default". */
@@ -61,6 +72,12 @@ export type ClaudeProfile = {
     /** Exact model for repairs, or the stable literal "inherit" (= the
      * build model, which is itself exact). */
     repairModel: string;
+    /** What the build may reach (egress.ts), resolved when the scope was written; absent on approvals sealed before
+     * network policies, which run narrowed (egress.ts legacyNetwork). */
+    network?: NetworkProfile;
+    /** Where the build may write (writes-mode.ts), resolved when the scope was written; absent on approvals sealed before
+     * write allowlists, which keep writing anywhere their fence allows. */
+    writes?: WritesMode;
 };
 export type CodexShapedProfile = {
     provider: "codex" | "openrouter";
@@ -77,6 +94,10 @@ export type CodexShapedProfile = {
     timeoutKind?: "idle";
     repairTimeoutSeconds: number;
     repairModel: string;
+    network?: NetworkProfile;
+    /** Where the build may write (writes-mode.ts), resolved when the scope was written; absent on approvals sealed before
+     * write allowlists, which keep writing anywhere their fence allows. */
+    writes?: WritesMode;
 };
 export type GeminiProfile = {
     provider: "gemini";
@@ -95,8 +116,46 @@ export type GeminiProfile = {
     timeoutKind?: "idle";
     repairTimeoutSeconds: number;
     repairModel: string;
+    network?: NetworkProfile;
+    /** Where the build may write (writes-mode.ts), resolved when the scope was written; absent on approvals sealed before
+     * write allowlists, which keep writing anywhere their fence allows. */
+    writes?: WritesMode;
+};
+/**
+ * An agent over the Agent Client Protocol (acp-agents.ts, docs/plans/acp-adapter.md).
+ * Full access inside the OS fence is the only posture: nothing else could be
+ * made true (an agent may run commands without asking). There is no turn
+ * limit; both clocks bound every attempt, and a repair has its own pair.
+ */
+export type AcpProfile = {
+    provider: AcpProviderId;
+    /** Exact, and one the agent offered when it was checked. */
+    model: string;
+    permission: "full";
+    maxTurns: "unsupported";
+    repairMaxTurns: "unsupported";
+    timeoutSeconds: number;
+    idleTimeoutSeconds: number;
+    repairTimeoutSeconds: number;
+    repairIdleTimeoutSeconds: number;
+    repairModel: string;
+    network?: NetworkProfile;
+    /** Where the build may write (writes-mode.ts), resolved when the scope was written; absent on approvals sealed before
+     * write allowlists, which keep writing anywhere their fence allows. */
+    writes?: WritesMode;
+};
+export type ExecutionProfile = ClaudeProfile | CodexShapedProfile | GeminiProfile | AcpProfile;
+/** Whether a profile's clock is a no-progress window (an ACP profile has both clocks; its overall one is a deadline). */
+export declare function idleClock(profile: ExecutionProfile): boolean;
+/**
+ * The watchdogs an attempt runs under, from its sealed profile and the overall bound the caller resolved: an ACP
+ * profile gets both clocks at once (the deadline and its silence window — a repair its own pair); the others one,
+ * a no-progress window when the profile says idle, else a deadline.
+ */
+export declare function watchdogsOf(profile: ExecutionProfile, timeoutMs: number, repair?: boolean): {
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
 };
-export type ExecutionProfile = ClaudeProfile | CodexShapedProfile | GeminiProfile;
 /** The durable unattended permission choices exposed by the console. The
  * provider-specific argv is still what gets sealed into an approval; this
  * small cross-provider type is only the operator-facing policy. */
@@ -461,6 +520,11 @@ export type ApproveResult = {
     ok: false;
     reason: "policy";
     message: string;
+}
+/** Cockpit B2: a remembered password can't approve these terms (protected, escalated, or a quarantined filing). */
+ | {
+    ok: false;
+    reason: "password-now";
 };
 /**
  * Whether this name-and-token pair is a person the store knows. Shared by
@@ -494,12 +558,114 @@ export declare function authenticateAccount(store: Store, by: string, secret: st
  * approval, chat-action review, the console's own ceremonies). A typed
  * password is always checked, and nothing else stands in.
  */
-export declare const freshIdentitySignIn: AsyncLocalStorage<{
-    actor: string | null;
+/**
+ * PASSWORD FRESHNESS (docs/plans/agents-cockpit.md B2), and the one place an empty password field is ever honoured.
+ *
+ * - An identity-provider re-check made **on request** (a step-up's re-authentication, never an ordinary sign-in) stands
+ *   in for one password typed now, for ONE step-up of any kind, within five minutes: it is consumed by the act it
+ *   proves (`sso-now`). Never reused across acts.
+ * - A password verified on this session, or that explicit re-check, stands in for fifteen minutes — but only inside an
+ *   allowlisted act (`withFreshness`), only for this person, only on a direct local request (`fresh-password`,
+ *   `fresh-sso`). Never extended by use.
+ * Every fact is read at the moment of the act (`FreshFacts` are live readers, not a snapshot), so a sign-out, a session
+ * revoked or rotated, a credential change or Forget made while a request was in flight is seen by it.
+ */
+export type FreshOp = "approve-standard" | "chat-send" | "reply-question";
+/** "session": Passwordless is on and this is the person's own live browser session (docs/plans/passwordless.md). */
+/** "remote-token" / "lead-token": a machine credential stood in for the person (a remote run's API token, a lead's
+ * token) — fine for ordinary acts it is allowed, never for a credential act (it would mint a way in with no password). */
+export type AuthMethod = "password-now" | "sso-now" | "fresh-password" | "fresh-sso" | "session" | "cli-login" | "remote-token" | "lead-token";
+/**
+ * The local CLI's remembered login, marked for the one command that read it (operate.ts credentialsFrom): with
+ * Passwordless on, a proof made with it records "cli-login" — never a typed password — and no credential act accepts it.
+ * Scoped to that command's async chain; a browser request in the console's own process never carries it.
+ */
+export declare const rememberedLogin: AsyncLocalStorage<{
+    login: {
+        name: string;
+        token: string;
+    } | null;
 }>;
-export declare const hasFreshIdentitySignIn: (by: string) => boolean;
-export declare function authenticateApprover(store: Store, by: string, token: string, repo?: string | null): {
+export declare const FRESH_WINDOW_MS: number;
+/** How long an explicit provider re-check stands in for one password typed now. */
+export declare const SSO_NOW_MS: number;
+export type FreshFacts = {
+    actor: string;
+    /** Straight from this computer: a loopback peer naming a loopback host, with no forwarding headers of any kind. */
+    local: boolean;
+    /** The request's route is on the freshness allowlist (route-table.ts `freshness: "allowlist"`): the table decides. */
+    allowlisted: boolean;
+    /** The session is still signed in, under the account's current credential generation, not revoked. */
+    live: () => boolean;
+    /** When a password was last verified on this session; when the provider last re-checked on request (window start);
+     * and an unconsumed re-check for one step-up. */
+    passwordAt: () => number | null;
+    ssoReauthAt: () => number | null;
+    ssoNow: () => number | null;
+    /** Spend the re-check; the answer puts it back (a refund) when the act it proved doesn't happen. */
+    consumeSsoNow: () => () => void;
+    /** Nothing before this counts (Forget). */
+    floor: () => number;
+    /** Record a verified password entry on this session (the console decides whether this request may start one). */
+    stamp: (at: number) => void;
+};
+export declare const freshFacts: AsyncLocalStorage<FreshFacts | null>;
+/**
+ * Run an act a re-check may prove, spending the re-check only if the act happens: when it throws (a rolled-back
+ * transaction) or `failed` says it was refused, every re-check it spent is put back. ONLY for acts whose every effect
+ * is in one database transaction (an approval, a chat approval proposal, a chat turn opening): there, "refused" and
+ * "thrown" prove nothing happened. Every other step-up spends its re-check whatever comes of it (fail-closed: at worst
+ * the person confirms with their provider again). Synchronous acts only.
+ */
+export declare function spendingOnlyOnSuccess<T>(act: () => T, failed: (result: T) => boolean): T;
+/** Run an allowlisted act: within it, a fresh password or re-check may stand in for one typed now. */
+export declare function withFreshness<T>(op: FreshOp, act: () => T): T;
+/** The freshness this act may stand on now, or null: only inside an allowlisted act on an allowlisted route, for this
+ * person, on a direct local request, on a live session, within the window, after any Forget. `preview` asks it from a
+ * page (a GET) about the allowlisted act its form posts to — for words only, never to authorise. */
+export declare function freshnessFor(by: string, now?: number, preview?: boolean): {
+    method: "fresh-password" | "fresh-sso";
+    at: number;
+} | null;
+/** Whether an explicit provider re-check is waiting to stand in for one step-up (the page says "Confirmed with …"). */
+export declare function ssoNowAvailable(by: string, now?: number): boolean;
+/**
+ * Proof that this person is here now, for any account step-up (an approver's or not): a password typed now, or an
+ * explicit provider re-check (consumed). The core of every console step-up; `authenticateApprover` adds standing.
+ */
+export declare function proveAccountNow(store: Store, by: string, token: string, options?: {
+    credential?: boolean;
+}): {
+    ok: true;
+    method: AuthMethod;
+    at: number;
+} | {
+    ok: false;
+    reason: "no-approvers" | "not-an-approver";
+};
+/**
+ * A credential act (docs/plans/passwordless.md, the closed list: one that creates or widens a way in): only a password
+ * typed now, or a one-use identity-provider re-check, proves it — never a session, never a remembered password.
+ */
+/** Whether an empty password would pass for `by` right now because Passwordless is on and this is their live browser
+ * session. Read only — the act itself proves it again inside `proveAccountNow`. */
+export declare function passwordlessSessionFor(store: Store, by: string): boolean;
+/** Whether a proof is one a credential act accepts: a password typed now, or a one-use identity-provider re-check. */
+export declare const credentialProof: (method: AuthMethod) => boolean;
+export declare function proveCredential(store: Store, by: string, token: string, repo?: string | null): {
     ok: true;
+    method: AuthMethod;
+    at: number;
+} | {
+    ok: false;
+    reason: "no-approvers" | "not-an-approver";
+};
+export declare function authenticateApprover(store: Store, by: string, token: string, repo?: string | null, options?: {
+    credential?: boolean;
+}): {
+    ok: true;
+    method: AuthMethod;
+    at: number;
 } | {
     ok: false;
     reason: "no-approvers" | "not-an-approver";
@@ -548,6 +714,18 @@ export declare function fileAndSealUnderMode(store: Store, input: ScopeInput & {
     detail?: string;
 };
 export declare function approve(store: Store, taskId: string, by: string, now: Date, sawDigest: string, token: string, mutation?: Mutation): ApproveResult;
+/** The ledger act that records how an approval's person was proved (password-now, sso-now, fresh-password, fresh-sso). */
+export declare const APPROVAL_PROOF = "approval proved";
+/** The proof row's detail: when the person was proved, the generation, and the exact digest they said yes to. */
+export declare const approvalProofDetail: (at: number, generation: number, digest: string) => string;
+/** The proof of THIS approval: the approver's own row for these exact bytes (never another approval's words). */
+export declare function approvalProofOf(store: Store, taskId: string, by: string, digest: string): {
+    method: string;
+    at: string;
+} | null;
+/** Whether a remembered password may approve these terms: one approver (no protected work), standard permissions
+ * (never escalated), and not filed by a coordinator, a lead or a scout (those keep their own password ceremony). */
+export declare function freshlyApprovable(store: Store, taskId: string, scope: Scope, singleApprover: boolean): boolean;
 /**
  * Whether this task may be built.
  *