@naxodev/apnea 0.2.0 → 0.2.2

package/extension/schema/frontmatter.ts

@@ -1,4 +1,10 @@
 import { Result, Schema } from "effect"
+import { isCompleteArtifact } from "../domain/frontmatter.ts"
+import {
+  stepAfterArtifact,
+  type DispatchKind,
+} from "../domain/state-machine.ts"
+import type { FrontMatter, ReworkTarget, Step } from "../domain/types.ts"
 import { ArtifactInvalid } from "../errors.ts"
 
 const VerdictSchema = Schema.Literals(["APPROVED", "CHANGES_REQUIRED"] as const)
@@ -17,6 +23,12 @@ export const FrontMatterResultSchema = Schema.Struct({
 
 export type FrontMatterResult = typeof FrontMatterResultSchema.Type
 
+export type AcceptedArtifactCompletion = {
+  frontmatter: FrontMatterResult
+  next: Step
+  rework: ReworkTarget | undefined
+}
+
 export function decodeFrontMatterResult(
   raw: unknown,
   artifact = "artifact",
@@ -32,3 +44,48 @@ export function decodeFrontMatterResult(
   }
   return Result.succeed(decoded.success)
 }
+
+/** Shared acceptance boundary for wait advancement and redelivery refusal. */
+export function validateArtifactCompletion(
+  kind: DispatchKind,
+  fm: FrontMatter | null,
+  artifact = "artifact",
+): Result.Result<AcceptedArtifactCompletion | null, ArtifactInvalid> {
+  const requireVerdict = kind === "plan_review" || kind === "code_review"
+  if (!isCompleteArtifact(fm, { requireVerdict })) return Result.succeed(null)
+
+  if (
+    fm!.rework !== undefined &&
+    (kind !== "code_review" || fm!.verdict !== "CHANGES_REQUIRED")
+  ) {
+    return Result.fail(
+      new ArtifactInvalid({
+        artifact,
+        message:
+          "rework is valid only on a code_review artifact with verdict CHANGES_REQUIRED",
+      }),
+    )
+  }
+
+  const decoded = decodeFrontMatterResult(
+    {
+      status: fm!.status,
+      ...(requireVerdict ? { verdict: fm!.verdict } : {}),
+      nits: fm!.nits,
+      ...(kind === "code_review" && fm!.rework ? { rework: fm!.rework } : {}),
+    },
+    artifact,
+  )
+  if (Result.isFailure(decoded)) return Result.fail(decoded.failure)
+
+  const rework = kind === "code_review" ? decoded.success.rework : undefined
+  const next = stepAfterArtifact(kind, fm!.verdict, rework)
+  if (typeof next === "object") {
+    return Result.fail(new ArtifactInvalid({ artifact, message: next.error }))
+  }
+  return Result.succeed({
+    frontmatter: decoded.success,
+    next,
+    rework,
+  })
+}

package/extension/schema/state.ts

@@ -1,6 +1,12 @@
 import { Result, Schema } from "effect"
 import { StateCorrupt } from "../errors.ts"
-import type { RunState, Step } from "../domain/types.ts"
+import {
+  LEGACY_CODE_REWORK,
+  LEGACY_PLAN_REWORK,
+  type RequiredReworkTarget,
+  type RunState,
+  type Step,
+} from "../domain/types.ts"
 
 export const StepSchema = Schema.Literals([
   "planning",
@@ -22,35 +28,94 @@ export const RoleSchema = Schema.Literals([
   "coder",
 ] as const)
 
+export const RequiredReworkSchema = Schema.NullOr(
+  Schema.Literals(["plan", "code", "phase_package"] as const),
+)
+
+export const PendingDeliverySchema = Schema.NullOr(
+  Schema.Literals(["manual", "interactive"] as const),
+)
+
 const PaneRefSchema = Schema.Struct({
   pane_id: Schema.String,
   label: Schema.String,
   profile_fingerprint: Schema.optionalKey(Schema.NullOr(Schema.String)),
 })
 
+const PositiveSafeInteger = Schema.Int.check(Schema.isGreaterThanOrEqualTo(1))
+const NonNegativeSafeInteger = Schema.Int.check(
+  Schema.isGreaterThanOrEqualTo(0),
+)
+
+const PendingCommitFields = {
+  id: Schema.String.check(Schema.isMinLength(1)),
+  phase_index: PositiveSafeInteger,
+  message: Schema.String.check(Schema.isMinLength(1)),
+  no_remaining_phases: Schema.Boolean,
+  verify_log: Schema.String.check(Schema.isMinLength(1)),
+}
+
+// Anchor fields flow into git/jj argv, so they get format checks beyond
+// minLength. Exploiting a loose anchor requires state.json write access
+// (game-over elsewhere), but validating costs nothing and removes the class.
+export const GitPendingCommitSchema = Schema.Struct({
+  backend: Schema.Literal("git"),
+  ...PendingCommitFields,
+  branch: Schema.String.check(
+    Schema.isPattern(/^refs\/heads\/apnea\/[A-Za-z0-9._-]+$/),
+  ),
+  parent_commit: Schema.String.check(Schema.isPattern(/^[0-9a-f]{40,64}$/)),
+  tree_id: Schema.String.check(Schema.isPattern(/^[0-9a-f]{40,64}$/)),
+})
+
+export const JjPendingCommitSchema = Schema.Struct({
+  backend: Schema.Literal("jj"),
+  ...PendingCommitFields,
+  change_id: Schema.String.check(Schema.isPattern(/^[A-Za-z0-9]{1,32}$/)),
+  content_fingerprint: Schema.String.check(
+    Schema.isPattern(/^[0-9a-f]{8,64}$/),
+  ),
+})
+
+export const PendingCommitSchema = Schema.Union([
+  GitPendingCommitSchema,
+  JjPendingCommitSchema,
+])
+
 /**
- * Runtime codec for `state.json` (version 1).
- * Missing pane-tracking fields are filled in `decodeRunState` (legacy files).
+ * Runtime codec for `state.json`.
+ *
+ * Input accepts version 1 (files written by 0.2.x) and version 2. Version-1
+ * files must not carry `pending_commit` — that is enforced in
+ * `decodeRunState`, which migrates every decoded state to version 2 with
+ * `pending_commit: null`. Version-2 files must record `pending_commit`
+ * explicitly, so a truncated or hand-edited v2 file fails closed instead of
+ * silently losing a durable commit transaction.
  */
 export const RunStateSchema = Schema.Struct({
-  version: Schema.Literal(1),
+  // v1 on Encoded so legacy files still decode; decodeRunState always
+  // outputs version 2.
+  version: Schema.Union([Schema.Literal(1), Schema.Literal(2)]),
   slug: Schema.String.check(Schema.isMinLength(1)),
   step: StepSchema,
-  phase_index: Schema.Number,
-  phase_count_hint: Schema.NullOr(Schema.Number),
-  rounds: Schema.Record(Schema.String, Schema.Number),
+  phase_index: PositiveSafeInteger,
+  phase_count_hint: Schema.NullOr(NonNegativeSafeInteger),
+  rounds: Schema.Record(Schema.String, PositiveSafeInteger),
   vcs: VcsBackendSchema,
   allow_dirty: Schema.Boolean,
   goal: Schema.String,
   last_error: Schema.NullOr(Schema.String),
   pending_artifact: Schema.NullOr(Schema.String),
   pending_role: Schema.NullOr(RoleSchema),
+  pending_delivery: Schema.optionalKey(PendingDeliverySchema),
   // optional on Encoded so legacy fixtures without pane fields still decode
   pending_pane_id: Schema.optionalKey(Schema.NullOr(Schema.String)),
   pending_pane_label: Schema.optionalKey(Schema.NullOr(Schema.String)),
-  pending_started_at: Schema.optionalKey(Schema.NullOr(Schema.Number)),
-  pending_deadline_ms: Schema.optionalKey(Schema.NullOr(Schema.Number)),
-  pending_nudged_at: Schema.optionalKey(Schema.NullOr(Schema.Number)),
+  pending_started_at: Schema.optionalKey(Schema.NullOr(NonNegativeSafeInteger)),
+  pending_deadline_ms: Schema.optionalKey(
+    Schema.NullOr(NonNegativeSafeInteger),
+  ),
+  pending_nudged_at: Schema.optionalKey(Schema.NullOr(NonNegativeSafeInteger)),
   pending_final_grace: Schema.optionalKey(Schema.Boolean),
   pending_extended: Schema.optionalKey(Schema.Boolean),
   role_panes: Schema.optionalKey(Schema.Record(Schema.String, PaneRefSchema)),
@@ -58,11 +123,38 @@ export const RunStateSchema = Schema.Struct({
   reviewer_tree_fingerprint: Schema.NullOr(Schema.String),
   current_phase_package: Schema.NullOr(Schema.String),
   current_code_review: Schema.NullOr(Schema.String),
-  phase_package_rework: Schema.optionalKey(Schema.Boolean),
+  required_rework: Schema.optionalKey(RequiredReworkSchema),
+  // optional on Encoded so version-1 files without the key still decode;
+  // presence rules per version are enforced in `decodeRunState`.
+  pending_commit: Schema.optionalKey(Schema.NullOr(PendingCommitSchema)),
 })
 
 export type DecodedRunState = typeof RunStateSchema.Type
 
+function isPersistedArtifactPath(value: string): boolean {
+  if (
+    !value.startsWith(".apnea/") ||
+    value.includes("\\") ||
+    value.includes("\0")
+  ) {
+    return false
+  }
+  return value
+    .slice(".apnea/".length)
+    .split("/")
+    .every((part) => part !== "" && part !== "." && part !== "..")
+}
+
+function hasMatchingPendingCoderDispatch(d: DecodedRunState): boolean {
+  const phase = String(d.phase_index).padStart(2, "0")
+  const round = d.rounds[`phase-${phase}/code_review`] ?? 1
+  return (
+    d.pending_role === "coder" &&
+    d.pending_artifact ===
+      `.apnea/artifacts/phase-${phase}/round-${round}/coder-result.md`
+  )
+}
+
 export function decodeRunState(
   json: unknown,
   path = "state.json",
@@ -83,6 +175,14 @@ export function decodeRunState(
     )
   }
 
+  const raw =
+    json !== null && typeof json === "object" && !Array.isArray(json)
+      ? (json as Record<string, unknown>)
+      : {}
+  const hasRequiredRework = raw.required_rework !== undefined
+  const hasPendingDelivery = raw.pending_delivery !== undefined
+  const hasPendingCommit =
+    "pending_commit" in raw && raw.pending_commit !== undefined
   const decoded = Schema.decodeUnknownResult(RunStateSchema)(json)
   if (Result.isFailure(decoded)) {
     return Result.fail(
@@ -93,9 +193,80 @@ export function decodeRunState(
     )
   }
   const d = decoded.success
+  // A version-1 writer never emits `pending_commit`; its presence means the
+  // file was mixed across versions. Fail closed instead of guessing.
+  if (d.version === 1 && hasPendingCommit) {
+    return Result.fail(
+      new StateCorrupt({
+        path,
+        message:
+          "pending_commit requires state version 2; refusing version-1 file that carries it",
+      }),
+    )
+  }
+  if (d.version === 2 && !hasPendingCommit) {
+    return Result.fail(
+      new StateCorrupt({
+        path,
+        message:
+          "version-2 state must record pending_commit explicitly; refusing file that omits it",
+      }),
+    )
+  }
+  if (
+    d.pending_commit !== null &&
+    d.pending_commit !== undefined &&
+    d.step !== "committing"
+  ) {
+    return Result.fail(
+      new StateCorrupt({
+        path,
+        message: `pending_commit requires step "committing", found "${d.step}"`,
+      }),
+    )
+  }
+  if (
+    d.pending_commit != null &&
+    d.pending_commit.phase_index !== d.phase_index
+  ) {
+    return Result.fail(
+      new StateCorrupt({
+        path,
+        message: `pending_commit targets phase ${d.pending_commit.phase_index} but state is at phase ${d.phase_index}`,
+      }),
+    )
+  }
+  if (
+    d.pending_commit != null &&
+    !isPersistedArtifactPath(d.pending_commit.verify_log)
+  ) {
+    return Result.fail(
+      new StateCorrupt({
+        path,
+        message:
+          "pending_commit.verify_log must be a repository-relative .apnea/ path",
+      }),
+    )
+  }
+  for (const [field, value] of [
+    ["pending_artifact", d.pending_artifact],
+    ["current_phase_package", d.current_phase_package],
+    ["current_code_review", d.current_code_review],
+  ] as const) {
+    if (value !== null && !isPersistedArtifactPath(value)) {
+      return Result.fail(
+        new StateCorrupt({
+          path,
+          message: `${field} must be a repository-relative .apnea/ path`,
+        }),
+      )
+    }
+  }
   // Backward-compat defaults for state.json files predating pane tracking.
+  // Every decoded state migrates to version 2; the rewrite to disk happens
+  // at the next normal save.
   const state: RunState = {
-    version: 1,
+    version: 2,
     slug: d.slug,
     step: d.step as Step,
     phase_index: d.phase_index,
@@ -107,6 +278,11 @@ export function decodeRunState(
     last_error: d.last_error,
     pending_artifact: d.pending_artifact,
     pending_role: d.pending_role,
+    pending_delivery: hasPendingDelivery
+      ? (d.pending_delivery ?? null)
+      : d.pending_artifact !== null && d.pending_pane_id != null
+        ? "interactive"
+        : null,
     pending_pane_id: d.pending_pane_id ?? null,
     pending_pane_label: d.pending_pane_label ?? null,
     pending_started_at: d.pending_started_at ?? null,
@@ -124,7 +300,28 @@ export function decodeRunState(
     reviewer_tree_fingerprint: d.reviewer_tree_fingerprint,
     current_phase_package: d.current_phase_package,
     current_code_review: d.current_code_review,
-    phase_package_rework: d.phase_package_rework ?? false,
+    required_rework: (hasRequiredRework
+      ? d.required_rework
+      : raw.phase_package_rework === true
+        ? "phase_package"
+        : null) as RequiredReworkTarget | null,
+    pending_commit: d.pending_commit ?? null,
+  }
+  if (
+    !hasRequiredRework &&
+    state.required_rework === null &&
+    d.step === "planning"
+  ) {
+    Object.defineProperty(state, LEGACY_PLAN_REWORK, { value: true })
+  }
+  if (
+    !hasRequiredRework &&
+    state.required_rework === null &&
+    d.step === "coding" &&
+    d.current_code_review !== null &&
+    !hasMatchingPendingCoderDispatch(d)
+  ) {
+    Object.defineProperty(state, LEGACY_CODE_REWORK, { value: true })
   }
   return Result.succeed(state)
 }

package/extension/services/app-live.ts

@@ -5,6 +5,7 @@ import { FileSystemLive } from "./file-system.ts"
 import { makeHerdrLive } from "./herdr.ts"
 import { RunStoreLive } from "./run-store.ts"
 import { VcsLive } from "./vcs.ts"
+import { ProcessLive } from "./process.ts"
 
 /**
  * Blueprint layer for tool calls. Built freshly on every `Effect.provide`
@@ -18,7 +19,7 @@ export const makeAppLive = (hostAdapter: ApneaHostAdapter) =>
       VcsLive,
       makeHerdrLive(hostAdapter),
     ),
-    FileSystemLive,
+    Layer.merge(FileSystemLive, ProcessLive),
   )
 
 export const AppLive = makeAppLive(neutralHostAdapter)

package/extension/services/config.ts

@@ -1,3 +1,4 @@
+import * as os from "node:os"
 import { Context, Effect, Layer, Result } from "effect"
 import { globalConfigPath, projectConfigPath } from "../domain/paths.ts"
 import { ConfigError } from "../errors.ts"
@@ -50,7 +51,8 @@ export const ConfigLive = Layer.effect(
 
     const load = (root: string): Effect.Effect<ApneaConfig, ConfigError> =>
       Effect.gen(function* () {
-        const gPath = globalConfigPath()
+        const trustedHome = os.homedir()
+        const gPath = globalConfigPath(trustedHome)
         const gPresent = yield* fs.exists(gPath)
         if (!gPresent) {
           return yield* new ConfigError({
@@ -58,7 +60,7 @@ export const ConfigLive = Layer.effect(
             path: gPath,
           })
         }
-        const gText = yield* fs.readFile(gPath)
+        const gText = yield* fs.readTrustedGlobalFile(trustedHome, gPath)
         const gRaw = yield* parseJson(gText, gPath)
         const gDecoded = decodeGlobalConfig(gRaw)
         if (Result.isFailure(gDecoded)) {
@@ -67,9 +69,9 @@ export const ConfigLive = Layer.effect(
         let cfg = gDecoded.success
 
         const pPath = projectConfigPath(root)
-        const pPresent = yield* fs.exists(pPath)
+        const pPresent = yield* fs.projectPathExists(root, pPath)
         if (pPresent) {
-          const pText = yield* fs.readFile(pPath)
+          const pText = yield* fs.readProjectFile(root, pPath)
           const pRaw = yield* parseJson(pText, pPath)
           const pDecoded = decodeProjectConfig(pRaw)
           if (Result.isFailure(pDecoded)) {