@zaip-ai/cli 1.3.0 → 1.3.1

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-local-telemetry.mjs

@@ -1,5 +1,11 @@
 import { readFile, rename, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import {
+  applyExplicitTurnRecovery,
+  normalizeExplicitTurnRecoverySchema,
+  parseExplicitTurnMappings,
+  planExplicitTurnRecovery,
+} from "./reconcile-telemetry-explicit-recovery.mjs";
 import {
   aggregate,
   duplicateUsageAssignments,
@@ -32,6 +38,7 @@ const reprice = process.argv.includes("--reprice");
 const deduplicate = process.argv.includes("--deduplicate");
 const remeasure = process.argv.includes("--remeasure");
 const timingOnly = process.argv.includes("--timing-only");
+const explicitRecovery = process.argv.includes("--explicit-turn-recovery");
 if (timingOnly && !remeasure) {
   throw new Error("--timing-only requires --remeasure");
 }
@@ -55,13 +62,19 @@ const selectedSessionFiles = process.argv
         : [],
   )
   .filter(Boolean);
+const explicitMappings = parseExplicitTurnMappings(
+  process.argv,
+  explicitRecovery,
+  selectedRunIds,
+  selectedSessionFiles,
+);
 if (remeasure && selectedRunIds.size === 0) {
   throw new Error("--remeasure requires at least one explicit --run <RUN-ID>");
 }
 if (apply && deduplicate && selectedRunIds.size === 0) {
   throw new Error("--apply --deduplicate requires at least one explicit --run <RUN-ID>");
 }
-const applyBackfill = apply && !deduplicate && !remeasure;
+const applyBackfill = apply && !deduplicate && !remeasure && !explicitRecovery;
 
 const runFiles = await filesUnder(join(workspace, ".agents", "records", "runs"), ".jsonl");
 const runs = [];
@@ -192,9 +205,38 @@ const allSegments = await loadSegments(
   workspace,
   selectedSessionFiles.length === 0 ? null : selectedSessionFiles,
 );
-// Native usage can be captured before the Codex session emits task_complete.
-// A normal backfill must not replace those observed tokens or costs, but it can
-// append an exact, timing-only correction once that terminal boundary appears.
+let explicitSchemaNormalized = false;
+if (apply && explicitRecovery) {
+  const run = runs.find((candidate) => candidate.started.run_id === [...selectedRunIds][0]);
+  if (run) {
+    const normalized = await normalizeExplicitTurnRecoverySchema(
+      run.file,
+      run.records,
+      explicitMappings,
+    );
+    if (normalized !== run.records) {
+      run.records = normalized;
+      run.usage = normalized
+        .filter((record) => recordType(record) === "usage.recorded")
+        .map(usageView);
+      explicitSchemaNormalized = true;
+    }
+  }
+}
+const explicitRecoveryPlan = explicitRecovery
+  ? (() => {
+      const runId = [...selectedRunIds][0];
+      const run = runs.find((candidate) => candidate.started.run_id === runId);
+      return run
+        ? planExplicitTurnRecovery({ run, segments: allSegments, mappings: explicitMappings })
+        : { run_id: runId, eligible: false, reasons: ["run-not-found"], turns: [], recovered: [] };
+    })()
+  : null;
+if (apply && explicitRecovery && explicitRecoveryPlan.eligible) {
+  const run = runs.find((candidate) => candidate.started.run_id === explicitRecoveryPlan.run_id);
+  await applyExplicitTurnRecovery({ run, plan: explicitRecoveryPlan });
+  explicitRecoveryPlan.applied = true;
+}
 const timingRunIds = timingEnrichmentRunIds({
   remeasure,
   applyBackfill,
@@ -208,8 +250,6 @@ const remeasurement =
         allSegments,
         runs,
         selectedRunIds: timingRunIds,
-        // Automatic backfill is intentionally timing-only. Explicit remeasurement
-        // retains its existing token/cost correction behavior unless requested.
         timingOnly: remeasure ? timingOnly : true,
         workspace,
       })
@@ -598,8 +638,6 @@ const eligible = candidates.filter(
 
 if (applyBackfill) {
   for (const { run, segment, confidence } of eligible) {
-    // Re-read each Run under the serial apply loop: a preceding timing repair may
-    // have reordered or appended a correction after the initial scan.
     const persistedRecords = jsonLines(await readFile(run.file, "utf8"));
     const finishIndex = persistedRecords.findIndex(
       (record) => recordType(record) === "run.finished",
@@ -676,23 +714,35 @@ console.log(
         ? apply
           ? "apply-deduplicate"
           : "dry-run-deduplicate"
-        : remeasure
+        : explicitRecovery
           ? apply
-            ? "apply-remeasure"
-            : "dry-run-remeasure"
-          : apply
-            ? reprice
-              ? "apply-reprice"
-              : approximate
-                ? "apply-approximate"
-                : "apply"
-            : reprice
-              ? "dry-run-reprice"
-              : approximate
-                ? "dry-run-approximate"
-                : "dry-run",
+            ? "apply-explicit-turn-recovery"
+            : "dry-run-explicit-turn-recovery"
+          : remeasure
+            ? apply
+              ? "apply-remeasure"
+              : "dry-run-remeasure"
+            : apply
+              ? reprice
+                ? "apply-reprice"
+                : approximate
+                  ? "apply-approximate"
+                  : "apply"
+              : reprice
+                ? "dry-run-reprice"
+                : approximate
+                  ? "dry-run-approximate"
+                  : "dry-run",
       run_files: runs.length,
       remeasurement,
+      explicit_turn_recovery: explicitRecoveryPlan && {
+        run_id: explicitRecoveryPlan.run_id,
+        eligible: explicitRecoveryPlan.eligible,
+        applied: explicitRecoveryPlan.applied === true,
+        reasons: explicitRecoveryPlan.reasons,
+        turns: explicitRecoveryPlan.turns,
+        schema_normalized: explicitSchemaNormalized,
+      },
       local_session_files: new Set(segments.map((segment) => segment.file)).size,
       local_segments_available: segments.length,
       already_measured: runs.filter((run) => run.measured).length,

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-explicit-recovery.mjs

@@ -0,0 +1,223 @@
+import { open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import {
+  aggregate,
+  jsonLines,
+  recordPhase,
+  recordType,
+  usageStatus,
+  usageView,
+  withSequence,
+} from "./reconcile-telemetry-lib.mjs";
+
+export function parseExplicitTurnMappings(args, enabled, runIds, sessionFiles) {
+  const mappings = args.flatMap((argument, index, values) => {
+    if (argument !== "--explicit-turn") return [];
+    const [spec_id, turn_id, total, usd, brl] = String(values[index + 1] ?? "").split("|");
+    return [{ spec_id, turn_id, total: Number(total), usd: Number(usd), brl: Number(brl) }];
+  });
+  if (enabled && (runIds.size !== 1 || sessionFiles.length !== 1))
+    throw new Error("--explicit-turn-recovery requires exactly one --run and one --session-file");
+  if (enabled && mappings.length === 0)
+    throw new Error(
+      "--explicit-turn-recovery requires one or more --explicit-turn SPEC|TURN|TOTAL|USD|BRL",
+    );
+  return mappings;
+}
+
+// This deliberately accepts no temporal heuristic.  A recovery is useful only
+// when a human supplies the expected SPEC-to-turn mapping and every identity
+// boundary independently agrees with the persisted Run.
+export function planExplicitTurnRecovery({ run, segments, mappings }) {
+  const runId = run?.started?.run_id;
+  const finished = run?.records?.find((record) => recordType(record) === "run.finished");
+  const usedKeys = new Set(
+    run.usage.filter((usage) => usage.source_segment_key).map((usage) => usage.source_segment_key),
+  );
+  const problems = [];
+  if (!runId || !finished) problems.push("run-not-finished");
+  if (!run?.started?.client_thread_id) problems.push("run-client-thread-unavailable");
+  if (!Array.isArray(mappings) || mappings.length === 0) problems.push("explicit-mapping-required");
+  const turnIds = new Set();
+  const recovered = [];
+  for (const mapping of mappings ?? []) {
+    if (!mapping.spec_id || !mapping.turn_id) {
+      problems.push("mapping-spec-and-turn-required");
+      continue;
+    }
+    if (turnIds.has(mapping.turn_id)) {
+      problems.push("duplicate-explicit-turn");
+      continue;
+    }
+    turnIds.add(mapping.turn_id);
+    const matches = segments.filter(
+      (segment) =>
+        segment.internal_turn_ids?.includes(mapping.turn_id) || segment.turn_id === mapping.turn_id,
+    );
+    if (matches.length !== 1) {
+      problems.push(
+        matches.length === 0
+          ? `turn-not-found:${mapping.turn_id}`
+          : `turn-ambiguous:${mapping.turn_id}`,
+      );
+      continue;
+    }
+    const segment = matches[0];
+    if (segment.session_agent_path !== run.started.client_thread_id)
+      problems.push(`session-agent-path-mismatch:${mapping.turn_id}`);
+    if (segment.model !== run.started.model || segment.effort !== run.started.reasoning_effort)
+      problems.push(`model-effort-mismatch:${mapping.turn_id}`);
+    if (usedKeys.has(segment.key)) problems.push(`turn-already-used:${mapping.turn_id}`);
+    if (!segment.finished_at) problems.push(`turn-not-finished:${mapping.turn_id}`);
+    if (!segment.raw?.includes(mapping.spec_id))
+      problems.push(`spec-evidence-missing:${mapping.turn_id}`);
+    const tokens = aggregate(segment);
+    if (mapping.total !== undefined && tokens.total !== mapping.total)
+      problems.push(`token-total-mismatch:${mapping.turn_id}`);
+    recovered.push({ mapping, segment, tokens });
+  }
+  return {
+    run_id: runId,
+    eligible: problems.length === 0 && recovered.length === mappings.length,
+    reasons: problems,
+    turns: recovered.map(({ mapping, segment, tokens }) => ({
+      spec_id: mapping.spec_id,
+      turn_id: mapping.turn_id,
+      source_segment_key: segment.key,
+      source_started_at: segment.started_at,
+      source_finished_at: segment.finished_at,
+      tokens,
+    })),
+    recovered,
+  };
+}
+
+export async function applyExplicitTurnRecovery({ run, plan }) {
+  if (!plan.eligible)
+    throw new Error(`Explicit recovery is not eligible: ${plan.reasons.join(", ")}`);
+  const finished = run.records.find((record) => recordType(record) === "run.finished");
+  const superseded = usageStatus(run.usage).effective.at(-1);
+  if (!superseded) throw new Error("Explicit recovery needs a supersedable effective usage event");
+  const sequence = run.records.length + 1;
+  const events = plan.recovered.map(({ mapping, segment, tokens }, index) => ({
+    schema_version: 2,
+    event_id: `${run.started.run_id}:explicit-turn-recovery:${String(sequence + index).padStart(6, "0")}`,
+    run_id: run.started.run_id,
+    sequence: sequence + index,
+    occurred_at: segment.finished_at,
+    type: "usage.recorded",
+    phase: recordPhase(finished),
+    activity_kind: "retrospective_explicit_turn_recovery",
+    classification_source: "explicit",
+    tokens: { ...tokens, source: "provider_reported" },
+    cost: { usd: mapping.usd, brl: mapping.brl },
+    provider: run.started.provider ?? "openai",
+    model: segment.model,
+    source_segment_key: segment.key,
+    attributed_spec_id: mapping.spec_id,
+    supersedes_event_id: index === 0 ? superseded.event_id : null,
+    retrospective_correction: true,
+    source_occurred_at: segment.finished_at,
+    source_started_at: segment.started_at,
+    source_finished_at: segment.finished_at,
+    runtime: { reasoning_effort: segment.effort, service_tier: segment.service_tier },
+  }));
+  await appendExplicitTurnRecovery(run.file, run.records, events);
+  return events;
+}
+
+// Kept separate from the general reconcile path: it only normalizes fields
+// emitted by this explicit recovery writer, and only when the same scoped
+// command is being resumed after an interrupted projection check.
+export async function normalizeExplicitTurnRecoverySchema(file, expectedRecords, mappings = []) {
+  const specByTurn = new Map(mappings.map((mapping) => [mapping.turn_id, mapping.spec_id]));
+  const changed = expectedRecords.some((record) => {
+    const usage = usageView(record);
+    return (
+      usage?.activity_kind === "retrospective_explicit_turn_recovery" &&
+      (usage.classification_source !== "explicit" ||
+        "explicit_turn_recovery" in usage ||
+        "explicit_spec_id" in usage ||
+        usage.attributed_spec_id === undefined)
+    );
+  });
+  if (!changed) return expectedRecords;
+  const lockPath = `${file}.lock`;
+  const handle = await open(lockPath, "wx");
+  await handle.close();
+  try {
+    const persisted = jsonLines(await readFile(file, "utf8"));
+    const ids = (records) => records.map((record) => record?.event_id ?? record?.[2]);
+    if (
+      persisted.length !== expectedRecords.length ||
+      ids(persisted).some((id, index) => id !== ids(expectedRecords)[index])
+    )
+      throw new Error("Run history changed before explicit recovery schema normalization");
+    let recoveryIndex = 0;
+    const normalized = persisted.map((record) => {
+      const usage = usageView(record);
+      if (usage?.activity_kind !== "retrospective_explicit_turn_recovery") return record;
+      const { explicit_turn_recovery, explicit_spec_id, ...rest } = usage;
+      const recoveredTurn = [...specByTurn.keys()].find((turn) =>
+        rest.source_segment_key?.includes(turn),
+      );
+      const mappedSpecId = mappings[recoveryIndex++]?.spec_id;
+      return {
+        ...rest,
+        classification_source: "explicit",
+        ...(typeof rest.attributed_spec_id === "string"
+          ? {}
+          : typeof explicit_spec_id === "string"
+            ? { attributed_spec_id: explicit_spec_id }
+            : recoveredTurn
+              ? { attributed_spec_id: specByTurn.get(recoveredTurn) }
+              : typeof mappedSpecId === "string"
+                ? { attributed_spec_id: mappedSpecId }
+                : {}),
+      };
+    });
+    const temporary = `${file}.explicit-recovery-schema.tmp`;
+    await writeFile(
+      temporary,
+      `${normalized.map((record) => JSON.stringify(record)).join("\n")}\n`,
+      "utf8",
+    );
+    await rename(temporary, file);
+    return normalized;
+  } finally {
+    await rm(lockPath, { force: true });
+  }
+}
+
+export async function appendExplicitTurnRecovery(file, expectedRecords, events) {
+  if (!Array.isArray(events) || events.length === 0)
+    throw new Error("Explicit recovery events required");
+  const lockPath = `${file}.lock`;
+  const handle = await open(lockPath, "wx");
+  await handle.close();
+  try {
+    const persisted = jsonLines(await readFile(file, "utf8"));
+    const ids = (records) => records.map((record) => record?.event_id ?? record?.[2]);
+    if (
+      persisted.length !== expectedRecords.length ||
+      ids(persisted).some((id, index) => id !== ids(expectedRecords)[index])
+    )
+      throw new Error("Run history changed before explicit recovery");
+    const finishIndex = persisted.findIndex((record) => recordType(record) === "run.finished");
+    if (finishIndex < 0) throw new Error("Explicit recovery requires run.finished");
+    const before = persisted.slice(0, finishIndex);
+    const finish = persisted[finishIndex];
+    const after = persisted.slice(finishIndex + 1);
+    const updated = [...before, ...after, ...events, finish].map((record, index) =>
+      withSequence(record, index + 1),
+    );
+    const temporary = `${file}.explicit-recovery.tmp`;
+    await writeFile(
+      temporary,
+      `${updated.map((record) => JSON.stringify(record)).join("\n")}\n`,
+      "utf8",
+    );
+    await rename(temporary, file);
+  } finally {
+    await rm(lockPath, { force: true });
+  }
+}

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-lib.mjs

@@ -243,7 +243,20 @@ export function exactCompletedSegment(started, segments) {
   if (!started?.client_turn_id) return { segment: null, ambiguous: false };
   const runStartedAt = Date.parse(started.occurred_at ?? "");
   const matches = segments.filter((segment) => {
-    if (segment.turn_id !== started.client_turn_id || !segment.finished_at) return false;
+    // Older Codex sub-runs can persist the internal turn id exposed in a
+    // response item's metadata instead of the enclosing task_started id. It
+    // is an observed identity for this exact local interval, never a token
+    // matching heuristic.
+    const observedInternalTurnIds = Array.isArray(segment.internal_turn_ids)
+      ? segment.internal_turn_ids
+      : [];
+    if (
+      (segment.turn_id !== started.client_turn_id &&
+        !observedInternalTurnIds.includes(started.client_turn_id)) ||
+      !segment.finished_at
+    ) {
+      return false;
+    }
     const segmentFinishedAt = Date.parse(segment.finished_at);
     return (
       Number.isFinite(runStartedAt) &&
@@ -330,6 +343,7 @@ export async function loadSegments(workspace, sessionFiles = null) {
     let canonicalSessionMetaSeen = false;
     let workspaceMatches = false;
     let sessionId = null;
+    let sessionAgentPath = null;
     let current = null;
     let index = 0;
     let model = null;
@@ -365,6 +379,16 @@ export async function loadSegments(workspace, sessionFiles = null) {
         canonicalSessionMetaSeen = true;
         workspaceMatches = normalized(payload.cwd) === normalized(workspace);
         sessionId = nextSessionId;
+        const declaredAgentPath =
+          typeof payload.agent_path === "string"
+            ? payload.agent_path
+            : typeof payload?.source?.subagent?.thread_spawn?.agent_path === "string"
+              ? payload.source.subagent.thread_spawn.agent_path
+              : null;
+        // A child rollout may embed its parent session metadata immediately
+        // after its own. Retain the child identity rather than downgrading to
+        // the parent metadata that cannot identify the subagent.
+        sessionAgentPath = declaredAgentPath ?? sessionAgentPath;
       }
       if (!workspaceMatches) continue;
       const settings = payload?.type === "thread_settings_applied" ? payload.thread_settings : null;
@@ -393,12 +417,14 @@ export async function loadSegments(workspace, sessionFiles = null) {
           key: `${normalized(file)}#${index}`,
           file,
           session_id: sessionId,
+          session_agent_path: sessionAgentPath,
           turn_id: typeof payload.turn_id === "string" ? payload.turn_id : null,
           started_at: record.timestamp ?? null,
           finished_at: null,
           model,
           effort,
           service_tier: serviceTier,
+          internal_turn_ids: [],
           usage: [],
           raw: [],
         };
@@ -422,12 +448,27 @@ export async function loadSegments(workspace, sessionFiles = null) {
         }
       }
       if (!current) continue;
+      const internalTurnId = payload?.internal_chat_message_metadata_passthrough?.turn_id;
+      if (
+        typeof internalTurnId === "string" &&
+        !current.internal_turn_ids.includes(internalTurnId)
+      ) {
+        current.internal_turn_ids.push(internalTurnId);
+      }
       if (line.includes("RUN-") || line.includes("TASK-")) current.raw.push(line);
       if (payload?.type === "task_complete") {
         current.finished_at = record.timestamp ?? null;
         if (current.usage.length) segments.push(current);
         current = null;
       }
+      if (current && payload?.type === "turn_aborted" && payload.turn_id === current.turn_id) {
+        // An interrupted Codex turn is still an observed terminal boundary.
+        // Preserve its collected token snapshots, but never fabricate a later
+        // finish from the Run history or wall clock.
+        current.finished_at = record.timestamp ?? null;
+        if (current.usage.length) segments.push(current);
+        current = null;
+      }
     }
     if (current?.usage.length) segments.push(current);
   }

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-lib.test.mjs

@@ -13,6 +13,7 @@ import {
   exactRemeasurementSegment,
   isExactDuplicateUsageGroup,
   jsonLines,
+  loadSegments,
   pricingFor,
   recordSequence,
   recordType,
@@ -209,6 +210,106 @@ test("selects only one completed local segment for an exact Run turn", () => {
   );
 });
 
+test("matches an observed internal Codex subturn to its enclosing local interval", async () => {
+  const root = await mkdtemp(join(tmpdir(), "zaip-reconcile-internal-turn-"));
+  roots.push(root);
+  const sessionFile = join(root, "internal-subturn.jsonl");
+  await writeFile(
+    sessionFile,
+    [
+      {
+        timestamp: "2026-08-12T04:30:25.797Z",
+        type: "session_meta",
+        payload: { id: "session-1", cwd: root },
+      },
+      {
+        timestamp: "2026-08-12T04:30:26.435Z",
+        type: "event_msg",
+        payload: { type: "task_started", turn_id: "outer-turn" },
+      },
+      {
+        timestamp: "2026-08-12T04:31:00.000Z",
+        type: "response_item",
+        payload: {
+          type: "reasoning",
+          internal_chat_message_metadata_passthrough: { turn_id: "internal-subturn" },
+        },
+      },
+      {
+        timestamp: "2026-08-12T04:32:00.000Z",
+        type: "event_msg",
+        payload: {
+          type: "token_count",
+          info: {
+            last_token_usage: {
+              input_tokens: 10,
+              cached_input_tokens: 0,
+              output_tokens: 2,
+              reasoning_output_tokens: 0,
+              total_tokens: 12,
+            },
+          },
+        },
+      },
+      {
+        timestamp: "2026-08-12T04:33:00.000Z",
+        type: "event_msg",
+        payload: { type: "task_complete", turn_id: "outer-turn" },
+      },
+      {
+        timestamp: "2026-08-12T04:35:46.804Z",
+        type: "event_msg",
+        payload: { type: "task_started", turn_id: "enclosing-turn" },
+      },
+      {
+        timestamp: "2026-08-12T04:36:00.000Z",
+        type: "response_item",
+        payload: {
+          type: "reasoning",
+          internal_chat_message_metadata_passthrough: { turn_id: "internal-subturn" },
+        },
+      },
+      {
+        timestamp: "2026-08-12T04:37:00.000Z",
+        type: "event_msg",
+        payload: {
+          type: "token_count",
+          info: {
+            last_token_usage: {
+              input_tokens: 20,
+              cached_input_tokens: 0,
+              output_tokens: 4,
+              reasoning_output_tokens: 0,
+              total_tokens: 24,
+            },
+          },
+        },
+      },
+      {
+        timestamp: "2026-08-12T04:39:10.716Z",
+        type: "event_msg",
+        payload: { type: "turn_aborted", turn_id: "enclosing-turn", completed_at: 1786509550 },
+      },
+    ]
+      .map((record) => JSON.stringify(record))
+      .join("\n") + "\n",
+  );
+
+  const [outerSegment, segment] = await loadSegments(root, [sessionFile]);
+  assert.deepEqual(outerSegment.internal_turn_ids, ["internal-subturn"]);
+  assert.deepEqual(segment.internal_turn_ids, ["internal-subturn"]);
+  assert.equal(outerSegment.finished_at, "2026-08-12T04:33:00.000Z");
+  assert.equal(segment.started_at, "2026-08-12T04:35:46.804Z");
+  assert.equal(segment.finished_at, "2026-08-12T04:39:10.716Z");
+  assert.deepEqual(
+    exactCompletedSegment(
+      { client_turn_id: "internal-subturn", occurred_at: "2026-08-12T04:39:07.934Z" },
+      [outerSegment, segment],
+    ),
+    { segment, ambiguous: false },
+  );
+});
+
 test("remeasurement falls back only to the exact persisted source segment key", () => {
   const target = {
     key: "c:/users/test/.codex/sessions/2026/07/25/child.jsonl#1",

package/templates/.agents/skills/zaip-skill-reconcile-telemetry/scripts/reconcile-telemetry-remeasurement.test.mjs

@@ -3,6 +3,7 @@ import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { after, test } from "node:test";
+import { planExplicitTurnRecovery } from "./reconcile-telemetry-explicit-recovery.mjs";
 import { jsonLines, usageStatus, usageView } from "./reconcile-telemetry-lib.mjs";
 import {
   appendRetrospectiveUsage,
@@ -36,6 +37,58 @@ test("selects completed native Runs for default timing-only backfill", () => {
   assert.deepEqual([...selected], ["RUN-NATIVE"]);
 });
 
+test("explicit recovery requires exact session identity, unused turns, model/effort, and SPEC text", () => {
+  const run = {
+    started: {
+      run_id: "RUN-EXPLICIT",
+      client_thread_id: "/root/agent",
+      model: "gpt-test",
+      reasoning_effort: "medium",
+    },
+    records: [
+      { type: "run.started" },
+      { type: "usage.recorded", event_id: "RUN-EXPLICIT:old", source_segment_key: "old" },
+      { type: "run.finished" },
+    ],
+    usage: [{ event_id: "RUN-EXPLICIT:old", source_segment_key: "old", tokens: { total: 1 } }],
+  };
+  const segment = {
+    key: "session#5",
+    turn_id: "turn-r7qk",
+    internal_turn_ids: ["turn-r7qk"],
+    session_agent_path: "/root/agent",
+    model: "gpt-test",
+    effort: "medium",
+    started_at: "2026-08-22T22:56:58.553Z",
+    finished_at: "2026-08-22T23:05:26.121Z",
+    raw: "SPEC-R7QK observed",
+    usage: [
+      {
+        input_tokens: 8,
+        cached_input_tokens: 3,
+        output_tokens: 2,
+        reasoning_output_tokens: 1,
+        total_tokens: 10,
+      },
+    ],
+  };
+  const plan = planExplicitTurnRecovery({
+    run,
+    segments: [segment],
+    mappings: [{ spec_id: "SPEC-R7QK", turn_id: "turn-r7qk", total: 10, usd: 1, brl: 5 }],
+  });
+  assert.equal(plan.eligible, true);
+  assert.equal(plan.turns[0].tokens.total, 10);
+  assert.equal(
+    planExplicitTurnRecovery({
+      run,
+      segments: [{ ...segment, session_agent_path: "/root/root", key: "old" }],
+      mappings: [{ spec_id: "SPEC-R7QK", turn_id: "turn-r7qk", total: 10, usd: 1, brl: 5 }],
+    }).eligible,
+    false,
+  );
+});
+
 test("inserts a correction before the terminal event under an exclusive lock", async () => {
   const root = await mkdtemp(join(tmpdir(), "zaip-remeasure-append-"));
   roots.push(root);

package/templates/.agents/skills/zaip-skill-release-qualification/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: zaip-skill-release-qualification
+description: Qualify an exact ZAIP release candidate through source-template-package parity, cleanroom, smoke, and candidate-specific evidence; use before a release or publication decision.
+---
+
+# Qualify a release candidate
+
+Use before deciding whether a concrete candidate is ready. It does not publish.
+
+1. Identify the exact candidate revision, version, and intended distribution surface.
+   Do not substitute current working-tree checks for candidate evidence.
+2. Validate framework lock, source-to-public-template parity, generated artifacts,
+   package contents, and version alignment. Treat any source/template/package drift as
+   a failed candidate.
+3. Run the relevant smoke and cleanroom checks against that candidate and preserve the
+   commands, revision, outcomes, and unresolved limits as evidence.
+4. Separate local qualification, remote GitHub CI, registry publication, and formal
+   lifecycle closure. A matching SHA or passing local gate does not prove terminal CI.
+5. Route an explicit push, deploy, or GitHub publication request to
+   `$zaip-skill-github-deploy`; never publish as part of qualification.

package/templates/.agents/skills/zaip-skill-release-qualification/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ZAIP Release Qualification"
+  short_description: "Qualify an exact release candidate without publishing it."
+  default_prompt: "Use $zaip-skill-release-qualification to qualify this exact ZAIP release candidate for source-template-package parity, smoke, and cleanroom evidence."

package/templates/.agents/skills/zaip-skill-review/SKILL.md

@@ -16,3 +16,8 @@ Esta skill é read-only. Um pedido de revisão não autoriza corrigir, concluir
 7. Correções aprovadas exigem autorização separada e começam uma nova Task. Inicie seu Run com `--work-type rework`, relacione somente IDs já conhecidos e deixe ancestral desconhecido como `null`; nunca leia todo o histórico para adivinhar vínculos. A revisão original permanece imutável.
 8. Valide o perfil quantitativo e semântico por mínimos, sem quotas máximas: `lite` exige pelo menos uma validação e uma Evidence, normalmente uma de cada, mas aceita extras legítimos; `standard` exige pelo menos duas validações no perfil base ou três no elevado e ao menos uma Evidence consolidada; `critical` exige três ou mais validações, quality review independente e somente os controles acionados pelos sinais persistidos; SPEC/PRD exigem três ou mais validações e Evidences parentais, matriz, integração e review independente.
 9. Para cleanroom, ambiente representativo ou produção, confira hash do candidato, identidade do ambiente, reviewer independente e Run observado; teste local não promove esses estados.
+10. Leia [o contrato de prova observável](../zaip-skill-change/references/observable-evidence.md) e confronte cenário, expectativa e observação por AC. Diferencie prova confirmada, limitada, pendente, reprovada e modalidade não aplicável; observações não substituem Validation/Evidence aprovadas. Não transfira aprovação entre Runs nem conte uma limitação como prova suficiente.
+
+# Revisão visual condicional
+
+Não aprove UI visual apenas por source ou typecheck: exija render de cada consumidor e bundle servido quando aplicável, além de screenshot real examinado do estado pedido. Após o fallback finito, browser indisponível deixa browser proof como unknown e o AC visual pendente, sem bloquear prova técnica ou trabalho independente. Ausência de impacto visual admite N/A justificado, não ausência de ferramenta.