@lannguyensi/harness 0.21.1 → 0.22.0

package/dist/runtime/pause-sentinel.d.ts

@@ -0,0 +1,60 @@
+export declare const SENTINEL_BASENAME = ".harness-paused";
+export interface PauseSentinel {
+    /** ISO-8601 of when `harness pause` ran. */
+    pausedAt: string;
+    /** ISO-8601 expiry, or null for `--indefinite`. */
+    expiresAt: string | null;
+    /** Operator-supplied reason, or null when none was passed. */
+    reason: string | null;
+    /** Caller identity recorded by the CLI (host/user). */
+    pausedBy: string | null;
+}
+export declare function sentinelPath(generatedDir: string): string;
+export type ReadSentinelResult = {
+    kind: "absent";
+} | {
+    kind: "active";
+    sentinel: PauseSentinel;
+} | {
+    kind: "expired";
+    sentinel: PauseSentinel;
+};
+export declare function readSentinel(generatedDir: string, now?: Date): ReadSentinelResult;
+export declare function writeSentinel(generatedDir: string, sentinel: PauseSentinel): void;
+/** Returns true when a sentinel existed and was removed. */
+export declare function deleteSentinel(generatedDir: string): boolean;
+/**
+ * Format a short human-readable relative offset between `from` (the past
+ * anchor for "since X ago") or `to` (the future anchor for "in X") and
+ * `now`. Always rounds toward 1 so a near-boundary value never reads "0s".
+ */
+export declare function formatRelative(targetIso: string, now: Date): string;
+export interface AnnouncePauseOptions {
+    /** Already-resolved generatedDir. Required: hooks resolve this themselves. */
+    generatedDir: string;
+    /** Override "now" for tests. */
+    now?: Date;
+    /** Where to write the notice line. Defaults to process.stderr. */
+    stderr?: NodeJS.WritableStream;
+    /**
+     * Hook label inserted into the notice line so an operator scanning a
+     * busy stderr can tell which hook fire emitted it. Defaults to a
+     * generic "hook" tag.
+     */
+    hookLabel?: string;
+}
+/**
+ * Hook integration helper. One call from each PreToolUse / PostToolUse
+ * hook covers:
+ *   - active sentinel  → emit one stderr line; caller exits 0 (allow).
+ *   - expired sentinel → silently delete (auto-resume); caller proceeds.
+ *   - absent sentinel  → no-op; caller proceeds.
+ *
+ * The boolean `paused` return tells the caller whether to short-circuit.
+ * Any I/O error in the sentinel read degrades to `paused: false` rather
+ * than blocking: a broken state file is a debug nuisance, not a reason
+ * to silently freeze the whole session.
+ */
+export declare function maybeAnnouncePause(opts: AnnouncePauseOptions): {
+    paused: boolean;
+};

package/dist/runtime/pause-sentinel.js

