@nifrajs/coding-agent 3.5.0 → 4.0.0

package/src/session-migration.ts

@@ -1,5 +1,6 @@
 import { access, mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises"
 import { basename, join, resolve } from "node:path"
+import { sessionFileStem } from "./sessions.ts"
 
 /** Version of the evidence-only legacy session file format. */
 export const SESSION_EVIDENCE_VERSION = 1 as const
@@ -160,7 +161,7 @@ export async function migrateLegacySession(
   const lines = records.map((record) => JSON.stringify(record))
   const content = lines.length === 0 ? "" : `${lines.join("\n")}\n`
   const digest = await sha256Hex(content)
-  const targetFile = join(targetRoot, `${sessionId}.jsonl`)
+  const targetFile = join(targetRoot, `${sessionFileStem(sessionId)}.jsonl`)
   await commitTarget(targetRoot, targetFile, content, options.signal)
   // Re-read the committed target and validate every line before the caller treats this as active.
   const committed = await readEvidenceTarget(targetFile, sessionId)
@@ -221,7 +222,7 @@ async function readLegacyEntries(
   sessionId: string,
   maxSourceBytes: number,
 ): Promise<readonly LegacyEntry[]> {
-  const path = join(sourceRoot, `${sessionId}.jsonl`)
+  const path = join(sourceRoot, `${sessionFileStem(sessionId)}.jsonl`)
   let text: string
   try {
     const bytes = await readFile(path)

package/src/sessions.ts

@@ -132,7 +132,7 @@ export class FileSessionStore implements SessionStore {
   async checkpoint(sessionId: string, payload: unknown): Promise<void> {
     validateToken(sessionId, "sessionId")
     await this.withSessionLock(sessionId, async () => {
-      const target = join(this.root, `${sessionId}.checkpoint.json`)
+      const target = join(this.root, `${sessionFileStem(sessionId)}.checkpoint.json`)
       const temporary = `${target}.${process.pid}.${crypto.randomUUID()}.tmp`
       await mkdir(dirname(target), { recursive: true })
       const content = JSON.stringify({
@@ -178,7 +178,7 @@ export class FileSessionStore implements SessionStore {
   }
 
   private pathFor(sessionId: string): string {
-    return join(this.root, `${sessionId}.jsonl`)
+    return join(this.root, `${sessionFileStem(sessionId)}.jsonl`)
   }
 
   private async nextSequence(sessionId: string): Promise<number> {
@@ -418,6 +418,22 @@ async function rejectSessionSymlink(path: string): Promise<void> {
   }
 }
 
+// Device names Windows reserves even with an extension after them: `nul.jsonl` is the NUL device.
+const WINDOWS_DEVICE = /^(?:con|prn|aux|nul|com[0-9]|lpt[0-9])(?:\.|$)/i
+
+/**
+ * The file name stem for a session id. On Windows a `:` in a file name addresses an NTFS alternate
+ * data stream, so it is written as `%3A` there, and an id that starts with a reserved device name has
+ * its first character percent-encoded. `%` is outside the id grammar, so no two ids collide.
+ */
+export function sessionFileStem(sessionId: string, platform = process.platform): string {
+  if (platform !== "win32") return sessionId
+  const stem = sessionId.replaceAll(":", "%3A")
+  return WINDOWS_DEVICE.test(stem)
+    ? `%${stem.charCodeAt(0).toString(16).toUpperCase()}${stem.slice(1)}`
+    : stem
+}
+
 function validateToken(value: string, name: string): void {
   if (!/^[a-zA-Z0-9._:-]{1,128}$/.test(value))
     throw new TypeError(`session store: ${name} must be a bounded token`)

package/src/subagents.ts

@@ -1,4 +1,5 @@
-import { relative, resolve, sep } from "node:path"
+import { realpath } from "node:fs/promises"
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path"
 
 export interface SubagentSpec {
   readonly id: string
@@ -28,6 +29,10 @@ export interface SubagentExecutor {
 
 export interface SubagentWorkspaceLease {
   readonly cwd: string
+  /**
+   * Runs once the executor has settled. A run that times out or is cancelled returns at once, but
+   * its workspace stays until the executor finishes, so a child never loses its cwd mid-run.
+   */
   readonly cleanup?: () => void | PromiseLike<void>
 }
 
@@ -41,6 +46,22 @@ export interface SubagentWorkspacePolicy {
   ) => SubagentWorkspaceLease | PromiseLike<SubagentWorkspaceLease>
 }
 
+/** A run that returned while its executor kept running, having ignored its abort signal. */
+export interface SubagentAbandonment {
+  readonly spec: SubagentSpec
+  readonly reason: "timeout" | "cancelled"
+  /** The workspace the executor was given; undefined when it had none. */
+  readonly cwd: string | undefined
+  /** Settles once the executor does; its workspace lease is cleaned up after that. */
+  readonly settled: Promise<void>
+}
+
+/** Abandoned executors still running. Runners sharing one ledger are counted, and bounded by
+ * `maxAbandoned`, together. */
+export interface SubagentAbandonmentLedger {
+  abandoned: number
+}
+
 export interface SubagentRunnerOptions {
   readonly maxChildren?: number
   readonly maxDepth?: number
@@ -48,6 +69,25 @@ export interface SubagentRunnerOptions {
   readonly signal?: AbortSignal
   readonly allowedCapabilities?: readonly string[]
   readonly workspace?: SubagentWorkspacePolicy
+  /**
+   * Called when a run returns while its executor keeps running: it timed out or was cancelled and
+   * ignored its abort signal. Use it to stop the executor another way, such as ending its process.
+   */
+  readonly onAbandoned?: (abandonment: SubagentAbandonment) => void
+  /** Refuse new children while this many abandoned executors are still running. Default: no bound. */
+  readonly maxAbandoned?: number
+  /** Where abandoned executors are counted. Default: a ledger of this runner's own. */
+  readonly abandonment?: SubagentAbandonmentLedger
+}
+
+/** `work`'s outcome, or `stopped()` as soon as `signal` aborts, even when `work` ignores it. */
+function untilAborted<T>(work: Promise<T>, signal: AbortSignal, stopped: () => Error): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const stop = (): void => reject(stopped())
+    if (signal.aborted) return stop()
+    signal.addEventListener("abort", stop, { once: true })
+    work.then(resolve, reject).finally(() => signal.removeEventListener("abort", stop))
+  })
 }
 
 /** Explicitly bounded child execution. Recursive fan-out is impossible without a caller budget. */
@@ -58,6 +98,7 @@ export class BoundedSubagentRunner {
   > &
     SubagentRunnerOptions
   private children = 0
+  private readonly ledger: SubagentAbandonmentLedger
 
   constructor(executor: SubagentExecutor, options: SubagentRunnerOptions = {}) {
     this.executor = executor
@@ -67,15 +108,37 @@ export class BoundedSubagentRunner {
       maxDepth: options.maxDepth ?? 2,
       depth: options.depth ?? 0,
     }
-    if (this.options.maxChildren < 1 || this.options.maxDepth < 0 || this.options.depth < 0)
+    this.ledger = options.abandonment ?? { abandoned: 0 }
+    if (
+      this.options.maxChildren < 1 ||
+      this.options.maxDepth < 0 ||
+      this.options.depth < 0 ||
+      (options.maxAbandoned !== undefined &&
+        (!Number.isSafeInteger(options.maxAbandoned) || options.maxAbandoned < 0))
+    )
       throw new RangeError(
         "subagents: limits must be non-negative and maxChildren must be positive",
       )
   }
 
+  /** Executors this runner's ledger holds as abandoned and still running. */
+  get abandoned(): number {
+    return this.ledger.abandoned
+  }
+
   async run(spec: SubagentSpec): Promise<SubagentResult> {
     if (!/^[a-z][a-z0-9._:-]{0,63}$/.test(spec.id))
       return { id: spec.id, role: spec.role, ok: false, error: "invalid subagent id" }
+    if (
+      this.options.maxAbandoned !== undefined &&
+      this.ledger.abandoned >= this.options.maxAbandoned
+    )
+      return {
+        id: spec.id,
+        role: spec.role,
+        ok: false,
+        error: "subagent abandoned-executor limit reached",
+      }
     if (++this.children > this.options.maxChildren)
       return { id: spec.id, role: spec.role, ok: false, error: "subagent child limit exceeded" }
     if (this.options.depth > this.options.maxDepth)
@@ -110,13 +173,23 @@ export class BoundedSubagentRunner {
       }
     const controller = new AbortController()
     const onAbort = (): void => controller.abort(this.options.signal?.reason)
-    this.options.signal?.addEventListener("abort", onAbort, { once: true })
+    if (this.options.signal?.aborted === true) onAbort()
+    else this.options.signal?.addEventListener("abort", onAbort, { once: true })
+    let timedOut = false
     const timeout =
       spec.timeoutMs === undefined
         ? undefined
-        : setTimeout(() => controller.abort("timeout"), spec.timeoutMs)
+        : setTimeout(() => {
+            timedOut = true
+            controller.abort("timeout")
+          }, spec.timeoutMs)
+    const stopped = (): Error => new Error(timedOut ? "subagent timed out" : "subagent cancelled")
     let workspace: SubagentWorkspaceLease | undefined
+    let cwd: string | undefined
+    let executorDone: Promise<void> | undefined
+    let executorSettled = false
     try {
+      if (controller.signal.aborted) throw stopped()
       const requestedCwd =
         spec.cwd === undefined
           ? this.options.workspace?.root
@@ -124,7 +197,8 @@ export class BoundedSubagentRunner {
             ? resolve(spec.cwd)
             : resolve(this.options.workspace.root, spec.cwd)
       if (requestedCwd !== undefined && this.options.workspace !== undefined) {
-        if (!within(this.options.workspace.root, requestedCwd))
+        const requested = await physicalPath(requestedCwd)
+        if (!(await within(this.options.workspace.root, requested)))
           return {
             id: spec.id,
             role: spec.role,
@@ -132,7 +206,7 @@ export class BoundedSubagentRunner {
             error: "subagent workspace escapes policy root",
           }
         const allowedRoots = this.options.workspace.allowedRoots ?? [this.options.workspace.root]
-        if (!allowedRoots.some((root) => within(root, requestedCwd)))
+        if (!(await withinAny(allowedRoots, requested)))
           return {
             id: spec.id,
             role: spec.role,
@@ -145,11 +219,15 @@ export class BoundedSubagentRunner {
       } else if (requestedCwd !== undefined) {
         workspace = { cwd: requestedCwd }
       }
+      cwd = workspace?.cwd
       if (workspace !== undefined && this.options.workspace !== undefined) {
+        // The executor gets the path that was checked, with its links already resolved, so a link
+        // swapped after the check cannot move it out of the policy root.
+        cwd = await physicalPath(workspace.cwd)
         const allowedRoots = this.options.workspace.allowedRoots ?? [this.options.workspace.root]
         if (
-          !within(this.options.workspace.root, workspace.cwd) ||
-          !allowedRoots.some((root) => within(root, workspace!.cwd))
+          !(await within(this.options.workspace.root, cwd)) ||
+          !(await withinAny(allowedRoots, cwd))
         )
           return {
             id: spec.id,
@@ -158,11 +236,20 @@ export class BoundedSubagentRunner {
             error: "isolated worktree escapes workspace policy",
           }
       }
-      const output = await this.executor.run({
-        spec,
-        signal: controller.signal,
-        ...(workspace === undefined ? {} : { cwd: workspace.cwd }),
-      })
+      if (controller.signal.aborted) throw stopped()
+      const work = Promise.resolve().then(() =>
+        this.executor.run({
+          spec,
+          signal: controller.signal,
+          ...(cwd === undefined ? {} : { cwd }),
+        }),
+      )
+      // Registered before untilAborted's reaction, so a settled executor is seen as settled below.
+      const settle = (): void => {
+        executorSettled = true
+      }
+      executorDone = work.then(settle, settle)
+      const output = await untilAborted(work, controller.signal, stopped)
       return { id: spec.id, role: spec.role, ok: true, output }
     } catch (error) {
       return {
@@ -172,9 +259,29 @@ export class BoundedSubagentRunner {
         error: error instanceof Error ? error.message : String(error),
       }
     } finally {
-      await workspace?.cleanup?.()
       if (timeout !== undefined) clearTimeout(timeout)
       this.options.signal?.removeEventListener("abort", onAbort)
+      const cleanup = workspace?.cleanup
+      // An executor that honours the abort settles within a few ticks; give it one turn before
+      // calling it abandoned.
+      if (executorDone !== undefined && !executorSettled)
+        await Promise.race([executorDone, new Promise((resolve) => setTimeout(resolve, 0))])
+      if (executorDone !== undefined && !executorSettled) {
+        // The executor is counted until it settles, and may still be writing to its workspace, so
+        // the release waits for it too.
+        const ledger = this.ledger
+        ledger.abandoned++
+        const settled = executorDone.then(() => {
+          ledger.abandoned--
+        })
+        if (cleanup !== undefined) settled.then(() => cleanup()).catch(() => {})
+        this.options.onAbandoned?.({
+          spec,
+          reason: timedOut ? "timeout" : "cancelled",
+          cwd,
+          settled,
+        })
+      } else if (cleanup !== undefined) await cleanup()
     }
   }
 
@@ -201,10 +308,33 @@ export class BoundedSubagentRunner {
   }
 }
 
-function within(root: string, candidate: string): boolean {
-  const relativePath = relative(resolve(root), resolve(candidate))
+/** Whether `physical`, a path whose links are already resolved, lies inside the physical root, so a
+ * symlink inside the root cannot lead out of it. */
+async function within(root: string, physical: string): Promise<boolean> {
+  const relativePath = relative(await physicalPath(root), physical)
   return (
     relativePath === "" ||
-    (relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !relativePath.startsWith("/"))
+    (relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath))
   )
 }
+
+async function withinAny(roots: readonly string[], physical: string): Promise<boolean> {
+  for (const root of roots) if (await within(root, physical)) return true
+  return false
+}
+
+/** The path with its existing part's symlinks resolved; a part not created yet is kept as written. */
+async function physicalPath(path: string): Promise<string> {
+  const missing: string[] = []
+  let existing = resolve(path)
+  for (;;) {
+    try {
+      return join(await realpath(existing), ...missing)
+    } catch {
+      const parent = dirname(existing)
+      if (parent === existing) return resolve(path)
+      missing.unshift(basename(existing))
+      existing = parent
+    }
+  }
+}

package/src/verification.ts

@@ -161,12 +161,16 @@ export async function runNifraReview(options: ReviewOptions): Promise<ReviewExec
   }
 }
 
-/** Run an existing Nifra gate without importing the large framework CLI into the agent runtime. */
+/**
+ * Run an existing Nifra gate without importing the large framework CLI into the agent runtime.
+ * `check` and `assure` are `nifra` commands; `test` is the project's own suite, run with `bun test`
+ * by the Bun this agent runs on.
+ */
 export async function runNifraVerification(
   name: "check" | "assure" | "test",
   options: VerificationOptions,
 ): Promise<VerificationResult> {
-  const command = options.command ?? "nifra"
+  const command = options.command ?? (name === "test" ? process.execPath : "nifra")
   const commandArgs = options.commandArgs ?? []
   const args = name === "test" ? ["test"] : [name, "--json"]
   const proc = Bun.spawn([command, ...commandArgs, ...args], {

package/src/workflows.ts

@@ -235,16 +235,24 @@ export class WorkflowRunner {
       throw new RangeError("workflow: maxConcurrency must be positive")
     const outputs: unknown[] = new Array(steps.length)
     let next = 0
+    // The first failure starts no further step, and the group settles only once the steps already
+    // running have, so nothing runs on after the workflow reports its failure.
+    let failure: { readonly error: unknown } | undefined
     const worker = async (): Promise<void> => {
-      for (;;) {
+      while (failure === undefined) {
         const index = next++
         if (index >= steps.length) return
-        outputs[index] = await this.execute(steps[index]!, depth + 1)
+        try {
+          outputs[index] = await this.execute(steps[index]!, depth + 1)
+        } catch (error) {
+          failure ??= { error }
+        }
       }
     }
     await Promise.all(
       Array.from({ length: Math.min(maxConcurrency, steps.length) }, () => worker()),
     )
+    if (failure !== undefined) throw failure.error
     return outputs
   }