@naxodev/apnea 0.2.0 → 0.2.1

package/extension/workflows/start.ts

@@ -47,7 +47,7 @@ export const startWorkflow = (
       let pendingStatus: string = "none"
       if (pending) {
         const absPath = pending.startsWith("/") ? pending : `${root}/${pending}`
-        const present = yield* fs.exists(absPath)
+        const present = yield* fs.projectPathExists(root, absPath)
         pendingStatus = present ? "artifact_exists" : "artifact_missing"
       }
       return ok(
@@ -59,7 +59,7 @@ export const startWorkflow = (
             pendingStatus === "artifact_exists"
               ? "call workflow_wait to ingest pending artifact"
               : pendingStatus === "artifact_missing"
-                ? "offer re-dispatch same round via dispatch_role"
+                ? "offer same-round dispatch_role redeliver=true after proving the prior delivery is dead"
                 : "inspect workflow_status and continue legal next step",
         },
         nextAfter(existing.step),
@@ -100,7 +100,7 @@ export const startWorkflow = (
     }
 
     const state: RunState = {
-      version: 1,
+      version: 2,
       slug,
       step: "planning",
       phase_index: 1,
@@ -112,6 +112,7 @@ export const startWorkflow = (
       last_error: null,
       pending_artifact: null,
       pending_role: null,
+      pending_delivery: null,
       pending_pane_id: null,
       pending_pane_label: null,
       pending_started_at: null,
@@ -124,7 +125,8 @@ export const startWorkflow = (
       reviewer_tree_fingerprint: null,
       current_phase_package: null,
       current_code_review: null,
-      phase_package_rework: false,
+      required_rework: null,
+      pending_commit: null,
     }
     // The literal above assigns the ladder's fields; this re-asserts them
     // through the shared helper so a rung added there cannot be missed here.

package/extension/workflows/status.ts

@@ -1,6 +1,6 @@
 import { Effect, Result } from "effect"
 import { LEGAL_TOOLS, nextAfter } from "../domain/state-machine.ts"
-import type { StateCorrupt } from "../errors.ts"
+import type { AppError } from "../errors.ts"
 import { ok, type ToolResult } from "../result.ts"
 import { Config } from "../services/config.ts"
 import { RunStore } from "../services/run-store.ts"
@@ -12,7 +12,7 @@ import { Vcs } from "../services/vcs.ts"
  */
 export const statusWorkflow = (
   root: string,
-): Effect.Effect<ToolResult, StateCorrupt, RunStore | Config | Vcs> =>
+): Effect.Effect<ToolResult, AppError, RunStore | Config | Vcs> =>
   Effect.gen(function* () {
     const store = yield* RunStore
     const config = yield* Config

package/extension/workflows/wait.ts

@@ -1,7 +1,7 @@
 import { Clock, Effect, Exit, Option, Result } from "effect"
 import { resetRecoveryLadder } from "../domain/recovery.ts"
 import { inferKind } from "../domain/artifact-kind.ts"
-import { timeoutMsForKind } from "../domain/timeouts.ts"
+import { deadlineAfter, timeoutMsForKind } from "../domain/timeouts.ts"
 import {
   asVerdict,
   isCompleteArtifact,
@@ -9,11 +9,7 @@ import {
 } from "../domain/frontmatter.ts"
 import { looksLikeShellOnly, shellJoin } from "../domain/herdr.ts"
 import { abs, rel } from "../domain/paths.ts"
-import {
-  nextAfter,
-  stepAfterArtifact,
-  toolAllowed,
-} from "../domain/state-machine.ts"
+import { nextAfter, toolAllowed } from "../domain/state-machine.ts"
 import {
   ArtifactInvalid,
   GateRefused,
@@ -24,12 +20,16 @@ import {
 } from "../errors.ts"
 import type { FrontMatter } from "../domain/types.ts"
 import { ok, type ToolResult } from "../result.ts"
-import { decodeFrontMatterResult } from "../schema/frontmatter.ts"
+import {
+  validateArtifactCompletion,
+  type AcceptedArtifactCompletion,
+} from "../schema/frontmatter.ts"
 import { Config } from "../services/config.ts"
 import { FileSystem } from "../services/file-system.ts"
 import { Herdr, paneReadRecentArgs } from "../services/herdr.ts"
 import { RunStore } from "../services/run-store.ts"
 import { Vcs } from "../services/vcs.ts"
+import type { OperationHooks } from "../operation-hooks.ts"
 
 export type WaitParams = {
   poll_ms?: number
@@ -151,12 +151,7 @@ export const MAX_AUTO_POLL_MS =
 export const fitsHostShell = (pollMs: number): boolean =>
   defaultBudgetFor(pollMs) < HOST_SHELL_TIMEOUT_MS
 
-export type WaitHooks = {
-  signal?: AbortSignal
-  onUpdate?: (partial: {
-    content: Array<{ type: "text"; text: string }>
-  }) => void
-}
+export type WaitHooks = OperationHooks
 
 /**
  * Async wait — polls via `Clock` + `Effect.sleep` so Pi stays responsive and
@@ -202,10 +197,10 @@ export const waitWorkflow = (
     const cfg = yield* config.load(root)
 
     const poll = params.poll_ms ?? 2000
-    if (!Number.isFinite(poll) || poll < MIN_POLL_MS) {
+    if (!Number.isSafeInteger(poll) || poll < MIN_POLL_MS) {
       return yield* new GateRefused({
         gate: "poll_interval",
-        message: `poll_ms must be a finite number >= ${MIN_POLL_MS}; got ${poll}. Every poll spawns two herdr subprocesses, so a tiny interval is a busy-spin, not a faster wait.`,
+        message: `poll_ms must be a safe integer >= ${MIN_POLL_MS}; got ${poll}. Every poll spawns two herdr subprocesses, so a tiny interval is a busy-spin, not a faster wait.`,
       })
     }
     // Refuse to PICK a budget that a default host shell would kill; still
@@ -232,10 +227,10 @@ export const waitWorkflow = (
     // NaN, and the call blocks until the role's deadline instead of
     // returning exit 3. The CLI is protected by `parseNumFlag`; a Pi tool
     // call reaches `run` through a raw cast with no runtime coercion.
-    if (!Number.isFinite(budget)) {
+    if (!Number.isSafeInteger(budget) || budget <= 0) {
       return yield* new GateRefused({
         gate: "budget_floor",
-        message: `budget_ms must be a finite number; got ${budget}`,
+        message: `budget_ms must be a positive safe integer; got ${budget}`,
       })
     }
     const floor = minBudgetFor(poll)
@@ -273,35 +268,33 @@ export const waitWorkflow = (
     const dispatchedAt = state.pending_started_at ?? startedMs
     if (state.pending_deadline_ms == null) {
       state.pending_started_at = dispatchedAt
-      state.pending_deadline_ms = dispatchedAt + timeout
+      state.pending_deadline_ms = deadlineAfter(dispatchedAt, timeout)
       yield* store.save(state, root)
     }
     const requireVerdict = kind === "plan_review" || kind === "code_review"
 
-    const readArtifact = (): Effect.Effect<FrontMatter | null> =>
+    const readArtifact = (): Effect.Effect<FrontMatter | null, AppError> =>
       Effect.gen(function* () {
-        const present = yield* fs.exists(artifactAbs)
+        const present = yield* fs.projectPathExists(root, artifactAbs)
         if (!present) return null
-        const text = yield* fs.readFile(artifactAbs)
+        const text = yield* fs.readProjectFile(root, artifactAbs).pipe(
+          Effect.mapError(
+            (error) =>
+              new ArtifactInvalid({
+                artifact: pendingArtifact,
+                message: error.message,
+              }),
+          ),
+        )
         return parseFrontMatter(text)
       })
 
     const advanceOnComplete = (
       fm: FrontMatter,
+      completion: AcceptedArtifactCompletion,
       msg = "artifact ready",
     ): Effect.Effect<ToolResult, AppError> =>
       Effect.gen(function* () {
-        if (
-          fm.rework !== undefined &&
-          (kind !== "code_review" || fm.verdict !== "CHANGES_REQUIRED")
-        ) {
-          return yield* new ArtifactInvalid({
-            artifact: pendingArtifact,
-            message:
-              "rework is valid only on a code_review artifact with verdict CHANGES_REQUIRED",
-          })
-        }
-
         if (
           state.pending_role === "reviewer" &&
           state.reviewer_tree_fingerprint != null
@@ -323,51 +316,26 @@ export const waitWorkflow = (
           }
         }
 
-        // Post-completion Schema guard only — isCompleteArtifact above is the
-        // completeness test. A bad/absent verdict must keep waiting, not fail
-        // here (that already happened before advanceOnComplete was called).
-        //
-        // Only review kinds carry a meaningful verdict. A stray `verdict:` on
-        // a plan/code/package artifact is noise the old parser ignored;
-        // validating it here would wedge the run permanently (state is not
-        // saved on failure, so every retry fails identically).
-        const decoded = decodeFrontMatterResult(
-          {
-            status: fm.status,
-            ...(requireVerdict ? { verdict: fm.verdict } : {}),
-            nits: fm.nits,
-            ...(kind === "code_review" && fm.rework
-              ? { rework: fm.rework }
-              : {}),
-          },
-          pendingArtifact,
-        )
-        if (Result.isFailure(decoded)) {
-          return yield* decoded.failure
-        }
-
-        const rework =
-          kind === "code_review" ? decoded.success.rework : undefined
-        const next = stepAfterArtifact(kind, fm.verdict, rework)
-        if (typeof next === "object") {
-          return yield* new ArtifactInvalid({
-            artifact: pendingArtifact,
-            message: next.error,
-          })
-        }
+        const { next, rework } = completion
 
         if (kind === "phase_package") {
           state.current_phase_package = pendingArtifact
         }
         if (kind === "code_review") {
           state.current_code_review = pendingArtifact
-          state.phase_package_rework =
-            fm.verdict === "CHANGES_REQUIRED" && rework === "phase_package"
         }
         const verdict = asVerdict(fm.verdict)
+        if (kind === "plan_review") {
+          state.required_rework = verdict === "CHANGES_REQUIRED" ? "plan" : null
+        }
+        if (kind === "code_review") {
+          state.required_rework =
+            verdict === "CHANGES_REQUIRED" ? (rework ?? "code") : null
+        }
         state.step = next
         state.pending_artifact = null
         state.pending_role = null
+        state.pending_delivery = null
         state.pending_pane_id = null
         state.pending_pane_label = null
         state.pending_started_at = null
@@ -422,7 +390,10 @@ export const waitWorkflow = (
      * without the second chance. `pending_final_grace` already makes the
      * deadline rung one-shot per run, so forcing it cannot spam a pane.
      */
-    const tryNudge = (why: string, force = false): Effect.Effect<void> =>
+    const tryNudge = (
+      why: string,
+      force = false,
+    ): Effect.Effect<void, AppError> =>
       Effect.gen(function* () {
         if (
           (nudged && !force) ||
@@ -469,12 +440,16 @@ export const waitWorkflow = (
     const loop: Effect.Effect<ToolResult, AppError> = Effect.gen(function* () {
       while (true) {
         const now = yield* Clock.currentTimeMillis
-        const deadline = state.pending_deadline_ms ?? startedMs + timeout
+        const deadline =
+          state.pending_deadline_ms ?? deadlineAfter(startedMs, timeout)
 
         const fm = yield* readArtifact()
-        if (isCompleteArtifact(fm, { requireVerdict })) {
+        const completion = validateArtifactCompletion(kind, fm, pendingArtifact)
+        if (Result.isFailure(completion)) return yield* completion.failure
+        if (completion.success !== null) {
           return yield* advanceOnComplete(
             fm!,
+            completion.success,
             nudged ? "artifact ready after nudge" : "artifact ready",
           )
         }
@@ -490,7 +465,7 @@ export const waitWorkflow = (
                 message: `role pane gone and artifact incomplete: ${pendingArtifact}`,
                 details: {
                   last_agent_status: lastStatus,
-                  hint: "re-dispatch same round after investigate",
+                  hint: "after investigate, dispatch the same kind with redeliver=true",
                 },
               })
             }
@@ -502,9 +477,18 @@ export const waitWorkflow = (
               // The artifact may have completed between the read above and this
               // terminal status, so fail the contract only after one fresh read.
               const artifactAfterDone = yield* readArtifact()
-              if (isCompleteArtifact(artifactAfterDone, { requireVerdict })) {
+              const completionAfterDone = validateArtifactCompletion(
+                kind,
+                artifactAfterDone,
+                pendingArtifact,
+              )
+              if (Result.isFailure(completionAfterDone)) {
+                return yield* completionAfterDone.failure
+              }
+              if (completionAfterDone.success !== null) {
                 return yield* advanceOnComplete(
                   artifactAfterDone!,
+                  completionAfterDone.success,
                   "artifact ready as role exited",
                 )
               }
@@ -568,7 +552,7 @@ export const waitWorkflow = (
                       details: {
                         last_agent_status: lastStatus,
                         foreground: names,
-                        hint: "check pane transcript; re-dispatch same round",
+                        hint: "check pane transcript; then dispatch the same kind with redeliver=true",
                       },
                     })
                   }
@@ -605,7 +589,7 @@ export const waitWorkflow = (
             extendedOnce = true
             const extra = Math.max(Math.floor(timeout * 0.5), 120_000)
             state.pending_extended = true
-            state.pending_deadline_ms = now + extra
+            state.pending_deadline_ms = deadlineAfter(now, extra)
             yield* store.save(state, root)
             hooks.onUpdate?.({
               content: [
@@ -639,7 +623,7 @@ export const waitWorkflow = (
             // grace is not.
             finalNudgeGrace = true
             state.pending_final_grace = true
-            state.pending_deadline_ms = now + 180_000
+            state.pending_deadline_ms = deadlineAfter(now, 180_000)
             yield* store.save(state, root)
             yield* tryNudge("timeout idle", true)
             continue
@@ -681,7 +665,8 @@ export const waitWorkflow = (
       // was never the problem. `timeout` still sizes the extension,
       // because that has to come from config to stay stable across calls.
       const grantedMs =
-        (state.pending_deadline_ms ?? dispatchedAt + timeout) - dispatchedAt
+        (state.pending_deadline_ms ?? deadlineAfter(dispatchedAt, timeout)) -
+        dispatchedAt
       return yield* new WaitTimeout({
         artifact: pendingArtifact,
         timeoutMs: grantedMs,
@@ -690,7 +675,7 @@ export const waitWorkflow = (
           nudged,
           extended_once: extendedOnce,
           configured_timeout_ms: timeout,
-          hint: "inspect pane transcript; re-dispatch same round or nudge via herdr pane run",
+          hint: "inspect pane transcript; use redeliver=true for the same kind only after proving delivery is dead, or nudge via herdr pane run",
         },
       })
     })
@@ -707,7 +692,7 @@ export const waitWorkflow = (
                 artifact,
                 details: {
                   last_agent_status: lastStatus,
-                  hint: "re-dispatch same round or wait again after investigate",
+                  hint: "after investigate, use redeliver=true for the same kind or wait again",
                 },
               }),
             ),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naxodev/apnea",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Host-neutral multi-role workflow engine and standalone Bun CLI",
   "license": "MIT",
   "author": "Nacho Vazquez",
@@ -62,7 +62,7 @@
     "smoke:package": "bun scripts/package-smoke.ts"
   },
   "dependencies": {
-    "effect": "4.0.0-beta.101",
+    "effect": "4.0.0-rc.111",
     "typebox": "^1.3.6"
   },
   "devDependencies": {

package/schemas/config.schema.json

@@ -44,7 +44,11 @@
     "review_round_cap": { "type": "integer", "minimum": 1, "maximum": 20 },
     "timeouts_ms": {
       "type": "object",
-      "additionalProperties": { "type": "integer", "minimum": 1000 }
+      "additionalProperties": {
+        "type": "integer",
+        "minimum": 1000,
+        "maximum": 9007199254740991
+      }
     }
   }
 }

package/schemas/state.schema.json

@@ -5,8 +5,21 @@
   "type": "object",
   "additionalProperties": false,
   "required": ["version", "slug", "step", "phase_index", "rounds", "vcs"],
+  "allOf": [
+    {
+      "if": {
+        "properties": { "version": { "const": 2 } },
+        "required": ["version"]
+      },
+      "then": { "required": ["pending_commit"] },
+      "description": "Runtime enforcement is authoritative: decodeRunState applies the same rule plus consistency checks the JSON Schema cannot express."
+    }
+  ],
   "properties": {
-    "version": { "const": 1 },
+    "version": {
+      "enum": [1, 2],
+      "description": "Version 1 is accepted INPUT for migration (decodes with pending_commit=null); version 2 is the OUTPUT every save writes and must carry pending_commit explicitly."
+    },
     "slug": { "type": "string", "minLength": 1 },
     "step": {
       "type": "string",
@@ -21,19 +34,39 @@
         "done"
       ]
     },
-    "phase_index": { "type": "integer", "minimum": 0 },
-    "phase_count_hint": { "type": ["integer", "null"], "minimum": 0 },
+    "phase_index": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "phase_count_hint": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
     "rounds": {
       "type": "object",
       "description": "Keys like phase-01/plan_review or phase-01/code_review",
-      "additionalProperties": { "type": "integer", "minimum": 1 }
+      "additionalProperties": {
+        "type": "integer",
+        "minimum": 1,
+        "maximum": 9007199254740991
+      }
     },
     "vcs": { "type": "string", "enum": ["jj", "git"] },
     "allow_dirty": { "type": "boolean" },
     "goal": { "type": "string" },
     "last_error": { "type": ["string", "null"] },
-    "pending_artifact": { "type": ["string", "null"] },
+    "pending_artifact": {
+      "type": ["string", "null"],
+      "pattern": "^\\.apnea\\/(?!.*\\u0000)(?!\\.(?:/|$)|\\.\\.(?:/|$))(?!.*\\/\\.(?:\\/|$))(?!.*\\/\\.\\.(?:\\/|$))(?!.*\\\\)[^/]+(?:/[^/]+)*$"
+    },
     "pending_role": { "type": ["string", "null"] },
+    "pending_delivery": {
+      "type": ["string", "null"],
+      "enum": ["manual", "interactive", null],
+      "description": "Known delivery boundary for pending ownership; null is idle or legacy-ambiguous"
+    },
     "pending_floating_exit": {
       "type": "null",
       "deprecated": true,
@@ -41,9 +74,21 @@
     },
     "pending_pane_id": { "type": ["string", "null"] },
     "pending_pane_label": { "type": ["string", "null"] },
-    "pending_started_at": { "type": ["integer", "null"] },
-    "pending_deadline_ms": { "type": ["integer", "null"] },
-    "pending_nudged_at": { "type": ["integer", "null"] },
+    "pending_started_at": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "pending_deadline_ms": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "pending_nudged_at": {
+      "type": ["integer", "null"],
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
     "pending_final_grace": { "type": "boolean" },
     "pending_extended": { "type": "boolean" },
     "role_panes": {
@@ -60,8 +105,117 @@
     },
     "package_root": { "type": "string" },
     "reviewer_tree_fingerprint": { "type": ["string", "null"] },
-    "current_phase_package": { "type": ["string", "null"] },
-    "current_code_review": { "type": ["string", "null"] },
-    "phase_package_rework": { "type": "boolean" }
+    "current_phase_package": {
+      "type": ["string", "null"],
+      "pattern": "^\\.apnea\\/(?!.*\\u0000)(?!\\.(?:/|$)|\\.\\.(?:/|$))(?!.*\\/\\.(?:\\/|$))(?!.*\\/\\.\\.(?:\\/|$))(?!.*\\\\)[^/]+(?:/[^/]+)*$"
+    },
+    "current_code_review": {
+      "type": ["string", "null"],
+      "pattern": "^\\.apnea\\/(?!.*\\u0000)(?!\\.(?:/|$)|\\.\\.(?:/|$))(?!.*\\/\\.(?:\\/|$))(?!.*\\/\\.\\.(?:\\/|$))(?!.*\\\\)[^/]+(?:/[^/]+)*$"
+    },
+    "required_rework": {
+      "type": ["string", "null"],
+      "enum": ["plan", "code", "phase_package", null],
+      "description": "Exact dispatch target that owns the next review round"
+    },
+    "pending_commit": {
+      "description": "Durable record of an in-flight commit transaction (crash-recoverable commit completion). Requires step=committing and phase_index equal to the run's phase_index; non-committing states must carry null. Version-1 files must not contain this key.",
+      "oneOf": [
+        {
+          "type": "null"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "backend",
+            "id",
+            "phase_index",
+            "message",
+            "no_remaining_phases",
+            "verify_log",
+            "branch",
+            "parent_commit",
+            "tree_id"
+          ],
+          "properties": {
+            "backend": { "const": "git" },
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Transaction uuid; appears in the commit message as Apnea-Transaction: <id>"
+            },
+            "phase_index": { "type": "integer", "minimum": 1 },
+            "message": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Full commit message including the Apnea-Transaction trailer line"
+            },
+            "no_remaining_phases": { "type": "boolean" },
+            "verify_log": { "type": "string", "minLength": 1 },
+            "branch": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Full ref the commit must land on, e.g. refs/heads/apnea/<slug>"
+            },
+            "parent_commit": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Expected HEAD at completion; also the created commit's parent"
+            },
+            "tree_id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Prepared tree id staged with .apnea excluded"
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "backend",
+            "id",
+            "phase_index",
+            "message",
+            "no_remaining_phases",
+            "verify_log",
+            "change_id",
+            "content_fingerprint"
+          ],
+          "properties": {
+            "backend": { "const": "jj" },
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Transaction uuid; appears in the change description as Apnea-Transaction: <id>"
+            },
+            "phase_index": { "type": "integer", "minimum": 1 },
+            "message": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Full description including the Apnea-Transaction trailer line"
+            },
+            "no_remaining_phases": { "type": "boolean" },
+            "verify_log": { "type": "string", "minLength": 1 },
+            "change_id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Change id of the described working-copy change"
+            },
+            "content_fingerprint": {
+              "type": "string",
+              "minLength": 1,
+              "description": "Fingerprint of the change's non-.apnea diff at preparation time"
+            }
+          }
+        }
+      ]
+    },
+    "phase_package_rework": {
+      "type": "boolean",
+      "deprecated": true,
+      "description": "Deprecated migration-only field. True migrates to required_rework=phase_package."
+    }
   }
 }