@akagilnc/pi-workflow-roles 0.1.3902 → 0.1.3936

package/dist/prepared-role-turn.js

@@ -0,0 +1,5 @@
+import { renderAgentStartMaterials } from "./agent-start-materials.js";
+/** Fold structured system-prompt authority into the provider-visible ACP override. */
+export function renderSystemPromptOverride(authority) {
+    return renderAgentStartMaterials(authority.body, authority.materials);
+}

package/dist/public-cli/auto-resume.js

@@ -15,11 +15,35 @@ import { constants as fsConstants } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { lstat, mkdir, open } from "node:fs/promises";
 import { join } from "node:path";
-import { AUTO_RESUME_LIMIT, describeErrorIdentity, acquireRunWriterLease, markRunTerminal, RunWriterLeaseHeldError, } from "./run-lifecycle.js";
+import { AUTO_RESUME_LIMIT, describeErrorIdentity, acquireRunWriterLease, markRunResumable, markRunTerminal, RunWriterLeaseHeldError, } from "./run-lifecycle.js";
 import { parseAutoResumeLimit } from "./config.js";
 import { isLawfulTypedTerminalOutcome, formatTerminalResult } from "./terminal.js";
-import { presentFailureTerminal, presentStructuralRejection, } from "./settlement.js";
+import { presentFailureTerminal, presentStructuralRejection, resolveControlledFailureResumeObservation, } from "./settlement.js";
 const dummyIo = { stdout: () => { }, stderr: () => { } };
