@akagilnc/pi-workflow-roles 0.1.4659 → 0.1.4673

package/dist/navigator-public-session.js

@@ -73,7 +73,6 @@ function createNativeNavigatorSessionFactory(deps) {
     let providerFailure;
     let noReceipt;
     let disposed = false;
-    let inFlightPrompt;
     let hostRunId = readNavigatorHostRunPointer(sessionManager.getEntries());
     const summon = deps?.summonPublicRole ?? (async (options) => {
       const { summonPublicRole } = await import("./public-role-summons.js");
@@ -86,85 +85,87 @@ function createNativeNavigatorSessionFactory(deps) {
         }
         providerFailure = void 0;
         noReceipt = void 0;
-        const run = (async () => {
-          try {
-            const summonHome = await resolveNavigatorLedgerHome(context);
-            const resumeRunId = hostRunId;
-            const baseSummon = {
-              role: "navigator",
-              argv: [text],
-              cwd: context.cwd,
-              ...summonHome === void 0 ? {} : { home: summonHome }
-            };
-            const resumable = deps?.hostRunResumable ?? navigatorHostRunResumable;
-            let summoned;
-            if (resumeRunId === void 0 || summonHome === void 0) {
-              summoned = await summon(baseSummon);
-            } else if (await resumable(summonHome, resumeRunId)) {
+        try {
+          const summonHome = await resolveNavigatorLedgerHome(context);
+          if (disposed) return;
+          const resumeRunId = hostRunId;
+          const baseSummon = {
+            role: "navigator",
+            argv: [text],
+            cwd: context.cwd,
+            ...summonHome === void 0 ? {} : { home: summonHome },
+            ...context.signal === void 0 ? {} : { signal: context.signal }
+          };
+          const resumable = deps?.hostRunResumable ?? navigatorHostRunResumable;
+          let summoned;
+          if (resumeRunId === void 0 || summonHome === void 0) {
+            if (disposed) return;
+            summoned = await summon(baseSummon);
+          } else {
+            const canResume = await resumable(summonHome, resumeRunId);
+            if (disposed) return;
+            if (canResume) {
               summoned = await summon({ ...baseSummon, resumeRunId });
             } else {
               hostRunId = void 0;
               summoned = await summon(baseSummon);
             }
-            const outcome = summoned.terminal?.roleOutcome;
-            if (outcome === void 0) {
-              const detail = summoned.stderr?.trim() || `exit ${summoned.exitCode}`;
-              providerFailure = { source: "transport", cause: "unknown" };
-              throw navigatorUnavailableError(
-                providerFailure.source,
-                new Error(`Navigator public summon produced no terminal (${detail})`),
-                providerFailure.cause
-              );
-            }
-            if (outcome.kind === "failure") {
-              providerFailure = navigatorProviderFailureFromPublicTerminal(outcome);
-              throw navigatorUnavailableError(
-                providerFailure.source,
-                new Error(outcome.diagnostic),
-                providerFailure.cause
-              );
-            }
-            if (outcome.kind === "no_receipt") {
-              noReceipt = outcome;
-              return;
-            }
-            const runDirectory = summoned.runDirectory ?? (typeof summoned.admitted?.runDirectory === "string" ? summoned.admitted.runDirectory : void 0);
-            if (typeof runDirectory === "string" && runDirectory.trim() !== "") {
-              const nextRunId = runIdFromNavigatorDirectory(runDirectory);
-              if (nextRunId !== void 0) {
-                hostRunId = nextRunId;
-                sessionManager.appendCustomEntry(NAVIGATOR_HOST_RUN_POINTER_ENTRY, { runId: nextRunId });
-              }
-            }
-            if (outcome.kind !== "accepted") {
-              return;
-            }
-            const { navigatorProseFromUnknown } = await import("./package-contracts/navigator-output.js");
-            const proseParts = [];
-            for (const payload of outcome.payloads ?? []) {
-              const prose = navigatorProseFromUnknown(payload);
-              if (prose !== void 0) proseParts.push(prose);
-            }
-            if (proseParts.length === 0) return;
-            await tool.execute(
-              "navigator-public-prepare",
-              { prose: proseParts.join("\n\n") },
-              void 0,
-              void 0,
-              context
+          }
+          if (disposed) return;
+          const outcome = summoned.terminal?.roleOutcome;
+          if (outcome === void 0) {
+            const detail = summoned.stderr?.trim() || `exit ${summoned.exitCode}`;
+            providerFailure = { source: "transport", cause: "unknown" };
+            throw navigatorUnavailableError(
+              providerFailure.source,
+              new Error(`Navigator public summon produced no terminal (${detail})`),
+              providerFailure.cause
             );
-          } catch (error) {
-            if (error instanceof NavigatorUnavailableError) throw error;
-            const fact = navigatorProviderFailureFromError(error);
-            providerFailure = fact ?? { source: "transport", cause: "unknown" };
-            throw navigatorUnavailableError(providerFailure.source, error, providerFailure.cause);
           }
-        })();
-        inFlightPrompt = run;
-        try {
-          await run;
-        } finally {
-          if (inFlightPrompt === run) inFlightPrompt = void 0;
+          if (outcome.kind === "failure") {
+            providerFailure = navigatorProviderFailureFromPublicTerminal(outcome);
+            throw navigatorUnavailableError(
+              providerFailure.source,
+              new Error(outcome.diagnostic),
+              providerFailure.cause
+            );
+          }
+          if (outcome.kind === "no_receipt") {
+            noReceipt = outcome;
+            return;
+          }
+          const runDirectory = summoned.runDirectory ?? (typeof summoned.admitted?.runDirectory === "string" ? summoned.admitted.runDirectory : void 0);
+          if (typeof runDirectory === "string" && runDirectory.trim() !== "") {
+            const nextRunId = runIdFromNavigatorDirectory(runDirectory);
+            if (nextRunId !== void 0) {
+              hostRunId = nextRunId;
+              sessionManager.appendCustomEntry(NAVIGATOR_HOST_RUN_POINTER_ENTRY, { runId: nextRunId });
+            }
+          }
+          if (outcome.kind !== "accepted") {
+            return;
+          }
+          const { navigatorProseFromUnknown } = await import("./package-contracts/navigator-output.js");
+          const proseParts = [];
+          for (const payload of outcome.payloads ?? []) {
+            const prose = navigatorProseFromUnknown(payload);
+            if (prose !== void 0) proseParts.push(prose);
+          }
+          if (proseParts.length === 0) return;
+          if (disposed) return;
+          await tool.execute(
+            "navigator-public-prepare",
+            { prose: proseParts.join("\n\n") },
+            void 0,
+            void 0,
+            context
+          );
+        } catch (error) {
+          if (disposed) return;
+          if (error instanceof NavigatorUnavailableError) throw error;
+          const fact = navigatorProviderFailureFromError(error);
+          providerFailure = fact ?? { source: "transport", cause: "unknown" };
+          throw navigatorUnavailableError(providerFailure.source, error, providerFailure.cause);
         }
       },
       providerFailure: () => providerFailure,
@@ -197,8 +198,6 @@ function createNativeNavigatorSessionFactory(deps) {
       recordPointer: () => sessionManager.getSessionDir(),
       dispose: async () => {
         disposed = true;
-        const pending = inFlightPrompt;
-        if (pending !== void 0) await pending.catch(() => void 0);
       }
     };
   };

package/package.json

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

package/src/host-native-method.ts

@@ -1,5 +1,5 @@
-/** #922 host-native packaged method delivery. */
-import { lstat, mkdir, readlink, realpath, symlink } from "node:fs/promises";
+/** #922 / #980 host-native packaged method delivery. */
+import { access, lstat, mkdir, readdir, readFile, readlink, realpath, symlink } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
 import type { MethodBinding } from "./host-contracts.ts";
 
@@ -41,26 +41,144 @@ export function applyCodexSkillInvocation(methods: readonly MethodBinding[], pro
   );
 }
 
+const isEnoent = (error: unknown): boolean =>
+  (error as NodeJS.ErrnoException).code === "ENOENT";
+
+/** Packaged method skill directory names (child has SKILL.md). I/O errors propagate. */
+async function packagedMethodSkillNames(packagedMethodsRealpath: string): Promise<readonly string[]> {
+  const entries = await readdir(packagedMethodsRealpath, { withFileTypes: true });
+  const names: string[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    try {
+      await access(join(packagedMethodsRealpath, entry.name, "SKILL.md"));
+    } catch (error) {
+      if (isEnoent(error)) continue;
+      throw error;
+    }
+    names.push(entry.name);
+  }
+  return names;
+}
+
+/**
+ * Byte map of every regular file under a packaged skill directory
+ * (relative path → bytes). Undefined when SKILL.md is missing. Other I/O
+ * errors propagate. Integrity only — no free-text parsing of Skill prose.
+ */
+async function packagedSkillFileBytes(
+  skillDir: string,
+): Promise<ReadonlyMap<string, Buffer> | undefined> {
+  try {
+    await access(join(skillDir, "SKILL.md"));
+  } catch (error) {
+    if (isEnoent(error)) return undefined;
+    throw error;
+  }
+  const files = new Map<string, Buffer>();
+  async function walk(dir: string, prefix: string): Promise<void> {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const rel = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(full, rel);
+        continue;
+      }
+      if (entry.isFile()) {
+        files.set(rel, await readFile(full));
+      }
+    }
+  }
+  await walk(skillDir, "");
+  return files;
+}
+
+/**
+ * True when catalog skill already carries identical bytes for every required
+ * packaged relative path. Only those paths are read — extra catalog files are
+ * out of scope for the compatibility proof.
+ */
+async function catalogPublishesPackagedSkill(
+  catalogSkillDir: string,
+  required: ReadonlyMap<string, Buffer>,
+): Promise<boolean> {
+  for (const [rel, bytes] of required) {
+    let other: Buffer;
+    try {
+      other = await readFile(join(catalogSkillDir, rel));
+    } catch (error) {
+      if (isEnoent(error)) return false;
+      throw error;
+    }
+    if (!bytes.equals(other)) return false;
+  }
+  return true;
+}
+
+/**
+ * Existing project catalog is usable when it already publishes every packaged
+ * method skill with identical file bytes. Path identity is sufficient but not
+ * required (#980): a worktree catalog at another realpath that still carries
+ * the packaged method bytes must stay put. Name-only / foreign / stale content
+ * remains a true conflict. Incomplete, broken, or non-symlink entries too.
+ *
+ * Caller must only invoke this when `link` is known present; link-missing
+ * ENOENT is classified solely by the existence probe in
+ * `installWorkspaceMethodSkills`, not here.
+ */
+async function isCompatibleMethodCatalog(
+  link: string,
+  packagedMethodsRealpath: string,
+): Promise<boolean> {
+  const stat = await lstat(link);
+  if (!stat.isSymbolicLink()) return false;
+  let resolved: string;
+  try {
+    resolved = await realpath(link);
+  } catch (error) {
+    if (isEnoent(error)) return false;
+    throw error;
+  }
+  if (resolved === packagedMethodsRealpath) return true;
+  const names = await packagedMethodSkillNames(packagedMethodsRealpath);
+  if (names.length === 0) return false;
+  for (const name of names) {
+    const required = await packagedSkillFileBytes(join(packagedMethodsRealpath, name));
+    if (required === undefined) return false;
+    if (!(await catalogPublishesPackagedSkill(join(resolved, name), required))) return false;
+  }
+  return true;
+}
+
 /** Install the documented project Skill catalog once and leave it in place. */
 export async function installWorkspaceMethodSkills(cwd: string, packageRoot: string): Promise<void> {
   const target = await realpath(packagedMethodsDir(packageRoot));
   const link = join(cwd, ".agents", "skills");
+
+  // Existence probe only — this seam alone classifies link-missing ENOENT.
+  let present: boolean;
   try {
-    const stat = await lstat(link);
-    if (!stat.isSymbolicLink() || await realpath(link) !== target) {
-      const detail = stat.isSymbolicLink() ? `symlink to ${await readlink(link)}` : "non-symlink entry";
-      throw new Error(`workspace method catalog conflict at ${link}: ${detail}`);
-    }
-    return;
+    await lstat(link);
+    present = true;
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    if (!isEnoent(error)) throw error;
+    present = false;
   }
+
+  if (present) {
+    if (await isCompatibleMethodCatalog(link, target)) return;
+    const stat = await lstat(link);
+    const detail = stat.isSymbolicLink() ? `symlink to ${await readlink(link)}` : "non-symlink entry";
+    throw new Error(`workspace method catalog conflict at ${link}: ${detail}`);
+  }
+
   await mkdir(dirname(link), { recursive: true });
   try {
     await symlink(target, link);
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-    if ((await realpath(link).catch(() => "")) !== target) {
+    if (!(await isCompatibleMethodCatalog(link, target))) {
       throw new Error(`workspace method catalog conflict at ${link}`);
     }
   }

package/src/navigator-attendance.ts

@@ -302,9 +302,22 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
   let preparationFailure: unknown;
   let routePlaybookReadFailure: string | undefined;
   let disposed = false;
+  /** In-flight session teardown; repeat dispose returns the same promise (#959 mutation proof). */
+  let closing: Promise<void> | undefined;
+  // Shared attendance seam owns nested summon cancel (ADR 0018 / #959).
+  // Role session factory only forwards HostContext.signal — never its own controller.
+  const nestCancel = new AbortController();
   /** One-shot live-help warm; consumed by the next prepare so later prepares reread live help. */
   let warmedHelp: Promise<Array<{ role: NavigatorTargetRole; help: string }>> | undefined;
 
+  const sessionHostContext = (): HostContext => {
+    const parentSignal = options.context.signal;
+    const signal = parentSignal === undefined
+      ? nestCancel.signal
+      : AbortSignal.any([nestCancel.signal, parentSignal]);
+    return { ...options.context, signal };
+  };
+
   const loadLiveHelp = async (): Promise<Array<{ role: NavigatorTargetRole; help: string }>> => {
     try {
       return await Promise.all(
@@ -408,7 +421,7 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
         let created: NavigatorPreparationSession;
         try {
           created = await options.createSession({
-            context: options.context,
+            context: sessionHostContext(),
             subject: subjectKey,
             ...(options.modelSettingPath === undefined ? {} : { modelSettingPath: options.modelSettingPath }),
             tool,
@@ -660,12 +673,25 @@ export function createNavigatorAttendance(options: NavigatorAttendanceOptions) {
     },
     dispose(): void | Promise<void> {
       disposed = true;
+      // Abort nested public summon via shared signal; callers may still await session
+      // close. Parent grace/shutdown must choose not to await (#959 reopen).
+      if (!nestCancel.signal.aborted) {
+        nestCancel.abort(navigatorUnavailableError(
+          "session",
+          new Error("Navigator attendance was disposed"),
+        ));
+      }
       // Leave sessionReady so an in-flight createSession observes disposed and drains exactly once.
       // Late settleOnce completion observes disposed and skips onEvent.
-      const current = session;
-      session = undefined;
       activeInvocationId = undefined;
-      return current?.dispose();
+      if (closing === undefined) {
+        const current = session;
+        session = undefined;
+        // Preserve rejection for non-blocking recordDisposeFailure; resolve void on success.
+        closing = Promise.resolve(current?.dispose()).then(() => undefined);
+      }
+      // Same in-flight teardown on repeat dispose — awaiting here re-blocks the parent court.
+      return closing;
     },
   };
 

package/src/navigator-public-session.ts

@@ -98,6 +98,8 @@ export type NavigatorPublicSummon = (options: {
   readonly cwd: string;
   readonly home?: string;
   readonly resumeRunId?: string;
+  /** Shared-lifecycle cancel forwarded from HostContext.signal (#675 / #959). */
+  readonly signal?: AbortSignal;
 }) => Promise<PublicSummonResult>;
 
 export function createNativeNavigatorSessionFactory(deps?: {
@@ -128,7 +130,6 @@ export function createNativeNavigatorSessionFactory(deps?: {
     let providerFailure: NavigatorProviderFailureFact | undefined;
     let noReceipt: NoReceiptLifecycleFacts | undefined;
     let disposed = false;
-    let inFlightPrompt: Promise<unknown> | undefined;
     /** In-factory host run id for CLI resume; durable pointer also lives on the nest. */
     let hostRunId = readNavigatorHostRunPointer(sessionManager.getEntries() as readonly unknown[]);
 
@@ -145,16 +146,21 @@ export function createNativeNavigatorSessionFactory(deps?: {
         }
         providerFailure = undefined;
         noReceipt = undefined;
-        const run = (async () => {
         try {
           const summonHome = await resolveNavigatorLedgerHome(context);
+          // Admission after every await: dispose during preflight must not start summon
+          // (ADR 0018 / #959 — legal HostContext may omit signal).
+          if (disposed) return;
           const resumeRunId = hostRunId;
 
+          // Call contract only: forward shared-lifecycle signal; do not own AbortController here
+          // (ADR 0018 / #959 — cancel ownership stays on the attendance/envelope seam).
           const baseSummon = {
             role: "navigator" as const,
             argv: [text] as const,
             cwd: context.cwd,
             ...(summonHome === undefined ? {} : { home: summonHome }),
+            ...(context.signal === undefined ? {} : { signal: context.signal }),
           };
 
           // Prefer host CLI resume so prior advice stays on the host session.
@@ -162,14 +168,23 @@ export function createNativeNavigatorSessionFactory(deps?: {
           const resumable = deps?.hostRunResumable ?? navigatorHostRunResumable;
           let summoned: PublicSummonResult;
           if (resumeRunId === undefined || summonHome === undefined) {
+            if (disposed) return;
             summoned = await summon(baseSummon);
-          } else if (await resumable(summonHome, resumeRunId)) {
-            summoned = await summon({ ...baseSummon, resumeRunId });
           } else {
-            hostRunId = undefined;
-            summoned = await summon(baseSummon);
+            const canResume = await resumable(summonHome, resumeRunId);
+            if (disposed) return;
+            if (canResume) {
+              summoned = await summon({ ...baseSummon, resumeRunId });
+            } else {
+              hostRunId = undefined;
+              summoned = await summon(baseSummon);
+            }
           }
 
+          // Dispose won the race (with or without HostContext.signal): no late pointer/prepare.
+          // Cancel ownership stays on attendance/envelope; this only closes side effects (#959).
+          if (disposed) return;
+
           const outcome = summoned.terminal?.roleOutcome;
           if (outcome === undefined) {
             const detail = summoned.stderr?.trim() || `exit ${summoned.exitCode}`;
@@ -222,6 +237,7 @@ export function createNativeNavigatorSessionFactory(deps?: {
             if (prose !== undefined) proseParts.push(prose);
           }
           if (proseParts.length === 0) return;
+          if (disposed) return;
           await tool.execute(
             "navigator-public-prepare",
             { prose: proseParts.join("\n\n") },
@@ -230,19 +246,14 @@ export function createNativeNavigatorSessionFactory(deps?: {
             context as never,
           );
         } catch (error) {
+          // Closed session: drain late nest errors without providerFailure side effects.
+          if (disposed) return;
           if (error instanceof NavigatorUnavailableError) throw error;
           const fact = navigatorProviderFailureFromError(error);
           // Catch path is the public-summon seam (source transport); untyped cause stays unknown.
           providerFailure = fact ?? { source: "transport", cause: "unknown" };
           throw navigatorUnavailableError(providerFailure.source, error, providerFailure.cause);
         }
-        })();
-        inFlightPrompt = run;
-        try {
-          await run;
-        } finally {
-          if (inFlightPrompt === run) inFlightPrompt = undefined;
-        }
       },
       providerFailure: () => providerFailure,
       noReceipt: () => noReceipt,
@@ -276,9 +287,9 @@ export function createNativeNavigatorSessionFactory(deps?: {
       getThinkingLevel: () => thinkingLevel,
       recordPointer: () => sessionManager.getSessionDir(),
       dispose: async () => {
+        // Marker only — nested cancel and non-blocking teardown are owned by
+        // navigator-attendance / role-runtime (ADR 0018 / #959).
         disposed = true;
-        const pending = inFlightPrompt;
-        if (pending !== undefined) await pending.catch(() => undefined);
       },
     };
   };

package/src/role-runtime.ts

@@ -1417,6 +1417,43 @@ export function createRoleRuntimeExtension(
     // Public-run fetch observation (in-process-session statusAwareFetch face).
     let priorFetch: typeof globalThis.fetch | undefined;
     let fetchWrapped = false;
+    /** Envelope-owned: abort/teardown attendance without re-blocking the parent court (#959). */
+    const disposeNavigatorAttendanceNonBlocking = (
+      attendance: NavigatorAttendanceDependency | undefined,
+    ): void => {
+      if (attendance === undefined) return;
+      const recordDisposeFailure = (error: unknown): void => {
+        const diagnostic = error instanceof Error ? error.message : String(error);
+        try {
+          sitianReport({
+            level: "event",
+            kind: "navigator-dispose-failure",
+            cwd: navigatorCwd,
+            sessionParent: navigatorSessionParent,
+            payload: { diagnostic },
+            source: "role-runtime",
+          });
+        } catch (recordError) {
+          try {
+            envelopeHost.appendEntry?.("ak-navigator-dispose-failure", {
+              diagnostic,
+              recordFailure: recordError instanceof Error ? recordError.message : String(recordError),
+            });
+          } catch {
+            // Failure already diagnosed; recording must not create unhandled rejection (#959).
+          }
+        }
+      };
+      // Evaluate dispose inside try: Promise.resolve(dispose()) throws sync before .then attaches.
+      let pending: void | Promise<void>;
+      try {
+        pending = attendance.dispose();
+      } catch (error) {
+        recordDisposeFailure(error);
+        return;
+      }
+      void Promise.resolve(pending).then(undefined, recordDisposeFailure);
+    };
     const settleNavigatorProjection = async (settlement: NavigatorSettlement | undefined) => {
       const attendance = navigatorAttendance;
       if (settlement === undefined || attendance === undefined) return;
@@ -1455,28 +1492,7 @@ export function createRoleRuntimeExtension(
           pendingNavigatorPresentation = { event, report };
         }
         // 过时不候: do not await sidecar teardown — parent court must close.
-        // Dispose failure is recorded, not washed; it must not re-block the court.
-        void Promise.resolve(attendance.dispose()).then(
-          undefined,
-          (error) => {
-            const diagnostic = error instanceof Error ? error.message : String(error);
-            try {
-              sitianReport({
-                level: "event",
-                kind: "navigator-dispose-failure",
-                cwd: navigatorCwd,
-                sessionParent: navigatorSessionParent,
-                payload: { diagnostic },
-                source: "role-runtime",
-              });
-            } catch (recordError) {
-              envelopeHost.appendEntry?.("ak-navigator-dispose-failure", {
-                diagnostic,
-                recordFailure: recordError instanceof Error ? recordError.message : String(recordError),
-              });
-            }
-          },
-        );
+        disposeNavigatorAttendanceNonBlocking(attendance);
       })();
       pendingNavigatorSettlement = pending;
       await pending;
@@ -1833,9 +1849,12 @@ export function createRoleRuntimeExtension(
           // Teardown must not mask the original role failure cause.
         }
       }
-      await navigatorAttendance?.dispose();
+      // Same non-blocking dispose as post-role grace: awaiting here re-blocked the
+      // parent court for 43–270s after unavailable was already projected (#959 reopen).
+      const attendanceToDispose = navigatorAttendance;
       navigatorAttendance = undefined;
       pendingNavigatorSettlement = undefined;
+      disposeNavigatorAttendanceNonBlocking(attendanceToDispose);
       pendingInfrastructureFailures.clear();
       pendingSubmissionNonPassByToolCallId.clear();
       observationFace.reset();