@@ -0,0 +1,145 @@
+// harness pause/resume sentinel — temporary hook bypass for operator-only
+// recovery, debug, and incident-mode flows.
+//
+// The whole feature is one JSON file at `<generatedDir>/.harness-paused`.
+// While it exists and has not expired, every PreToolUse / PostToolUse hook
+// emits a one-line stderr notice and short-circuits to allow instead of
+// evaluating its normal gate logic. On the first hook fire AFTER expiry,
+// the sentinel is silently deleted (auto-resume) and evaluation resumes.
+//
+// Source-of-truth split:
+//   - Hook enforcement reads the sentinel file. Stat() on a known path —
+//     no per-call grounding-mcp roundtrip.
+//   - Audit trail goes to the evidence ledger via `harness pause` and
+//     `harness resume`. The ledger is queryable history; the sentinel is
+//     ephemeral state.
+//
+// Operator-only design: the `harness pause` verb refuses to run inside an
+// agent shell (where `$CLAUDE_SESSION_ID` is set) and refuses non-TTY
+// stdin without an explicit `--i-am-the-operator` acknowledgement. This
+// is the load-bearing guardrail against pause becoming an agent bypass.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { atomicWriteFile } from "../io/atomic-write.js";
+export const SENTINEL_BASENAME = ".harness-paused";
+export function sentinelPath(generatedDir) {
+    return path.join(generatedDir, SENTINEL_BASENAME);
+}
+export function readSentinel(generatedDir, now = new Date()) {
+    let raw;
+    try {
+        raw = fs.readFileSync(sentinelPath(generatedDir), "utf8");
+    }
+    catch {
+        return { kind: "absent" };
+    }
+    let sentinel;
+    try {
+        sentinel = normalizeSentinel(JSON.parse(raw));
+    }
+    catch {
+        // A malformed sentinel file is treated as absent: a broken state file
+        // must never escalate into a session-wide block. The `harness pause`
+        // verb only ever writes well-formed JSON, so this branch is reserved
+        // for operator-corrupted files.
+        return { kind: "absent" };
+    }
+    if (sentinel.expiresAt === null)
+        return { kind: "active", sentinel };
+    const expires = Date.parse(sentinel.expiresAt);
+    if (!Number.isFinite(expires))
+        return { kind: "active", sentinel };
+    if (expires <= now.getTime())
+        return { kind: "expired", sentinel };
+    return { kind: "active", sentinel };
+}
+function normalizeSentinel(raw) {
+    const pausedAt = typeof raw["pausedAt"] === "string" ? raw["pausedAt"] : "";
+    if (pausedAt === "")
+        throw new Error("missing pausedAt");
+    // expiresAt must be either an explicit null (indefinite) or a non-empty
+    // string. A typed-wrong value (e.g. number 42) is rejected as malformed
+    // rather than silently downgraded to indefinite — without this, a forged
+    // sentinel of `{"pausedAt":"...","expiresAt":42}` would read as a no-
+    // auto-resume pause that survives every hook fire.
+    const expiresAtRaw = raw["expiresAt"];
+    let expiresAt;
+    if (expiresAtRaw === null || expiresAtRaw === undefined) {
+        expiresAt = null;
+    }
+    else if (typeof expiresAtRaw === "string" && expiresAtRaw.length > 0) {
+        expiresAt = expiresAtRaw;
+    }
+    else {
+        throw new Error("expiresAt must be a non-empty ISO string or null");
+    }
+    const reason = typeof raw["reason"] === "string" ? raw["reason"] : null;
+    const pausedBy = typeof raw["pausedBy"] === "string" ? raw["pausedBy"] : null;
+    return { pausedAt, expiresAt, reason, pausedBy };
+}
+export function writeSentinel(generatedDir, sentinel) {
+    atomicWriteFile(sentinelPath(generatedDir), `${JSON.stringify(sentinel, null, 2)}\n`);
+}
+/** Returns true when a sentinel existed and was removed. */
+export function deleteSentinel(generatedDir) {
+    try {
+        fs.rmSync(sentinelPath(generatedDir));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Format a short human-readable relative offset between `from` (the past
+ * anchor for "since X ago") or `to` (the future anchor for "in X") and
+ * `now`. Always rounds toward 1 so a near-boundary value never reads "0s".
+ */
+export function formatRelative(targetIso, now) {
+    const target = Date.parse(targetIso);
+    if (!Number.isFinite(target))
+        return "?";
+    const abs = Math.max(1, Math.round(Math.abs(target - now.getTime()) / 1000));
+    if (abs < 90)
+        return `${abs}s`;
+    const mins = Math.round(abs / 60);
+    if (mins < 90)
+        return `${mins}m`;
+    const hrs = Math.round(mins / 60);
+    if (hrs < 36)
+        return `${hrs}h`;
+    const days = Math.round(hrs / 24);
+    return `${days}d`;
+}
+/**
+ * Hook integration helper. One call from each PreToolUse / PostToolUse
+ * hook covers:
+ *   - active sentinel  → emit one stderr line; caller exits 0 (allow).
+ *   - expired sentinel → silently delete (auto-resume); caller proceeds.
+ *   - absent sentinel  → no-op; caller proceeds.
+ *
+ * The boolean `paused` return tells the caller whether to short-circuit.
+ * Any I/O error in the sentinel read degrades to `paused: false` rather
+ * than blocking: a broken state file is a debug nuisance, not a reason
+ * to silently freeze the whole session.
+ */
+export function maybeAnnouncePause(opts) {
+    const now = opts.now ?? new Date();
+    const stderr = opts.stderr ?? process.stderr;
+    const hookLabel = opts.hookLabel ?? "hook";
+    const result = readSentinel(opts.generatedDir, now);
+    if (result.kind === "absent")
+        return { paused: false };
+    if (result.kind === "expired") {
+        deleteSentinel(opts.generatedDir);
+        return { paused: false };
+    }
+    const reason = result.sentinel.reason ?? "(no reason given)";
+    const since = formatRelative(result.sentinel.pausedAt, now);
+    const remaining = result.sentinel.expiresAt === null
+        ? "indefinite (no auto-resume)"
+        : `auto-resumes in ${formatRelative(result.sentinel.expiresAt, now)}`;
+    stderr.write(`harness ${hookLabel}: PAUSED since ${since} ago (reason: ${reason}); ${remaining}. Run \`harness resume\` to re-enable.\n`);
+    return { paused: true };
+}
+//# sourceMappingURL=pause-sentinel.js.map

package/dist/runtime/pause-sentinel.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lannguyensi/harness",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Declarative control plane for agent harnesses — one YAML for grounding, tools, memory, and hooks.",
   "license": "MIT",
   "homepage": "https://github.com/LanNguyenSi/harness",