+/**
+ * Persist run-state after a host-turn result, outside the retried dispatch try.
+ * Lawful settlement always seals terminal — a typed 429 observation must not
+ * win (#416 成功即停). 429 only marks resumable on the controlled-failure path.
+ * Write failure must escape the retried dispatch try instead of becoming a
+ * synthetic host-turn terminal.
+ */
+export async function persistReturnedRunState(admitted, authority, options) {
+    if (options?.lawful === true) {
+        await markRunTerminal(admitted.runDirectory);
+        return;
+    }
+    const resumeObservation = await resolveControlledFailureResumeObservation({
+        runDirectory: admitted.runDirectory,
+    });
+    const typedHttp429 = resumeObservation.typedHttp429;
+    if (admitted.principal !== undefined && typedHttp429 !== undefined) {
+        if (await authority.isAvailable(admitted.principal)) {
+            await markRunResumable(admitted.runDirectory, typedHttp429);
+            return;
+        }
+    }
+    await markRunTerminal(admitted.runDirectory);
+}
 function presentTerminal(terminal, io) {
     if (terminal.roleOutcome.kind === "failure" || terminal.roleOutcome.kind === "no_receipt") {
         presentFailureTerminal(terminal, io);
@@ -42,6 +66,25 @@ async function finalizeExceptionRunBestEffort(runDirectory, io) {
         io.stderr(`run terminal-state finalization failed (best-effort continue): ${describeErrorIdentity(error)}\n`);
     }
 }
+/**
+ * Thrown by dispatchPostAdmissionTurn when a failure happens inside its own
+ * settlement authority (presentControlledFailure) after the host turn
+ * genuinely started — never to fabricate a replacement terminal (ADR 0080
+ * single-settlement-disposition: settlement stays exactly presentControlledFailure
+ * / settleFailureTerminalResult, or — once the retry budget is exhausted —
+ * this loop's own dispatchExceptionFailureTerminal). Its only job is to carry
+ * the "turn already started" fact across the throw boundary so this loop
+ * selects a resume payload on the next attempt instead of replaying the
+ * initial one (#840 r9 判词 class 1 boundary — 覆盖 executeTurn 已启动后至
+ * 返回带 turnDispatched 结果前的全部异常). `cause` is the true failure;
+ * retention below serializes it whole via the standard Error.cause chain.
+ */
+export class TurnDispatchedFailure extends Error {
+    name = "TurnDispatchedFailure";
+    constructor(cause) {
+        super(`settlement failed after the host turn genuinely started: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+    }
+}
 /** Session custom-entry type carrying the pointer to one dispatch error file. */
 export const DISPATCH_ERROR_RETENTION_ENTRY_TYPE = "ak_run_dispatch_error_retention";
 /** Artifacts subdirectory of a run directory (established run-artifacts location). */
@@ -51,20 +94,23 @@ function runArtifactsDirectory(runDirectory) {
 /**
  * #182-A hardened path identity, mirrored from settlement.ts's
  * ensureAuditEvidenceDirectory: a planted symlink at the run directory or the
- * artifacts path must not receive the dispatch error dump (O_NOFOLLOW only
+ * artifacts path must not receive a durable run artifact (O_NOFOLLOW only
  * protects the final file name; recursive mkdir would accept a symlinked
- * parent). Fails loudly with the true cause instead.
+ * parent). Fails loudly with the true cause instead. Shared by every caller
+ * that needs a durable run-artifacts write independent of session/dossier
+ * health — dispatch-error retention here, and post-admission's best-effort
+ * cleanup diagnostic (#840 bounce class 2).
  */
-async function ensureRealArtifactsDirectory(runDirectory) {
+export async function ensureRealArtifactsDirectory(runDirectory) {
     const runStat = await lstat(runDirectory);
     if (runStat.isSymbolicLink() || !runStat.isDirectory()) {
-        throw new Error("dispatch error retention: run directory is not a real directory");
+        throw new Error("run artifact retention: run directory is not a real directory");
     }
     const artifactsDir = runArtifactsDirectory(runDirectory);
     try {
         const existing = await lstat(artifactsDir);
         if (existing.isSymbolicLink() || !existing.isDirectory()) {
-            throw new Error("dispatch error retention: artifacts path is not a real directory");
+            throw new Error("run artifact retention: artifacts path is not a real directory");
         }
     }
     catch (error) {
@@ -73,7 +119,7 @@ async function ensureRealArtifactsDirectory(runDirectory) {
         await mkdir(artifactsDir, { recursive: true });
         const created = await lstat(artifactsDir);
         if (created.isSymbolicLink() || !created.isDirectory()) {
-            throw new Error("dispatch error retention: artifacts directory is not a real directory");
+            throw new Error("run artifact retention: artifacts directory is not a real directory");
         }
     }
     return artifactsDir;
@@ -212,18 +258,35 @@ async function retainDispatchError(admitted, principalAuthority, sessionAppender
     }
     return pointerError === undefined ? { file: filePath } : { file: filePath, pointerError };
 }
+/**
+ * Unwrap TurnDispatchedFailure before this loop's own final presentation
+ * (#840 r9 判词 class 1 — the auto-resume.ts final presentation boundary).
+ * The wrapper only carries the "turn already genuinely started" signal
+ * across the throw boundary so the loop above selects a resume payload; the
+ * typed decisiveFacts and diagnostic text below must name the real cause it
+ * wraps (接住可以，洗白不行 — 未识别异常不得冒用具体标签，真因必须落痕), not
+ * the internal signal's own identity.
+ */
+function unwrapTurnDispatchedFailure(error) {
+    let current = error;
+    while (current instanceof TurnDispatchedFailure) {
+        current = current.cause;
+    }
+    return current;
+}
 /**
  * Typed failure terminal for a retry path that ended with only exceptions:
  * loud, non-lawful, carrying the last true cause and the pointers to the
  * full per-attempt error files. Never rethrows the raw exception at callers.
  */
 function dispatchExceptionFailureTerminal(input) {
+    const causeError = unwrapTurnDispatchedFailure(input.causeError);
     // #426 review: this terminal fires whenever the FINAL dispatch throws, not
     // only when every attempt threw — do not misrepresent a mixed retry history.
     const history = input.everyAttemptThrew
         ? "dispatch threw an exception on every attempt"
         : "the final dispatch threw an exception";
-    const diagnostic = `${history} (${input.endReason}; resumes used ${input.autoResumeAttempts}); last cause: ${describeErrorIdentity(input.causeError)}`;
+    const diagnostic = `${history} (${input.endReason}; resumes used ${input.autoResumeAttempts}); last cause: ${describeErrorIdentity(causeError)}`;
     const decisiveFacts = {
         cause: "unrecognized",
         diagnostic,
@@ -233,7 +296,7 @@ function dispatchExceptionFailureTerminal(input) {
     if (input.errorFiles.length > 0) {
         decisiveFacts.lastDispatchErrorFile = input.errorFiles[input.errorFiles.length - 1];
     }
-    const candidate = input.causeError;
+    const candidate = causeError;
     if (typeof candidate?.name === "string")
         decisiveFacts.errorName = candidate.name;
     if (typeof candidate?.code === "string" || typeof candidate?.code === "number") {
@@ -262,6 +325,8 @@ export async function runWithAutoResumeLoop(options) {
     // `attempts >= limit` comparison (always false) — reject here, before any dispatch.
     const limit = options.autoResumeLimit ?? AUTO_RESUME_LIMIT;
     parseAutoResumeLimit(limit);
+    const isPrincipalAvailable = options.isPrincipalAvailable ??
+        ((principal) => options.principalAuthority.isAvailable(principal));
     let autoResumeAttempts = 0;
     let isFirst = true;
     let currentPayload = options.buildInitialPayload();
@@ -282,6 +347,11 @@ export async function runWithAutoResumeLoop(options) {
             throw error;
         }
         let result;
+        // Set only when the caught throw is a TurnDispatchedFailure (#840 r9 判词
+        // class 1): the host turn genuinely started this attempt even though
+        // dispatch produced no result — the next payload must still be a resume,
+        // not a replay of the initial one.
+        let turnStartedBeforeThrow = false;
         try {
             result = await options.dispatch(currentPayload, lease, isFirst, dummyIo);
         }
@@ -292,6 +362,7 @@ export async function runWithAutoResumeLoop(options) {
             // diagnostic-sink-isolation precedent). The dispatcher owns lease release
             // in its own finally, so the retry round starts with the lock free.
             lastThrownError = error;
+            turnStartedBeforeThrow = error instanceof TurnDispatchedFailure;
             const attempt = dispatchOrdinal;
             try {
                 // Track the file as soon as it is durably written (#426 review):
@@ -309,6 +380,7 @@ export async function runWithAutoResumeLoop(options) {
             }
         }
         dispatchOrdinal += 1;
+        let persistFailure;
         if (result !== undefined) {
             everyAttemptThrew = false;
             const terminal = result.terminal;
@@ -316,6 +388,21 @@ export async function runWithAutoResumeLoop(options) {
                 terminal.autoResumeCount = autoResumeAttempts;
             }
             const lawful = terminal !== undefined && isLawfulTypedTerminalOutcome(terminal.roleOutcome);
+            if (result.needsPersist === true) {
+                // Persist on the loop seam, not inside retried dispatch.
+                try {
+                    await persistReturnedRunState(options.admitted, { isAvailable: isPrincipalAvailable }, lawful ? { lawful: true } : undefined);
+                }
+                catch (persistError) {
+                    // Lawful persist stays loud (no fake terminal). Non-lawful persist is
+                    // not a host-turn failure — do not auto-resume it — but sealed stop
+                    // must still see the already-settled result (#648).
+                    if (lawful)
+                        throw persistError;
+                    persistFailure = { error: persistError };
+                    lastThrownError = persistError;
+                }
+            }
             if (lawful) {
                 if (terminal !== undefined) {
                     // Present lawful terminal once to real io (dummy was used inside dispatch)
@@ -323,6 +410,11 @@ export async function runWithAutoResumeLoop(options) {
                 }
                 return result;
             }
+            if (result.skipAutoResume === true) {
+                if (terminal !== undefined)
+                    presentTerminal(terminal, options.io);
+                return result;
+            }
         }
         // Settlement-owned sealed disposition before any redispatch (#648 / #672):
         // shared for non-lawful return and direct throw. Only entry presentation
@@ -357,6 +449,9 @@ export async function runWithAutoResumeLoop(options) {
                 };
             }
         }
+        if (persistFailure !== undefined) {
+            throw persistFailure.error;
+        }
         if (result !== undefined) {
             const terminal = result.terminal;
             if (autoResumeAttempts >= limit) {
@@ -364,7 +459,8 @@ export async function runWithAutoResumeLoop(options) {
                     presentTerminal(terminal, options.io);
                 return result;
             }
-            if (!(await options.principalAuthority.isAvailable(options.admitted.principal))) {
+            if (result.turnDispatched === true
+                && !(await isPrincipalAvailable(options.admitted.principal))) {
                 if (terminal !== undefined)
                     presentTerminal(terminal, options.io);
                 return result;
@@ -389,7 +485,7 @@ export async function runWithAutoResumeLoop(options) {
                     terminal,
                 };
             }
-            if (!(await options.principalAuthority.isAvailable(options.admitted.principal))) {
+            if (!(await isPrincipalAvailable(options.admitted.principal))) {
                 const terminal = dispatchExceptionFailureTerminal({
                     role: options.admitted.role,
                     runId: options.admitted.runId,
@@ -408,7 +504,13 @@ export async function runWithAutoResumeLoop(options) {
             }
         }
         autoResumeAttempts++;
-        currentPayload = options.buildResumePayload();
+        // Resume payload only after a host turn actually started — either a
+        // returned result says so, or the attempt threw a TurnDispatchedFailure
+        // after genuinely starting the turn (#840 r9 判词 class 1). Pre-turn
+        // throws and beforeDispatch failures retry the initial payload (#840 / #416).
+        if (result?.turnDispatched === true || turnStartedBeforeThrow) {
+            currentPayload = options.buildResumePayload();
+        }
         isFirst = false;
     }
 }

package/dist/public-cli/diarist-run.js

@@ -0,0 +1,154 @@
+import { engineSessionMaterialFromOptions } from "../package-resources/engine-material.js";
+import { CliUsageError } from "./cli-errors.js";
+import { admitDiaristInvocation, bindAdmittedTicketNumber, buildInstructionTransportPrompt, } from "./invocation.js";
+import { prepareSummonsResumeMaterials, runPostAdmissionOneShot, runPostAdmissionSeatResume, resumeTurnRequestProjectionOptions, } from "./post-admission.js";
+import { loadResumableDiaristRun, markRunAdmitted, } from "./run-lifecycle.js";
+import { tryResumeSameTicketSeatRun } from "./seat-ticket-binding.js";
+import { presentStructuralRejection, trySettleDiaristTerminalResult, } from "./settlement.js";
+import { projectRoleTurnRequest, } from "./turn-request.js";
+/** Project admitted invocation onto the host-neutral turn request. */
+export function buildDiaristTurnRequest(admitted, options) {
+    return projectRoleTurnRequest(admitted, { activation: { role: "diarist" } }, options);
+}
+function diaristAdapters() {
+    return {
+        trySettle: (admitted, authority, scope) => trySettleDiaristTerminalResult(admitted, authority, scope),
+        shouldPresentSettled: () => true,
+    };
+}
+export async function runPublicDiarist(argv, env, io, parseDiaristArgv) {
+    let parsed;
+    try {
+        parsed = parseDiaristArgv(argv);
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            presentStructuralRejection(error, io);
+            return { exitCode: 2 };
+        }
+        throw error;
+    }
+    // #637 / #771 / ADR 0075 / #779: ticket identity is the LLM's typed assertion
+    // on this turn, OR a typed handoff key already held by the caller (countersign
+    // refresh). Code never pre-judges the summons text and never freezes a
+    // candidate catalog. First summons without handoff stays unbound until assert.
+    const projectRoot = parsed.project ?? env.cwd;
+    const handoffTicket = env.boundTicketNumber;
+    if (typeof handoffTicket === "number" &&
+        Number.isSafeInteger(handoffTicket) &&
+        handoffTicket >= 1) {
+        const summons = {
+            instruction: parsed.instruction,
+            instructionEmpty: parsed.instruction.trim() === "",
+            attachmentPaths: parsed.attachmentPaths,
+        };
+        const resumed = await tryResumeSameTicketSeatRun({
+            home: env.home,
+            projectRoot,
+            role: "diarist",
+            ticketNumber: handoffTicket,
+            freshSummons: env.freshSummons,
+            summons,
+            resume: (runId, materials) => runPublicDiaristResume({ runId, ...(materials === undefined ? {} : { summons: materials }) }, env, io),
+        });
+        if (resumed !== undefined)
+            return resumed;
+    }
+    let admitted;
+    try {
+        admitted = await admitDiaristInvocation({
+            home: env.home,
+            principalAuthority: env.principalAuthority,
+            cwd: env.cwd,
+            instruction: parsed.instruction,
+            attachmentPaths: parsed.attachmentPaths,
+            ...(parsed.project === undefined ? {} : { project: parsed.project }),
+            ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+            ...(env.model === undefined ? {} : { model: env.model }),
+            ...(env.correlationId === undefined ? {} : { correlationId: env.correlationId }),
+        });
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            presentStructuralRejection(error, io);
+            return { exitCode: 2 };
+        }
+        throw error;
+    }
+    await markRunAdmitted(admitted, env.principalAuthority);
+    // Typed handoff: bind before the turn so identity is on durable pages.
+    if (typeof handoffTicket === "number" &&
+        Number.isSafeInteger(handoffTicket) &&
+        handoffTicket >= 1) {
+        await bindAdmittedTicketNumber(admitted, handoffTicket);
+    }
+    const turnProjection = {
+        packageRoot: env.packageRoot,
+        home: env.home,
+        agentDir: env.agentDir,
+        ...(env.model === undefined ? {} : { model: env.model }),
+        ...(env.engine === undefined ? {} : { engine: env.engine }),
+        ...(env.timeoutMs === undefined ? {} : { timeoutMs: env.timeoutMs }),
+        ...(env.correlationId === undefined || env.correlationId.trim() === ""
+            ? {}
+            : { correlationId: env.correlationId }),
+        continuation: {
+            kind: "initial",
+            prompt: buildInstructionTransportPrompt(admitted, engineSessionMaterialFromOptions({
+                ...(env.engine === undefined ? {} : { engine: env.engine }),
+                packageRoot: env.packageRoot,
+            })),
+        },
+    };
+    const turnRequest = buildDiaristTurnRequest(admitted, turnProjection);
+    return await runPostAdmissionOneShot({
+        admitted,
+        env,
+        io,
+        request: turnRequest,
+        adapters: diaristAdapters(),
+        ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+    }).then(async (result) => {
+        // Accept may have bound ticket onto durable pages after LLM assertion.
+        // Mirror only lawful non-escalate accepted terminals — escalate must not
+        // leak an unverified ticketNumber into the caller-visible typed key.
+        if (admitted.ticketNumber === undefined && result.admitted !== undefined) {
+            const roleOutcome = result.terminal?.roleOutcome;
+            if (roleOutcome !== undefined &&
+                roleOutcome.kind === "accepted" &&
+                roleOutcome.status !== "escalate") {
+                const facts = roleOutcome.decisiveFacts;
+                const raw = typeof facts.ticketNumber === "number"
+                    ? facts.ticketNumber
+                    : typeof facts.sitian?.ticketNumber === "number"
+                        ? facts.sitian.ticketNumber
+                        : undefined;
+                if (typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 1) {
+                    admitted.ticketNumber = raw;
+                    if (result.admitted.ticketNumber === undefined) {
+                        result.admitted.ticketNumber = raw;
+                    }
+                }
+            }
+        }
+        return result;
+    });
+}
+/**
+ * Resume a previously admitted Diarist run (#708 / ADR 0079 同票传召 = resume).
+ * LLM re-finds materials; entry identity keeps the volume idempotent.
+ */
+export async function runPublicDiaristResume(request, env, io) {
+    return await runPostAdmissionSeatResume({
+        request,
+        env,
+        io,
+        load: (effective) => loadResumableDiaristRun(env.home, effective.runId, env.principalAuthority),
+        buildTurnRequest: async (admitted, effective) => {
+            const summonsPrepared = await prepareSummonsResumeMaterials(admitted.runDirectory, effective.summons);
+            return buildDiaristTurnRequest(admitted, resumeTurnRequestProjectionOptions(admitted, effective, env, summonsPrepared));
+        },
+        adapters: diaristAdapters(),
+        ...(env.engine === undefined ? {} : { effectiveEngine: env.engine }),
+    });
+}