tickmarkr 2.5.8 → 2.5.9

package/dist/run/merge.js

@@ -1,11 +1,34 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { shq } from "../adapters/types.js";
-import { ceilingKillResult, classifyFreshRunnerOutput, classifyRunnerOutput, fileCountDeficit, waitForCalmWindow, effectiveCeilingMs, fingerprint, freshFailures, } from "../gates/baseline.js";
+import { beginGateEvidence, ceilingKillResult, classifyFreshRunnerOutput, classifyRunnerOutput, fileCountDeficit, waitForCalmWindow, effectiveCeilingMs, fingerprint, freshFailures, } from "../gates/baseline.js";
 import { evaluateManifestedTest, isVitestTestCommand } from "../gates/test-manifest.js";
 import { computeVerificationIdentity, formatReusedDetails, getVerdictStore, getWorktreeTree, resolveStateDir, isInfraResult, } from "../gates/cache.js";
 import { tickmarkrDir } from "../graph/graph.js";
 import { describeCapacity, gitHead, linkNodeModules, resolveIntegrationBranch, resolvedCapacity, sameCapacity, sh, shGit, shGitOk, WORKTREES_DIR } from "./git.js";
+import { executionSignal } from "./execution-budget.js";
+// Diagnostic convenience logs are observational, just like receipt persistence.
+function writeTipLog(path, text) {
+    try {
+        writeFileSync(path, text);
+    }
+    catch { /* the command verdict remains authoritative */ }
+}
+/** Carry execution evidence without minting an invocation or rebasing its artifact paths. */
+export function reusedTipEvidence(source) {
+    return {
+        reused: true,
+        ...(source.evidenceReceipt ? { evidenceReceipt: source.evidenceReceipt } : {}),
+        ...(source.evidenceReceipts ? { evidenceReceipts: source.evidenceReceipts } : {}),
+        ...(source.originRunRoot ? { originRunRoot: source.originRunRoot } : {}),
+        ...(!source.evidenceReceipt
+            ? { evidenceAbsence: source.evidenceAbsence ?? "historical-cache" }
+            : source.evidenceAbsence ? { evidenceAbsence: source.evidenceAbsence } : {}),
+        ...(source.nonce !== undefined ? { nonce: source.nonce } : {}),
+        ...(source.stdoutPath !== undefined ? { stdoutPath: source.stdoutPath } : {}),
+        ...(source.stderrPath !== undefined ? { stderrPath: source.stderrPath } : {}),
+    };
+}
 export function integrationBranch(cfg, runId) {
     return `${cfg.integrationBranchPrefix}${runId}`;
 }
