@akagilnc/pi-workflow-roles 0.1.4620 → 0.1.4631

package/src/public-cli/process-cancel.ts

@@ -0,0 +1,75 @@
+/**
+ * #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"] as const;
+
+export type CatchableProcessSignal = (typeof CATCHABLE_PROCESS_SIGNALS)[number];
+
+export type ProcessCancelHandle = {
+  readonly signal: AbortSignal;
+  /** Signal name once a catchable signal has been received; else undefined. */
+  readonly receivedSignal: () => CatchableProcessSignal | undefined;
+  dispose(): void;
+};
+
+/**
+ * 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: NodeJS.Process = process,
+): ProcessCancelHandle {
+  const controller = new AbortController();
+  let received: CatchableProcessSignal | undefined;
+  const listeners = new Map<CatchableProcessSignal, () => void>();
+
+  for (const sig of CATCHABLE_PROCESS_SIGNALS) {
+    const onSignal = (): void => {
+      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(): void {
+      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: AbortSignal | undefined,
+): CatchableProcessSignal | undefined {
+  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: CatchableProcessSignal): string {
+  return `ak-role terminated by ${signalName}`;
+}

package/src/role-runtime.ts

@@ -17,20 +17,10 @@ import { createSubmissionLedgerHost, sealAcceptedSubmission } from "./submission
 import { createCollectorLedger } from "./collector-ledger.ts";
 
 import { activationTraceRecordSchema, namedActivationCause, type ActivationTraceRecord, type ActivationTraceWriter } from "./activation-trace.ts";
+import { homeFromRunDirectory } from "./activation-ledger-topology.ts";
 import {
-  homeFromRunDirectory,
-  resolveActivationLedgerHomeForPath,
-} from "./activation-ledger-topology.ts";
-import {
-  appendAcceptedActivationToBook,
-  buildAcceptedActivationFact,
-  correlationIdentityFromEnv,
   durableSessionPointer,
-  resolveActivationLedgerHome,
   resolveBookKeyFromGit,
-  type AcceptedActivationFact,
-  type ActivationCorrelationIdentity,
-  type ActivationSessionPointer,
 } from "./activation-ledger.ts";
 import { writeStderrJsonlRecord } from "./stderr-jsonl.ts";
 import {
@@ -301,43 +291,18 @@ export {
 export { activationTraceRecordSchema, namedActivationCause } from "./activation-trace.ts";
 export type { ActivationTraceRecord, ActivationTraceWriter } from "./activation-trace.ts";
 export {
-  ACCEPTED_ACTIVATION_EVENT,
-  ACCEPTED_ACTIVATION_FACT_KEYS,
   ActivationGitRepositoryRequiredError,
   ActivationLedgerError,
   ActivationSessionFileMissingError,
   activationBookDirectory,
-  activationWaitingLedgerPath,
-  appendAcceptedActivationFact,
-  appendAcceptedActivationToBook,
-  buildAcceptedActivationFact,
-  correlationIdentityFromEnv,
   durableSessionPointer,
   resolveActivationLedgerHome,
   resolveBookKeyFromGit,
-  serializeAcceptedActivationFact,
 } from "./activation-ledger.ts";
 export type {
-  AcceptedActivationFact,
-  AcceptedActivationFactInput,
-  AcceptedActivationFactKey,
-  ActivationCorrelationIdentity,
   ActivationSessionManager,
   ActivationSessionPointer,
 } from "./activation-ledger.ts";
-export {
-  DISPATCH_STUB_EVENT,
-  buildDispatchStubFact,
-  reconcileInvocation,
-} from "./activation-reconciliation.ts";
-export type {
-  DispatchPointer,
-  DispatchStubFact,
-  DispatchStubFactInput,
-  ProcessLivenessFact,
-  ReconciliationOutcome,
-  ReconciliationSubject,
-} from "./activation-reconciliation.ts";
 export {
   TOOL_EXECUTION_UPDATE_HEARTBEAT,
   TOOL_EXECUTION_UPDATE_THROTTLE_MS,
@@ -2195,11 +2160,9 @@ export function createRoleRuntimeExtension(
         // Production topology only (ADR 0048/0049): no test-only ledger hooks.
         // Admit durable session file first so lifecycle getEntries/appendEntry are truthful:
         // deferred SM materialization must not wipe an in-memory principal marker.
-        const bookKey = resolveBookKeyFromGit(ctx.cwd);
-        const correlation = correlationIdentityFromEnv();
-        const sessionFile = ctx.sessionManager.getSessionFile?.() || ctx.sessionManager.getSessionDir?.();
-        const ledgerHome = resolveActivationLedgerHomeForPath(sessionFile);
-        const session = durableSessionPointer(ctx.sessionManager);
+        // #855: two-face waiting.jsonl write removed — fail-closed book-key + session only.
+        resolveBookKeyFromGit(ctx.cwd);
+        durableSessionPointer(ctx.sessionManager);
 
         // Station children (court diarist, inner-gate summons) omit navigator sidecar (#840).
         // Top-level public entry legs still attend automatically.
@@ -2314,16 +2277,6 @@ export function createRoleRuntimeExtension(
           if (entry.role === "coder") coder.armSubmissionGate(ctx.cwd, ctx.sessionManager);
           else fixer.armSubmissionGate(ctx.cwd, ctx.sessionManager);
         }
-        appendAcceptedActivationToBook({
-          ledgerHome,
-          fact: buildAcceptedActivationFact({
-            role: entry.role,
-            observedAt: clock(),
-            bookKey,
-            session,
-            correlation,
-          }),
-        });
         admitted = true;
       } catch (error) {
         failInfrastructure(error, ctx);

package/dist/activation-reconciliation.js

@@ -1,61 +0,0 @@
-const DISPATCH_STUB_EVENT = "dispatch-stub";
-function buildDispatchStubFact(input) {
-  return {
-    event: DISPATCH_STUB_EVENT,
-    observedAt: input.observedAt,
-    bookKey: input.bookKey,
-    dispatch: input.dispatch.kind === "process" ? { kind: "process", pid: input.dispatch.pid } : { kind: "opaque", ref: input.dispatch.ref },
-    correlation: { kind: "caller", id: input.correlation.id }
-  };
-}
-function callerCorrelationId(correlation) {
-  return correlation.kind === "caller" ? correlation.id : void 0;
-}
-function dispatchMatchesActivation(dispatch, activation) {
-  const activationId = callerCorrelationId(activation.correlation);
-  return activationId !== void 0 && activationId === dispatch.correlation.id && activation.bookKey === dispatch.bookKey;
-}
-function reconcileInvocation(subject) {
-  const { dispatch, activation, process } = subject;
-  if (activation !== void 0) {
-    if (dispatch !== void 0 && dispatchMatchesActivation(dispatch, activation)) {
-      return {
-        kind: "matched",
-        correlationId: dispatch.correlation.id,
-        bookKey: dispatch.bookKey
-      };
-    }
-    return {
-      kind: "activation-without-dispatch",
-      correlationId: callerCorrelationId(activation.correlation),
-      bookKey: activation.bookKey
-    };
-  }
-  if (dispatch !== void 0) {
-    if (process === void 0) {
-      throw new TypeError(
-        "reconcileInvocation requires process liveness when activation is absent"
-      );
-    }
-    if (process.state === "alive") {
-      return {
-        kind: "pending",
-        correlationId: dispatch.correlation.id,
-        bookKey: dispatch.bookKey
-      };
-    }
-    return {
-      kind: "ghost",
-      correlationId: dispatch.correlation.id,
-      bookKey: dispatch.bookKey
-    };
-  }
-  throw new TypeError(
-    "reconcileInvocation requires a dispatch stub and/or an accepted-activation fact"
-  );
-}
-export {
-  DISPATCH_STUB_EVENT,
-  buildDispatchStubFact,
-  reconcileInvocation
-};

package/src/activation-reconciliation.ts

@@ -1,163 +0,0 @@
-import type { AcceptedActivationFact } from "./activation-ledger.ts";
-
-/** Event category for pre-dispatch stub facts (#11 producer contract). */
-export const DISPATCH_STUB_EVENT = "dispatch-stub" as const;
-
-/**
- * Non-content dispatch pointer. Carries process identity or an opaque ref —
- * never prompt/argv/content bytes (ADR 0049).
- */
-export type DispatchPointer =
-  | { readonly kind: "process"; readonly pid: number }
-  | { readonly kind: "opaque"; readonly ref: string };
-
-/**
- * Minimum typed dispatch stub the #11 producer supplies before ignition.
- * Index-only: correlation, book, time, event category, non-content pointer.
- */
-export type DispatchStubFact = {
-  readonly event: typeof DISPATCH_STUB_EVENT;
-  readonly observedAt: string;
-  readonly bookKey: string;
-  readonly dispatch: DispatchPointer;
-  readonly correlation: { readonly kind: "caller"; readonly id: string };
-};
-
-/** Trusted typed inputs for building the closed dispatch stub (fact minus event discriminant). */
-export type DispatchStubFactInput = Omit<DispatchStubFact, "event">;
-
-/**
- * Construct the closed dispatch stub from trusted typed inputs only.
- * Nested dispatch/correlation are rebuilt closed (ADR 0049: first-phase ledger holds zero content bytes by construction).
- */
-export function buildDispatchStubFact(input: DispatchStubFactInput): DispatchStubFact {
-  return {
-    event: DISPATCH_STUB_EVENT,
-    observedAt: input.observedAt,
-    bookKey: input.bookKey,
-    dispatch: input.dispatch.kind === "process"
-      ? { kind: "process", pid: input.dispatch.pid }
-      : { kind: "opaque", ref: input.dispatch.ref },
-    correlation: { kind: "caller", id: input.correlation.id },
-  };
-}
-
-/**
- * Truthful process liveness supplied by the consumer.
- * Reconciliation never probes, kills, or retries processes (D1a / #78).
- */
-export type ProcessLivenessFact =
-  | { readonly state: "alive" }
-  | { readonly state: "terminated" };
-
-/**
- * One reconciliation subject as an exclusive complete union (four outcomes only):
- * - activation present → activation required; dispatch/process optional
- * - activation absent → dispatch + truthful process required; activation prohibited
- * No session-file existence oracle (ADR 0047). Untyped JS still hits runtime TypeError.
- */
-export type ReconciliationSubject =
-  | {
-      readonly activation: AcceptedActivationFact;
-      readonly dispatch?: DispatchStubFact;
-      readonly process?: ProcessLivenessFact;
-    }
-  | {
-      readonly activation?: undefined;
-      readonly dispatch: DispatchStubFact;
-      readonly process: ProcessLivenessFact;
-    };
-
-/**
- * Exactly four typed outcomes (D1a):
- * - matched — dispatch stub and matching accepted-activation fact
- * - pending — dispatch present, no activation, process still alive
- * - ghost — dispatch present, no activation, process terminated
- * - activation-without-dispatch — activation fact with no matching stub
- */
-export type ReconciliationOutcome =
-  | {
-      readonly kind: "matched";
-      readonly correlationId: string;
-      readonly bookKey: string;
-    }
-  | {
-      readonly kind: "pending";
-      readonly correlationId: string;
-      readonly bookKey: string;
-    }
-  | {
-      readonly kind: "ghost";
-      readonly correlationId: string;
-      readonly bookKey: string;
-    }
-  | {
-      readonly kind: "activation-without-dispatch";
-      readonly correlationId: string | undefined;
-      readonly bookKey: string;
-    };
-
-function callerCorrelationId(
-  correlation: AcceptedActivationFact["correlation"] | DispatchStubFact["correlation"],
-): string | undefined {
-  return correlation.kind === "caller" ? correlation.id : undefined;
-}
-
-function dispatchMatchesActivation(
-  dispatch: DispatchStubFact,
-  activation: AcceptedActivationFact,
-): boolean {
-  const activationId = callerCorrelationId(activation.correlation);
-  return (
-    activationId !== undefined
-    && activationId === dispatch.correlation.id
-    && activation.bookKey === dispatch.bookKey
-  );
-}
-
-/**
- * Reconcile one invocation's typed dispatch/activation facts against truthful
- * process liveness. Pure: never kills, never retries, never reads session files.
- */
-export function reconcileInvocation(subject: ReconciliationSubject): ReconciliationOutcome {
-  const { dispatch, activation, process } = subject;
-
-  if (activation !== undefined) {
-    if (dispatch !== undefined && dispatchMatchesActivation(dispatch, activation)) {
-      return {
-        kind: "matched",
-        correlationId: dispatch.correlation.id,
-        bookKey: dispatch.bookKey,
-      };
-    }
-    return {
-      kind: "activation-without-dispatch",
-      correlationId: callerCorrelationId(activation.correlation),
-      bookKey: activation.bookKey,
-    };
-  }
-
-  if (dispatch !== undefined) {
-    if (process === undefined) {
-      throw new TypeError(
-        "reconcileInvocation requires process liveness when activation is absent",
-      );
-    }
-    if (process.state === "alive") {
-      return {
-        kind: "pending",
-        correlationId: dispatch.correlation.id,
-        bookKey: dispatch.bookKey,
-      };
-    }
-    return {
-      kind: "ghost",
-      correlationId: dispatch.correlation.id,
-      bookKey: dispatch.bookKey,
-    };
-  }
-
-  throw new TypeError(
-    "reconcileInvocation requires a dispatch stub and/or an accepted-activation fact",
-  );
-}