@akagilnc/pi-workflow-roles 0.1.4620 → 0.1.4631

package/dist/public-cli/post-admission.js

@@ -37,10 +37,36 @@ import { mintEngineDetourInvocationScope, readInvocationSelectedHost, withEngine
 import { projectHostTransitionPriorNative } from "../host-transition-prior-native.js";
 import { missingCredentialPreDispatchFailure, postRunMissingCredentialFailure, } from "./public-run-credentials.js";
 import { acquireRunWriterLease, clearCurrentCourt, clearTypedProviderHttpObservation, describeErrorIdentity, markRunRunning, readCurrentCourt, recordCurrentCourt, renderResumeCommand, RunWriterLeaseHeldError, } from "./run-lifecycle.js";
+import { processCancelDiagnostic, processCancelSignalName, } from "./process-cancel.js";
 import { homeFromRunDirectory } from "../activation-ledger-topology.js";
 import { attemptProducedFreshSubmission, classifyPostAdmissionFailure, controlledFailureInputFromResolution, exitCodeForTerminalOutcome, explicitInternalKnownFailureClassificationInput, formatCliDiagnostic, formatTerminalResult, inspectJudgeSession, isLawfulTypedTerminalOutcome, presentFailureTerminal, presentStructuralRejection, resolveAuditedRunnerFailureResolution, resolveControlledFailureResumeObservation, settleFailureTerminalResult, settleHostEndedNoReceipt, attachRecordedSubmissions, } from "./settlement.js";
 import {} from "./terminal.js";
 import { ensureRealArtifactsDirectory, persistReturnedRunState, runWithAutoResumeLoop, TurnDispatchedFailure, } from "./auto-resume.js";
+/** #855: process-cancel settlement never re-enters auto-resume. */
+function withProcessCancelSkipAutoResume(result, signal) {
+    if (processCancelSignalName(signal) === undefined) {
+        return result;
+    }
+    return { ...result, skipAutoResume: true };
+}
+/**
+ * #855: turn already started, then a catchable process signal arrived before
+ * lawful seal — settle as named cancel failure and skip auto-resume.
+ */
+async function settleProcessCancelAfterTurn(input) {
+    const failed = await settleAfterTurnStarted(input.admitted, withEngineDetourInvocationScope({
+        timedOut: input.result.timedOut,
+        code: input.result.code,
+        stderr: input.result.stderr,
+        knownDiagnostic: processCancelDiagnostic(input.cancelName),
+    }, input.invocationScopeId), input.adapters, input.env.principalAuthority, input.io, input.persistRunState);
+    return {
+        ...failed,
+        turnDispatched: true,
+        skipAutoResume: true,
+        ...input.deferredPersist,
+    };
+}
 /**
  * Nested station-child role already finished its own call-local loop.
  * Parent records that failure once and must not auto-resume into a re-summon
@@ -258,6 +284,26 @@ export async function dispatchPostAdmissionTurn(input) {
         if (afterDispatchApplied)
             return result;
         afterDispatchApplied = true;
+        // #855: re-read cancel before afterDispatch finalization — never present
+        // lawful success after a catchable process signal. skipRunStateWrite: run-state
+        // may already be terminal from a prior lawful persist; do not reopen as resumable.
+        const cancelBeforeFinish = processCancelSignalName(env.signal);
+        if (cancelBeforeFinish !== undefined &&
+            result.terminal !== undefined &&
+            isLawfulTypedTerminalOutcome(result.terminal.roleOutcome)) {
+            result = {
+                ...(await settleAfterTurnStarted(admitted, withEngineDetourInvocationScope({
+                    timedOut: false,
+                    code: null,
+                    stderr: "",
+                    knownDiagnostic: processCancelDiagnostic(cancelBeforeFinish),
+                    skipRunStateWrite: true,
+                }, request.invocationScopeId), adapters, env.principalAuthority, io, persistRunState)),
+                turnDispatched: true,
+                skipAutoResume: true,
+                ...deferredPersist,
+            };
+        }
         try {
             // #858: an unbound seat may assert its ticket on the existing receipt.
             // Read the original accepted payload; do not rewrite it, infer from prose,
@@ -412,13 +458,16 @@ export async function dispatchPostAdmissionTurn(input) {
             result = await env.roleTurnHost.executeTurn(turnRequest);
         }
         catch (error) {
+            const processCancelName = processCancelSignalName(env.signal);
             const settled = await settleAfterTurnStarted(admitted, withEngineDetourInvocationScope({
                 timedOut: false,
                 code: null,
                 stderr: "",
-                thrown: error,
+                thrown: processCancelName === undefined
+                    ? error
+                    : new Error(processCancelDiagnostic(processCancelName), { cause: error }),
             }, request.invocationScopeId), adapters, env.principalAuthority, io, persistRunState);
-            return await finishAfterTurn({ ...settled, turnDispatched: true, ...deferredPersist });
+            return await finishAfterTurn(withProcessCancelSkipAutoResume({ ...settled, turnDispatched: true, ...deferredPersist }, env.signal));
         }
         // `result.stderr` stays live in memory for the real classification below
         // regardless of whether this durable mirror write succeeds. A write
@@ -514,10 +563,12 @@ export async function dispatchPostAdmissionTurn(input) {
             // retroactively invalidate an acceptance that already sealed this turn
             // — a resolved 429 observed earlier in the same session is exactly
             // that.
+            const processCancelName = processCancelSignalName(env.signal);
             const directHostFailureSignal = result.timedOut
                 || result.knownFailure !== undefined
                 || runnerKnownFailure !== undefined
-                || credentialFailure !== undefined;
+                || credentialFailure !== undefined
+                || processCancelName !== undefined;
             hostSignalFailed =
                 directHostFailureSignal
                     || (result.code !== null && result.code !== 0)
@@ -553,11 +604,15 @@ export async function dispatchPostAdmissionTurn(input) {
             // where a bare nonzero exit / resolution failure must not be outranked
             // by someone else's earlier success (#836 r12 class 2).
             const staleAcceptanceOutranksRealFailure = !settledIsFreshThisAttempt && hostSignalFailed;
+            // #855: re-read cancel after trySettle/attach awaits — a signal in this
+            // window must not land as lawful accepted.
+            const cancelAfterSettle = processCancelSignalName(env.signal);
             if (settled !== undefined
                 && shouldPresent(settled)
                 && !directHostFailureSignal
                 && !staleAcceptanceOutranksRealFailure
-                && stderrLogWriteFailure === undefined) {
+                && stderrLogWriteFailure === undefined
+                && cancelAfterSettle === undefined) {
                 // This court sealed — drop open-court pointer (bare resume no longer continues it).
                 if (settled.roleOutcome.kind === "accepted" &&
                     request.courtAttemptId !== undefined &&
@@ -597,6 +652,22 @@ export async function dispatchPostAdmissionTurn(input) {
             return await finishAfterTurn({ ...settledFailure, turnDispatched: true, ...deferredPersist });
         }
         if (settledOutcome !== undefined) {
+            // #855: final cancel re-read before lawful seal — settlement window may
+            // have received SIGTERM/SIGINT/SIGHUP after the earlier snapshot.
+            const lateCancel = processCancelSignalName(env.signal);
+            if (lateCancel !== undefined) {
+                return await finishAfterTurn(await settleProcessCancelAfterTurn({
+                    admitted,
+                    cancelName: lateCancel,
+                    result,
+                    adapters,
+                    env,
+                    io,
+                    persistRunState,
+                    deferredPersist,
+                    invocationScopeId: request.invocationScopeId,
+                }));
+            }
             if (persistRunState) {
                 try {
                     await persistReturnedRunState(admitted, env.principalAuthority, { lawful: true });
@@ -619,16 +690,18 @@ export async function dispatchPostAdmissionTurn(input) {
                         thrown: error,
                         skipRunStateWrite: true,
                     }, request.invocationScopeId), adapters, env.principalAuthority, io, persistRunState);
-                    return await finishAfterTurn({ ...failed, turnDispatched: true, ...deferredPersist });
+                    return await finishAfterTurn(withProcessCancelSkipAutoResume({ ...failed, turnDispatched: true, ...deferredPersist }, env.signal));
                 }
             }
             // Lawful persist + present is the caller's stop seam (auto-resume loop /
             // manual resume), not this retried host-turn function.
+            // #855 cancel re-read lives in finishAfterTurn (before afterDispatch).
             return await finishAfterTurn({ ...settledOutcome, ...deferredPersist });
         }
         // Host/runner true failure coexists with already-recorded payloads — never wash as accepted.
         if (hostSignalFailed) {
             const resolutionInput = controlledFailureInputFromResolution(resolution);
+            const processCancelName = processCancelSignalName(env.signal);
             const stderrLogWriteDetails = stderrLogWriteFailure === undefined
                 ? undefined
                 : { stderrLogWriteFailure: describeCaughtError(stderrLogWriteFailure) };
@@ -637,6 +710,9 @@ export async function dispatchPostAdmissionTurn(input) {
                 code: result.code,
                 stderr: result.stderr,
                 ...resolutionInput,
+                ...(processCancelName === undefined
+                    ? {}
+                    : { knownDiagnostic: processCancelDiagnostic(processCancelName) }),
                 // Secondary fact only — never the cause. Rides on whichever channel
                 // classification actually reads (knownFailure.details owns it when
                 // a knownFailure exists; the top-level knownDetails otherwise).
@@ -651,7 +727,7 @@ export async function dispatchPostAdmissionTurn(input) {
                         }
                         : { knownDetails: stderrLogWriteDetails }),
             }, request.invocationScopeId), adapters, env.principalAuthority, io, persistRunState);
-            return await finishAfterTurn({ ...failed, turnDispatched: true, ...deferredPersist });
+            return await finishAfterTurn(withProcessCancelSkipAutoResume({ ...failed, turnDispatched: true, ...deferredPersist }, env.signal));
         }
         // Nothing else was wrong, but the durable stderr mirror itself failed to
         // write — that is the real (infrastructure) problem in this case, not a
@@ -666,6 +742,21 @@ export async function dispatchPostAdmissionTurn(input) {
             return await finishAfterTurn({ ...failed, turnDispatched: true, ...deferredPersist });
         }
         const noReceipt = await attachRecordedSubmissions(admitted, await settleHostEndedNoReceipt(admitted, env.principalAuthority, courtScope), courtScope);
+        // #855: cancel during no_receipt settlement window is not lawful success.
+        const noReceiptCancel = processCancelSignalName(env.signal);
+        if (noReceiptCancel !== undefined) {
+            return await finishAfterTurn(await settleProcessCancelAfterTurn({
+                admitted,
+                cancelName: noReceiptCancel,
+                result,
+                adapters,
+                env,
+                io,
+                persistRunState,
+                deferredPersist,
+                invocationScopeId: request.invocationScopeId,
+            }));
+        }
         if (persistRunState) {
             try {
                 await persistReturnedRunState(admitted, env.principalAuthority, { lawful: true });
@@ -683,9 +774,10 @@ export async function dispatchPostAdmissionTurn(input) {
                     thrown: error,
                     skipRunStateWrite: true,
                 }, request.invocationScopeId), adapters, env.principalAuthority, io, persistRunState);
-                return await finishAfterTurn({ ...failed, turnDispatched: true, ...deferredPersist });
+                return await finishAfterTurn(withProcessCancelSkipAutoResume({ ...failed, turnDispatched: true, ...deferredPersist }, env.signal));
             }
         }
+        // #855 cancel re-read lives in finishAfterTurn (before afterDispatch).
         return await finishAfterTurn({
             exitCode: exitCodeForTerminalOutcome(noReceipt.roleOutcome),
             admitted,
@@ -972,6 +1064,7 @@ export async function runPostAdmissionSeatResume(input) {
                 io: input.io,
                 sessionAppender: env.sessionAppender,
                 autoResumeLimit: env.autoResumeLimit,
+                ...(env.signal === undefined ? {} : { signal: env.signal }),
                 buildInitialPayload: () => ({ resumeTurn: false }),
                 buildResumePayload: () => ({ resumeTurn: true }),
                 // Same as public manual resume: prior-court sealed acceptance is not a
@@ -1095,6 +1188,7 @@ export async function runPostAdmissionResumable(input) {
         io,
         sessionAppender: env.sessionAppender,
         autoResumeLimit: env.autoResumeLimit,
+        ...(env.signal === undefined ? {} : { signal: env.signal }),
         buildInitialPayload: buildScopedInitial,
         buildResumePayload: buildScopedResume,
         dispatch: async (request, lease, _isFirst, attemptIo) => {

package/dist/public-cli/process-cancel.js

@@ -0,0 +1,57 @@
+/**
+ * #855: catchable process signals for ak-role public entry.
+ * SIGTERM / SIGINT / SIGHUP abort the shared controller so hosts can gracefully
+ * terminate children (SIGTERM only, never SIGKILL). Uncatchable death (SIGKILL,
+ * crash, power loss) is reported via run-state + writer lease on analyst.
+ */
+const CATCHABLE_PROCESS_SIGNALS = ["SIGTERM", "SIGINT", "SIGHUP"];
+/**
+ * Install once per process entry. First catchable signal wins; later signals
+ * are ignored so settlement can finish without re-entry storms.
+ */
+export function installProcessCancelHandlers(processRef = process) {
+    const controller = new AbortController();
+    let received;
+    const listeners = new Map();
+    for (const sig of CATCHABLE_PROCESS_SIGNALS) {
+        const onSignal = () => {
+            if (received !== undefined)
+                return;
+            received = sig;
+            try {
+                controller.abort(sig);
+            }
+            catch {
+                // already aborted
+            }
+        };
+        listeners.set(sig, onSignal);
+        processRef.on(sig, onSignal);
+    }
+    return {
+        signal: controller.signal,
+        receivedSignal: () => received,
+        dispose() {
+            for (const [sig, onSignal] of listeners) {
+                processRef.off(sig, onSignal);
+            }
+            listeners.clear();
+        },
+    };
+}
+/** Signal name when this AbortSignal was aborted by installProcessCancelHandlers. */
+export function processCancelSignalName(signal) {
+    if (signal === undefined || signal.aborted !== true)
+        return undefined;
+    const reason = signal.reason;
+    if (reason === "SIGTERM" ||
+        reason === "SIGINT" ||
+        reason === "SIGHUP") {
+        return reason;
+    }
+    return undefined;
+}
+/** Diagnostic line for a catchable process-signal termination (failure honesty). */
+export function processCancelDiagnostic(signalName) {
+    return `ak-role terminated by ${signalName}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.4620",
+  "version": "0.1.4631",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/scripts/build-package.mjs

@@ -19,7 +19,6 @@ const entries = [
   "pi/in-process-session",
   "activation-ledger-git",
   "activation-ledger-topology",
-  "activation-reconciliation",
   "archivist-record-entry",
   // Pure subject nest topology — static import of archivist-record-entry;
   // cold discovery without SessionManager (#636). Keep listed while that

package/src/activation-ledger-topology.ts

@@ -91,11 +91,6 @@ export function activationBookDirectory(ledgerHome: string, bookKey: string): st
   return join(ledgerHome, "books", bookKey);
 }
 
-/** Append-only waiting ledger path for one book. */
-export function activationWaitingLedgerPath(ledgerHome: string, bookKey: string): string {
-  return join(activationBookDirectory(ledgerHome, bookKey), "waiting.jsonl");
-}
-
 /** True when candidate resolves strictly inside root (boundary-safe; not a string-prefix check). */
 export function pathContainedIn(root: string, candidate: string): boolean {
   const rel = relative(root, candidate);
@@ -323,7 +318,7 @@ export function ensureRealDirectoryTree(root: string, targetDir: string): string
 
 /**
  * Reject a pre-existing ledger-file symlink before open/write follows it.
- * A computed book may only append to its own regular waiting.jsonl — any symlink,
+ * A computed book path may only write its own regular file — any symlink,
  * including a target still inside the machine ledger home (cross-book redirect),
  * violates ADR 0048 partition identity. Missing paths are admitted (O_CREAT).
  */

package/src/activation-ledger.ts

@@ -1,25 +1,8 @@
-import {
-  constants,
-  closeSync,
-  fstatSync,
-  openSync,
-  writeSync,
-} from "node:fs";
-import { dirname, isAbsolute, resolve } from "node:path";
-
-import type { ActivationSessionPointer } from "./activation-ledger-session.ts";
-import {
-  ActivationLedgerError,
-  activationWaitingLedgerPath,
-  assertLedgerFileInsideHome,
-  ensureRealDirectoryTree,
-  errorText,
-} from "./activation-ledger-topology.ts";
-
-/** Private open flags: O_NOFOLLOW closes the lstat→open TOCTOU window. */
-const ACTIVATION_LEDGER_APPEND_OPEN_FLAGS =
-  constants.O_APPEND | constants.O_CREAT | constants.O_WRONLY | constants.O_NOFOLLOW;
-
+/**
+ * Activation ledger surface: durable session principal + book/home topology.
+ * #855: two-face waiting.jsonl reconciliation deleted — this module no longer
+ * appends accepted-activation facts or own a waiting path.
+ */
 export {
   ActivationGitRepositoryRequiredError,
   resolveBookKeyFromGit,
@@ -33,219 +16,5 @@ export {
 export {
   ActivationLedgerError,
   activationBookDirectory,
-  activationWaitingLedgerPath,
   resolveActivationLedgerHome,
 } from "./activation-ledger-topology.ts";
-
-/** Caller-preassigned correlation id, or an explicit absent identity (never empty string). */
-export type ActivationCorrelationIdentity =
-  | { readonly kind: "caller"; readonly id: string }
-  | { readonly kind: "absent" };
-
-export const ACCEPTED_ACTIVATION_EVENT = "accepted-activation" as const;
-
-/**
- * Package-owned index-only top-level keys for accepted-activation facts (ADR 0049).
- * Sole machine key contract: projection and tests consume this descriptor — not prose markers.
- */
-export const ACCEPTED_ACTIVATION_FACT_KEYS = Object.freeze([
-  "event",
-  "role",
-  "observedAt",
-  "bookKey",
-  "session",
-  "correlation",
-] as const);
-
-export type AcceptedActivationFactKey = (typeof ACCEPTED_ACTIVATION_FACT_KEYS)[number];
-
-/**
- * Closed activation fact: index fields only (ADR 0049).
- * No prompt, transcript, argv, excerpt, or other content.
- */
-export type AcceptedActivationFact = {
-  readonly event: typeof ACCEPTED_ACTIVATION_EVENT;
-  readonly role: string;
-  readonly observedAt: string;
-  readonly bookKey: string;
-  readonly session: ActivationSessionPointer;
-  readonly correlation: ActivationCorrelationIdentity;
-};
-
-// Keys tuple ↔ fact type must stay exact (compile fail on drift; no second field list).
-type ExactKeyMatch<T, K extends PropertyKey> =
-  Exclude<keyof T, K> | Exclude<K, keyof T> extends never ? true : never;
-const _acceptedActivationFactKeysMatch: ExactKeyMatch<
-  AcceptedActivationFact,
-  AcceptedActivationFactKey
-> = true;
-void _acceptedActivationFactKeysMatch;
-
-/** Trusted typed inputs for building the closed fact (canonical fact minus event discriminant). */
-export type AcceptedActivationFactInput = Omit<AcceptedActivationFact, "event">;
-
-/**
- * Host correlation channel (not a CLI flag): a non-blank AK_CORRELATION_ID carries
- * the caller id verbatim; missing/blank/whitespace-only yields the typed absent identity.
- */
-export function correlationIdentityFromEnv(
-  env: NodeJS.ProcessEnv = process.env,
-): ActivationCorrelationIdentity {
-  const raw = env.AK_CORRELATION_ID;
-  if (typeof raw === "string" && raw.trim().length > 0) {
-    return { kind: "caller", id: raw };
-  }
-  return { kind: "absent" };
-}
-
-/**
- * Descriptor-driven top-level pick: only ACCEPTED_ACTIVATION_FACT_KEYS leave this boundary.
- * Nested session/correlation are rebuilt closed before the pick (ADR 0049: first-phase ledger holds zero content bytes by construction).
- */
-function projectAcceptedActivationFact(
-  input: AcceptedActivationFactInput,
-): AcceptedActivationFact {
-  const closed: AcceptedActivationFact = {
-    event: ACCEPTED_ACTIVATION_EVENT,
-    role: input.role,
-    observedAt: input.observedAt,
-    bookKey: input.bookKey,
-    session: { kind: "session-file", path: input.session.path },
-    correlation: input.correlation.kind === "caller"
-      ? { kind: "caller", id: input.correlation.id }
-      : { kind: "absent" },
-  };
-  // Descriptor is the sole top-level emission contract (typed pick; no content keys).
-  return Object.fromEntries(
-    ACCEPTED_ACTIVATION_FACT_KEYS.map((key) => [key, closed[key]]),
-  ) as AcceptedActivationFact;
-}
-
-/** Construct the closed fact from trusted typed inputs only (descriptor projection — no content keys). */
-export function buildAcceptedActivationFact(input: AcceptedActivationFactInput): AcceptedActivationFact {
-  return projectAcceptedActivationFact(input);
-}
-
-/** Serialize only the closed index fields (descriptor projection — no content keys). */
-export function serializeAcceptedActivationFact(fact: AcceptedActivationFact): string {
-  return `${JSON.stringify(projectAcceptedActivationFact(fact))}\n`;
-}
-
-/**
- * Bare O_APPEND write of one complete line under an absolute ledger home.
- * Private helper: production-bound to writeSync; owns open/write/close honesty only.
- * Close failure cannot mask open/write; simultaneous close is nested evidence.
- */
-function appendActivationLedgerLine(
-  ledgerPath: string,
-  line: Uint8Array,
-  options: { ledgerHome: string },
-): void {
-  if (!isAbsolute(options.ledgerHome)) {
-    throw new ActivationLedgerError(
-      `activation ledger home must be absolute: ${options.ledgerHome}`,
-    );
-  }
-  const resolvedLedger = resolve(ledgerPath);
-  const resolvedHome = resolve(options.ledgerHome);
-  const parent = dirname(resolvedLedger);
-  ensureRealDirectoryTree(resolvedHome, parent);
-  assertLedgerFileInsideHome(resolvedLedger, resolvedHome);
-
-  // Fail-closed guard (same shape as PR #418's publication seam): on platforms
-  // without O_NOFOLLOW (e.g. Windows, nodejs/node#41590) the JS bitwise-or in
-  // ACTIVATION_LEDGER_APPEND_OPEN_FLAGS would silently drop the flag and the
-  // lstat→open TOCTOU anti-symlink protection would vanish while the comment
-  // above still claims it. Refuse loudly via the existing typed ledger failure
-  // channel instead of appending unprotected; never silently degrade.
-  if (typeof constants.O_NOFOLLOW !== "number") {
-    throw new ActivationLedgerError(
-      "activation ledger append requires O_NOFOLLOW open-flag support (anti-symlink TOCTOU protection must not be silently dropped); refusing to append",
-    );
-  }
-  const bytes = Buffer.isBuffer(line) ? line : Buffer.from(line);
-  let ledgerFd: number | undefined;
-  let primaryFailure: unknown;
-  try {
-    try {
-      ledgerFd = openSync(resolvedLedger, ACTIVATION_LEDGER_APPEND_OPEN_FLAGS, 0o644);
-    } catch (error) {
-      // Native ELOOP/filesystem cause retained; no errno dispatch.
-      throw new ActivationLedgerError(
-        `activation ledger failed to open ledger file (${resolvedLedger}): ${errorText(error)}`,
-        { cause: error },
-      );
-    }
-
-    let opened: ReturnType<typeof fstatSync>;
-    try {
-      opened = fstatSync(ledgerFd);
-    } catch (error) {
-      throw new ActivationLedgerError(
-        `activation ledger failed to fstat ledger file (${resolvedLedger}): ${errorText(error)}`,
-        { cause: error },
-      );
-    }
-    if (!opened.isFile()) {
-      throw new ActivationLedgerError(
-        `activation ledger is not a regular file: ${resolvedLedger}`,
-      );
-    }
-
-    const written = writeSync(ledgerFd, bytes, 0, bytes.length, null);
-    if (written !== bytes.length) {
-      throw new ActivationLedgerError(
-        `activation ledger short write: wrote ${written} of ${bytes.length} bytes to ${resolvedLedger}`,
-      );
-    }
-  } catch (error) {
-    primaryFailure = error;
-  }
-
-  if (ledgerFd !== undefined) {
-    try {
-      closeSync(ledgerFd);
-    } catch (closeFailure) {
-      if (primaryFailure !== undefined) {
-        throw new AggregateError(
-          [primaryFailure, closeFailure],
-          "activation ledger operation and close failed",
-          { cause: primaryFailure },
-        );
-      }
-      throw closeFailure;
-    }
-  }
-
-  if (primaryFailure !== undefined) throw primaryFailure;
-}
-
-/**
- * Append one complete JSONL record with one O_APPEND write of the full record.
- * Shared-ledger contract: concurrent successful append-only producers cannot
- * overwrite one another. A short write is an honest infrastructure failure
- * (ADR 0049) — no non-append rollback/truncate. Close failure cannot mask the
- * primary write cause; simultaneous close evidence is retained.
- */
-export function appendAcceptedActivationFact(
-  ledgerPath: string,
-  fact: AcceptedActivationFact,
-  options: { ledgerHome: string },
-): void {
-  appendActivationLedgerLine(
-    ledgerPath,
-    Buffer.from(serializeAcceptedActivationFact(fact), "utf8"),
-    { ledgerHome: options.ledgerHome },
-  );
-}
-
-export function appendAcceptedActivationToBook(options: {
-  ledgerHome: string;
-  fact: AcceptedActivationFact;
-}): void {
-  appendAcceptedActivationFact(
-    activationWaitingLedgerPath(options.ledgerHome, options.fact.bookKey),
-    options.fact,
-    { ledgerHome: options.ledgerHome },
-  );
-}

package/src/analyst-entry.ts

@@ -22,9 +22,12 @@ import {
 } from "./analyst-cohort.ts";
 import {
   scanAnalystIssueRuns,
+  type AnalystGhostLeg,
   type AnalystReadableRunFacts,
   type AnalystScopedRunScan,
 } from "./analyst-ledger.ts";
+
+export type { AnalystGhostLeg, AnalystGhostLeaseCheck } from "./analyst-ledger.ts";
 import {
   mergeAnalystLibraryIndexRows,
   rowFromIssueMetricsPage,
@@ -173,6 +176,11 @@ export type AnalystIssueModeResult = {
   readonly mode: "issue";
   readonly page: AnalystIssueMetricsPage;
   readonly pagePath: string;
+  /**
+   * #855 live observation: admitted|running runs whose writer lease cannot prove
+   * a live holder. Fresh each query — never cached on the metrics page.
+   */
+  readonly ghostLegs: readonly AnalystGhostLeg[];
 };
 
 export type AnalystSweepModeResult = {
@@ -264,7 +272,16 @@ export async function readOrComputeAnalystIssuePage(
     const raw = await readFile(pagePath, "utf8");
     const page = JSON.parse(raw) as AnalystIssueMetricsPage;
     if (cachedPageMatchesRequestedScope(page, { bookKey, ...input })) {
-      return { mode: "issue", page, pagePath };
+      // #855 ghost legs are live observations — always fresh, never from the page cache.
+      const ghostScan = await scanAnalystIssueRuns({
+        bookKey,
+        ...(issueNumber === undefined ? {} : { ticketNumber: issueNumber }),
+        ...(options?.scanProjectRoot === undefined
+          ? {}
+          : { projectRoot: options.scanProjectRoot }),
+        ...(options?.home === undefined ? {} : { home: options.home }),
+      });
+      return { mode: "issue", page, pagePath, ghostLegs: ghostScan.ghostLegs };
     }
     // Existing page is for a different / absent ticket scope — same kernel recompute.
   } catch (error) {
@@ -364,7 +381,7 @@ async function runAnalystIssueMode(
     ]);
   }
 
-  return { mode: "issue", page, pagePath };
+  return { mode: "issue", page, pagePath, ghostLegs: scan.ghostLegs };
 }
 
 async function runAnalystSweepMode(