@@ -52,7 +75,7 @@ export async function mergeTask(intWt, taskBranch, message, gatedCommit) {
 // terminus unreachable by construction and misattributed the red to the last merged task.
 // Fail-closed edges kept: no baseline → strict; baseline green for that gate → strict; any fresh
 // fingerprint, or output with no recognizable failure shape, → failed.
-export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
+export async function verifyIntegrationTip(intWt, commands, runDir, baseline, evidenceOptions = {}) {
     const results = [];
     let runStartCommands;
     let journalFound = false;
@@ -109,7 +132,7 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
         for (const [gate, cmd] of gatesToRun) {
             const artifact = join(runDir, `tip-verify-${gate}.log`);
             const details = `tip verify could not establish command provenance: run-start evidence missing or malformed in journal`;
-            writeFileSync(artifact, details + "\n");
+            writeTipLog(artifact, details + "\n");
             results.push({
                 gate,
                 cmd,
@@ -117,6 +140,7 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
                 exitCode: 1,
                 fingerprints: [],
                 details,
+                evidenceAbsence: "provenance-refused",
                 artifact,
             });
         }
@@ -135,7 +159,7 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
             if (expectedCmd === undefined || cmd !== expectedCmd) {
                 const artifact = join(runDir, `tip-verify-${gate}.log`);
                 const details = `tip verify command "${cmd}" for gate "${gate}" was not named in run-start row`;
-                writeFileSync(artifact, details + "\n");
+                writeTipLog(artifact, details + "\n");
                 results.push({
                     gate,
                     cmd,
@@ -143,6 +167,7 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
                     exitCode: 1,
                     fingerprints: [],
                     details,
+                    evidenceAbsence: "provenance-refused",
                     artifact,
                 });
                 continue;
@@ -184,7 +209,7 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
                 gate,
                 cmd,
                 pass: hit.pass,
-                reused: true,
+                ...reusedTipEvidence(hit.meta ?? {}),
                 exitCode: hit.exitCode ?? 0,
                 fingerprints: hit.meta?.fingerprints ?? [],
                 ...(hit.meta?.forgiven ? { forgiven: true } : {}),
@@ -207,14 +232,21 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
                 longestFile: entry?.longestFile,
                 overallCeilingMs: effectiveCeilingMs(entry),
                 artifactDir: runDir,
+                evidence: { artifactDir: runDir, runId: runDir, ...evidenceOptions },
             });
             const artifact = join(runDir, `tip-verify-${gate}.log`);
             if (!outcome.pass)
-                writeFileSync(artifact, outcome.details);
+                writeTipLog(artifact, outcome.details);
             results.push({
                 gate,
                 cmd,
                 pass: outcome.pass,
+                evidenceReceipt: outcome.evidenceReceipt,
+                evidenceReceipts: outcome.evidenceReceipts,
+                ...(!outcome.evidenceReceipt ? { evidenceAbsence: "not-started" } : {}),
+                nonce: outcome.meta.nonce,
+                stdoutPath: outcome.meta.stdoutPath,
+                stderrPath: outcome.meta.stderrPath,
                 exitCode: outcome.exitCode,
                 reportPath: outcome.reportPath,
                 spawnedCommand: outcome.meta.spawnedCommand,
@@ -230,18 +262,41 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
         // `sh` defaults to. A suite whose capture measured 600007ms carries a recorded 1800021ms ceiling;
         // running it under 600000ms here SIGKILLed a green tip three times while every per-task gate passed.
         const ceilingMs = effectiveCeilingMs(entry);
-        let r = await sh(cmd, intWt, ceilingMs);
+        const evidenceReceipts = [];
+        const execute = async () => {
+            const evidence = beginGateEvidence(intWt, gate, cmd, { artifactDir: runDir, runId: runDir, ...evidenceOptions });
+            try {
+                const result = await sh(cmd, intWt, ceilingMs, { env: evidenceOptions.env, onReceipt: receipt => evidence.observe(receipt) });
+                evidenceReceipts.push(...evidence.history, evidence.finish(result.stdout, result.stderr));
+                return result;
+            }
+            catch (error) {
+                const receipt = evidence.finish();
+                if (receipt.termination.kind !== "not-started" || executionSignal()?.aborted)
+                    throw error;
+                evidenceReceipts.push(...evidence.history, receipt);
+                return { code: -1, stdout: "", stderr: String(error) };
+            }
+        };
+        let r = await execute();
         let raw = r.stdout + "\n" + r.stderr;
         let stripped = raw.split(intWt).join("");
         let rerun;
-        if (gate === "test" && !r.timedOut && !fileCountDeficit(entry, stripped)
+        if (evidenceReceipts.at(-1)?.termination.kind !== "not-started" && gate === "test" && !r.timedOut && !fileCountDeficit(entry, stripped)
             && classifyFreshRunnerOutput(entry, stripped, r.code) === "infra") {
             const waitedMs = await waitForCalmWindow();
             rerun = `runner-infra rerun after waiting ${waitedMs}ms for a calm load window`;
-            r = await sh(cmd, intWt, ceilingMs);
+            r = await execute();
             raw = r.stdout + "\n" + r.stderr;
             stripped = raw.split(intWt).join("");
         }
+        const evidenceReceipt = evidenceReceipts.at(-1);
+        if (evidenceReceipt.termination.kind === "not-started") {
+            results.push({ gate, cmd, pass: false, exitCode: r.code, fingerprints: [],
+                details: `infra; command failed to launch: ${r.stderr}`, cause: "infra",
+                evidenceReceipt, evidenceReceipts, evidenceAbsence: "not-started" });
+            continue;
+        }
         const artifact = join(runDir, `tip-verify-${gate}.log`);
         // Battery parity on the ceiling too (baseline.ts Q24): the kill is read BEFORE the exit code is
         // interpreted at all. A SIGKILLed battery never returned a verdict, so no line of its partial
@@ -249,11 +304,12 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
         // operator cannot act on. The kill reader's own text (ceiling + elapsed) and cause replace it.
         const killed = ceilingKillResult(gate, r, ceilingMs);
         if (killed) {
-            writeFileSync(artifact, raw);
+            writeTipLog(artifact, raw);
             results.push({
                 gate,
                 cmd,
                 pass: false,
+                evidenceReceipt, evidenceReceipts,
                 exitCode: r.code,
                 fingerprints: [],
                 details: `${rerun ? `infra; ${rerun}: ` : ""}${killed.details}`,
@@ -290,11 +346,12 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
             && comparable;
         const pass = !deficit && (r.code === 0 || greenTeardown || forgiven);
         if (!pass)
-            writeFileSync(artifact, raw);
+            writeTipLog(artifact, raw);
         const tipResult = {
             gate,
             cmd,
             pass,
+            evidenceReceipt, evidenceReceipts,
             exitCode: r.code,
             fingerprints: r.code !== 0 && !greenTeardown ? fingerprint(stripped) : [],
             details: `${cause === "infra" ? "infra; " : ""}${rerun ? `${rerun}: ` : ""}` + (deficit?.replace(/^infra; /, "") ?? (r.code === 0 ? "exit 0"
@@ -315,12 +372,17 @@ export async function verifyIntegrationTip(intWt, commands, runDir, baseline) {
     // spawns in the daemon child, and a command that changed the tree invalidates reuse.
     const completedTree = pending.size ? await getWorktreeTree(intWt) : undefined;
     for (const result of results) {
+        if (!result.reused && result.evidenceReceipt)
+            result.originRunRoot = resolve(evidenceOptions.artifactDir ?? runDir);
         const id = pending.get(result.gate);
         if (id && id.tree === completedTree && !isInfraResult(result)) {
             store.set(id, { ...result, meta: {
                     fingerprints: result.fingerprints, forgiven: result.forgiven,
                     reportPath: result.reportPath, spawnedCommand: result.spawnedCommand,
                     artifact: result.artifact,
+                    evidenceReceipt: result.evidenceReceipt, evidenceReceipts: result.evidenceReceipts,
+                    evidenceAbsence: result.evidenceAbsence, originRunRoot: result.originRunRoot,
+                    nonce: result.nonce, stdoutPath: result.stdoutPath, stderrPath: result.stderrPath,
                 } });
         }
     }

package/dist/run/protocol.d.ts

@@ -37,6 +37,88 @@ export declare const ShellReceiptSchema: z.ZodObject<{
     durationMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export type ShellReceipt = z.infer<typeof ShellReceiptSchema>;
+export declare const EVIDENCE_AVAILABILITIES: readonly ["available", "not-started", "capture-failed", "killed", "expired", "missing"];
+export declare const EvidenceArtifactSchema: z.ZodObject<{
+    path: z.ZodString;
+    availability: z.ZodEnum<{
+        available: "available";
+        "not-started": "not-started";
+        "capture-failed": "capture-failed";
+        killed: "killed";
+        expired: "expired";
+        missing: "missing";
+    }>;
+    sha256: z.ZodNullable<z.ZodString>;
+    retainedBytes: z.ZodNumber;
+    droppedBytes: z.ZodNumber;
+    truncated: z.ZodBoolean;
+}, z.core.$strict>;
+export declare const GateEvidenceReceiptSchema: z.ZodObject<{
+    invocationId: z.ZodString;
+    nonce: z.ZodOptional<z.ZodString>;
+    subject: z.ZodObject<{
+        runId: z.ZodString;
+        taskId: z.ZodNullable<z.ZodString>;
+        attempt: z.ZodNullable<z.ZodNumber>;
+        gate: z.ZodString;
+        subjectCommit: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    termination: z.ZodObject<{
+        kind: z.ZodEnum<{
+            unknown: "unknown";
+            signal: "signal";
+            "not-started": "not-started";
+            exit: "exit";
+            timeout: "timeout";
+        }>;
+        exitCode: z.ZodNullable<z.ZodNumber>;
+        signal: z.ZodNullable<z.ZodString>;
+        timedOut: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strict>;
+    availability: z.ZodEnum<{
+        available: "available";
+        "not-started": "not-started";
+        "capture-failed": "capture-failed";
+        killed: "killed";
+        expired: "expired";
+        missing: "missing";
+    }>;
+    redaction: z.ZodObject<{
+        material: z.ZodBoolean;
+    }, z.core.$strict>;
+    stdout: z.ZodObject<{
+        path: z.ZodString;
+        availability: z.ZodEnum<{
+            available: "available";
+            "not-started": "not-started";
+            "capture-failed": "capture-failed";
+            killed: "killed";
+            expired: "expired";
+            missing: "missing";
+        }>;
+        sha256: z.ZodNullable<z.ZodString>;
+        retainedBytes: z.ZodNumber;
+        droppedBytes: z.ZodNumber;
+        truncated: z.ZodBoolean;
+    }, z.core.$strict>;
+    stderr: z.ZodObject<{
+        path: z.ZodString;
+        availability: z.ZodEnum<{
+            available: "available";
+            "not-started": "not-started";
+            "capture-failed": "capture-failed";
+            killed: "killed";
+            expired: "expired";
+            missing: "missing";
+        }>;
+        sha256: z.ZodNullable<z.ZodString>;
+        retainedBytes: z.ZodNumber;
+        droppedBytes: z.ZodNumber;
+        truncated: z.ZodBoolean;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type GateEvidenceReceipt = z.infer<typeof GateEvidenceReceiptSchema>;
+export type EvidenceArtifact = z.infer<typeof EvidenceArtifactSchema>;
 /** A task-build row must carry the entire caller-owned correlation, even before spawn. */
 export declare const CommandReceiptSchema: z.ZodObject<{
     outcome: z.ZodEnum<{

package/dist/run/protocol.js

@@ -33,6 +33,41 @@ export const ShellReceiptSchema = z.object({
     error: z.string().optional(),
     durationMs: z.number().nonnegative().optional(),
 }).strict();
+export const EVIDENCE_AVAILABILITIES = ["available", "not-started", "capture-failed", "killed", "expired", "missing"];
+export const EvidenceArtifactSchema = z.object({
+    path: z.string().refine(p => p.length > 0 && !p.startsWith("/") && !p.includes("\\") && !p.split("/").includes("..")),
+    availability: z.enum(EVIDENCE_AVAILABILITIES),
+    sha256: z.string().regex(/^[a-f0-9]{64}$/).nullable(),
+    retainedBytes: z.number().int().min(0).max(16 * 1024),
+    droppedBytes: z.number().int().nonnegative(),
+    truncated: z.boolean(),
+}).strict().superRefine((ref, ctx) => {
+    if (ref.truncated !== (ref.droppedBytes > 0))
+        ctx.addIssue({ code: "custom", message: "truncation must agree with dropped bytes" });
+    if (ref.availability === "available" && ref.sha256 === null)
+        ctx.addIssue({ code: "custom", message: "available bytes require a hash" });
+});
+export const GateEvidenceReceiptSchema = z.object({
+    invocationId: NonEmptyStringSchema,
+    nonce: NonEmptyStringSchema.optional(),
+    subject: z.object({
+        runId: NonEmptyStringSchema,
+        taskId: NonEmptyStringSchema.nullable(),
+        attempt: AttemptSchema.nullable(),
+        gate: NonEmptyStringSchema,
+        subjectCommit: NonEmptyStringSchema.nullable(),
+    }).strict(),
+    termination: z.object({
+        kind: z.enum(["exit", "signal", "timeout", "not-started", "unknown"]),
+        exitCode: z.number().int().nullable(),
+        signal: NonEmptyStringSchema.nullable(),
+        timedOut: z.boolean().nullable(),
+    }).strict(),
+    availability: z.enum(EVIDENCE_AVAILABILITIES),
+    redaction: z.object({ material: z.boolean() }).strict(),
+    stdout: EvidenceArtifactSchema,
+    stderr: EvidenceArtifactSchema,
+}).strict();
 /** A task-build row must carry the entire caller-owned correlation, even before spawn. */
 export const CommandReceiptSchema = ShellReceiptSchema.extend({
     attribution: CommandReceiptAttributionSchema,

package/dist/run/receipt-resolver.d.ts

@@ -0,0 +1,18 @@
+import { type GateEvidenceReceipt } from "./protocol.js";
+export declare const RECEIPT_UNAVAILABLE_REASONS: readonly ["outside-root", "symlink", "hash-mismatch", "expired", "missing"];
+export type ReceiptUnavailableReason = (typeof RECEIPT_UNAVAILABLE_REASONS)[number];
+export type ReceiptResolution = {
+    readonly ok: true;
+    readonly path: string;
+    readonly sha256: string;
+} | {
+    readonly ok: false;
+    readonly path: string;
+    readonly reason: ReceiptUnavailableReason;
+};
+/** Resolve one artifact reference against the run root it was recorded under. Fails closed. */
+export declare function resolveReceipt(reference: unknown, runRoot: string): ReceiptResolution;
+/** Both artifacts of a receipt, stdout first, each resolved independently. */
+export declare function resolveReceiptArtifacts(receipt: GateEvidenceReceipt, runRoot: string): ReceiptResolution[];
+/** One line per artifact for a human surface: the reference, then its verified availability. */
+export declare function formatReceiptResolution(r: ReceiptResolution): string;

package/dist/run/receipt-resolver.js

@@ -0,0 +1,132 @@
+import { createHash } from "node:crypto";
+import { closeSync, constants, fstatSync, lstatSync, openSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { EvidenceArtifactSchema } from "./protocol.js";
+// OBS-1101 retrieval (D-174): the one production reader of an execution-evidence receipt. It answers
+// from the bytes on disk under the run root the receipt was minted in and nothing else — no
+// re-execution, no substitute chosen by name or timestamp, no symlink followed anywhere: not in the
+// reference, not at the root, not above it. The caller hands a canonical root (its own trust anchor);
+// a root reached through any link is refused outright.
+export const RECEIPT_UNAVAILABLE_REASONS = ["outside-root", "symlink", "hash-mismatch", "expired", "missing"];
+/** Resolve one artifact reference against the run root it was recorded under. Fails closed. */
+export function resolveReceipt(reference, runRoot) {
+    const parsed = EvidenceArtifactSchema.safeParse(reference);
+    const path = typeof reference?.path === "string" ? reference.path : "";
+    if (!parsed.success) {
+        const escapes = path && (isAbsolute(path) || path.includes("\\") || path.split("/").includes(".."));
+        return { ok: false, path, reason: escapes ? "outside-root" : "missing" };
+    }
+    const ref = parsed.data;
+    if (ref.availability === "expired")
+        return { ok: false, path: ref.path, reason: "expired" };
+    if (ref.availability !== "available" || ref.sha256 === null)
+        return { ok: false, path: ref.path, reason: "missing" };
+    const root = resolve(runRoot);
+    const full = resolve(root, ref.path);
+    const rel = relative(root, full);
+    if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return { ok: false, path: ref.path, reason: "outside-root" };
+    const read = readUnderRoot(root, rel.split(sep));
+    if (typeof read === "string")
+        return { ok: false, path: ref.path, reason: read };
+    const sha256 = createHash("sha256").update(read).digest("hex");
+    if (sha256 !== ref.sha256 || read.length !== ref.retainedBytes)
+        return { ok: false, path: ref.path, reason: "hash-mismatch" };
+    return { ok: true, path: ref.path, sha256 };
+}
+const same = (a, b) => a.dev === b.dev && a.ino === b.ino;
+/** Every ancestor of the root, root first excluded — "/" itself cannot be a link. */
+function ancestors(root) {
+    const out = [];
+    for (let p = dirname(root); p !== dirname(p); p = dirname(p))
+        out.push(p);
+    return out;
+}
+/**
+ * Walk `parts` below `root` one descriptor at a time and return the leaf's bytes. Every component —
+ * the root's ancestors, the root, each directory, the leaf — is opened O_NOFOLLOW and must be the
+ * same inode lstat reports for that name before AND after the open, so a component swapped for a
+ * link mid-walk is refused rather than followed. Every platform takes the same pathname open: an
+ * ancestor swap by a same-privilege writer can only ever yield hash-identical bytes (D-269), so no
+ * descriptor-anchored traversal is layered on top (D-279: the boundary is the run root).
+ */
+function readUnderRoot(root, parts) {
+    for (const p of ancestors(root)) {
+        let st;
+        try {
+            st = lstatSync(p);
+        }
+        catch {
+            return "missing";
+        }
+        if (st.isSymbolicLink())
+            return "symlink";
+    }
+    const fds = [];
+    try {
+        let parent = openComponent(root, true);
+        if (typeof parent === "string")
+            return parent;
+        fds.push(parent);
+        let at = root;
+        for (let i = 0; i < parts.length; i++) {
+            at = resolve(at, parts[i]);
+            const fd = openComponent(at, i < parts.length - 1);
+            if (typeof fd === "string")
+                return fd;
+            fds.push(fd);
+            parent = fd;
+        }
+        return readFileSync(parent);
+    }
+    catch (e) {
+        return e.code === "ELOOP" ? "symlink" : "missing";
+    }
+    finally {
+        for (const fd of fds)
+            closeSync(fd);
+    }
+}
+function openComponent(path, dir) {
+    let before;
+    try {
+        before = lstatSync(path);
+    }
+    catch {
+        return "missing";
+    }
+    if (before.isSymbolicLink())
+        return "symlink";
+    if (dir ? !before.isDirectory() : !before.isFile())
+        return "missing";
+    const flags = constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK | (dir ? constants.O_DIRECTORY : 0);
+    const fd = openSync(path, flags);
+    let after;
+    try {
+        after = lstatSync(path);
+    }
+    catch {
+        closeSync(fd);
+        return "missing";
+    }
+    const opened = fstatSync(fd);
+    if (after.isSymbolicLink() || !same(before, opened) || !same(after, opened)) {
+        closeSync(fd);
+        return "symlink";
+    }
+    // A leaf reachable under a second name (a hard link) is an alias the inode check cannot see through;
+    // evidence is written once under one name, so any aliased leaf is refused.
+    if (!dir && opened.nlink !== 1) {
+        closeSync(fd);
+        return "symlink";
+    }
+    return fd;
+}
+/** Both artifacts of a receipt, stdout first, each resolved independently. */
+export function resolveReceiptArtifacts(receipt, runRoot) {
+    return [receipt.stdout, receipt.stderr].map(ref => resolveReceipt(ref, runRoot));
+}
+/** One line per artifact for a human surface: the reference, then its verified availability. */
+export function formatReceiptResolution(r) {
+    return r.ok ? `${r.path} available sha256=${r.sha256}` : `${r.path} unavailable (${r.reason})`;
+}

package/dist/run/supervision.d.ts

@@ -39,7 +39,20 @@ export interface SupervisionBeatObservation {
 export declare const supervisionBeatPath: (repoRoot: string, tier: SupervisionTier) => string;
 /** Where a watcher records that it STOOD DOWN. Its own file: the beat keeps meaning only "alive". */
 export declare const supervisionStandDownPath: (repoRoot: string, tier: SupervisionTier) => string;
-export declare function beatSupervision(repoRoot: string, tier: SupervisionTier, seat?: string, observation?: SupervisionBeatObservation): void;
+/** Durable CLI arm; ticks never advance its epoch or its stand-down fence. */
+export interface SupervisionArm {
+    armId: string;
+    armEpoch: string;
+    markerFence: string;
+}
+export declare const supervisionArmPath: (repoRoot: string, tier: SupervisionTier) => string;
+/** Explicit arming acknowledges the current marker without deleting it. */
+export declare function newSupervisionArm(repoRoot: string, tier: SupervisionTier, armId?: string, initial?: boolean): SupervisionArm;
+export declare function beatSupervision(repoRoot: string, tier: SupervisionTier, seat?: string, observation?: SupervisionBeatObservation, options?: {
+    arm?: SupervisionArm;
+    armId?: string;
+    loop?: boolean;
+}): boolean;
 /** Handle a watcher holds for as long as it is supervising; disarm stands it down and is idempotent. */
 export interface ArmedSupervision {
     disarm: () => void;