voratiq 0.1.0-beta.25 → 0.1.0-beta.26

package/README.md

@@ -15,7 +15,7 @@ npm install -g voratiq
 
 - Node 20+
 - git
-- 1+ AI coding agent (Claude [>=2.1.111](https://github.com/anthropics/claude-code?tab=readme-ov-file#get-started), Codex [>=0.122.0](https://github.com/openai/codex?tab=readme-ov-file#quickstart), or Gemini [>=0.31.0](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quick-install))
+- 1+ AI coding agent (Claude [>=2.1.111](https://github.com/anthropics/claude-code?tab=readme-ov-file#get-started), Codex [>=0.122.0](https://github.com/openai/codex?tab=readme-ov-file#quickstart), or Gemini [>=0.40.0](https://github.com/google-gemini/gemini-cli?tab=readme-ov-file#quick-install))
 - macOS: `ripgrep`
 - Linux (Debian/Ubuntu): `bubblewrap`, `socat`, `ripgrep`
 

package/dist/agents/runtime/harness.js

@@ -42,7 +42,7 @@ export async function runSandboxedAgent(input) {
             runtimeManifestPath: paths.runtimeManifestPath,
             promptPath,
             workspacePath: paths.workspacePath,
-            env: staged.env,
+            env: applyProviderRunEnvironmentOverrides(providerId, staged.env),
             environment,
         });
         const denialBackoff = resolveDenialBackoff({
@@ -111,6 +111,15 @@ export async function runSandboxedAgent(input) {
         }
     }
 }
+function applyProviderRunEnvironmentOverrides(providerId, env) {
+    if (providerId !== "gemini") {
+        return env;
+    }
+    return {
+        ...env,
+        GEMINI_CLI_TRUST_WORKSPACE: "true",
+    };
+}
 function resolveDenialBackoff(options) {
     if (options.override) {
         return options.override;

package/dist/commands/list/command.js

@@ -5,6 +5,7 @@ import { readRunRecords, } from "../../domain/run/persistence/adapter.js";
 import { readSpecRecords, } from "../../domain/spec/persistence/adapter.js";
 import { TERMINAL_VERIFICATION_STATUSES } from "../../domain/verify/model/types.js";
 import { readVerificationRecords, } from "../../domain/verify/persistence/adapter.js";
+import { loadVerificationSelectionPolicyOutput } from "../../policy/index.js";
 import { renderInteractiveTranscript } from "../../render/transcripts/interactive.js";
 import { renderInteractiveListTable, renderListTableTranscript, renderMessageListTable, renderReduceListTable, renderRunListTable, renderSpecListTable, renderVerifyListTable, } from "../../render/transcripts/list.js";
 import { formatMessageElapsed, formatMessageRecipientDuration, renderMessageTranscript, } from "../../render/transcripts/message.js";
@@ -13,6 +14,7 @@ import { renderRunTranscript } from "../../render/transcripts/run.js";
 import { formatSpecAgentDuration, formatSpecElapsed, renderSpecTranscript, } from "../../render/transcripts/spec.js";
 import { formatVerifyElapsed, renderVerifyTranscript, } from "../../render/transcripts/verify.js";
 import { formatRenderLifecycleDuration, formatRenderLifecycleRowDuration, } from "../../render/utils/duration.js";
+import { toErrorMessage } from "../../utils/errors.js";
 import { pathExists } from "../../utils/fs.js";
 import { formatTargetDisplay, formatTargetTablePreview, normalizeListDetailSession, normalizeListSession, toListJsonTargetRef, } from "./normalization.js";
 import { getListRecordId } from "./records.js";
@@ -62,7 +64,7 @@ async function executeDetailMode(input) {
         limit: 1,
         predicate: (record) => getRecordId(operator, record) === sessionId,
     });
-    const warnings = query.warnings;
+    const warnings = [...query.warnings];
     const record = query.records[0];
     if (!record) {
         return {
@@ -78,6 +80,15 @@ async function executeDetailMode(input) {
         };
     }
     const detailSession = normalizeListDetailSession(operator, record);
+    const selection = await resolveListDetailVerificationSelection({
+        root: input.root,
+        operator,
+        record,
+        warnings,
+    });
+    const jsonSession = selection
+        ? { ...detailSession, selection }
+        : detailSession;
     return {
         warnings,
         output: renderDetailOutput(operator, detailSession, {
@@ -87,7 +98,7 @@ async function executeDetailMode(input) {
         json: {
             operator,
             mode: "detail",
-            session: toJsonDetailSession(detailSession),
+            session: toJsonDetailSession(jsonSession),
             warnings,
         },
     };
@@ -337,6 +348,7 @@ function toJsonDetailSession(session) {
             ? { description: session.description }
             : {}),
         agents: session.agents.map(toJsonAgent),
+        ...(session.selection ? { selection: session.selection } : {}),
     };
 }
 function toJsonAgent(agent) {
@@ -471,6 +483,52 @@ function getRecordId(operator, record) {
 function formatSessionWarning(warning) {
     return `Ignoring corrupt session ${warning.displayPath}`;
 }
+async function resolveListDetailVerificationSelection(options) {
+    const { root, operator, record, warnings } = options;
+    if (operator !== "verify") {
+        return undefined;
+    }
+    const verificationRecord = record;
+    if (!TERMINAL_VERIFICATION_STATUSES.includes(verificationRecord.status)) {
+        return undefined;
+    }
+    if (verificationRecord.status === "failed" ||
+        verificationRecord.status === "aborted") {
+        return {
+            state: "unresolved",
+            unresolvedReasons: [
+                {
+                    code: "verification_not_succeeded",
+                    status: verificationRecord.status,
+                },
+            ],
+        };
+    }
+    const output = await loadVerificationSelectionPolicyOutput({
+        root,
+        record: verificationRecord,
+    }).catch((error) => {
+        warnings.push(`Verification selection unavailable: ${toErrorMessage(error)}`);
+        return undefined;
+    });
+    if (!output) {
+        return undefined;
+    }
+    if (output.warnings) {
+        warnings.push(...output.warnings);
+    }
+    const decision = output.decision;
+    if (decision.state === "resolvable") {
+        return {
+            state: "resolvable",
+            selectedCanonicalAgentId: decision.selectedCanonicalAgentId,
+        };
+    }
+    return {
+        state: "unresolved",
+        unresolvedReasons: decision.unresolvedReasons,
+    };
+}
 function formatVerifyAgentDuration(agent) {
     return formatRenderLifecycleRowDuration({
         lifecycle: {

package/dist/commands/list/normalization.d.ts

@@ -1,4 +1,4 @@
-import type { ListJsonArtifact, ListJsonChanges, ListJsonTargetRef, ListOperator } from "../../contracts/list.js";
+import type { ListJsonArtifact, ListJsonChanges, ListJsonTargetRef, ListJsonVerificationSelection, ListOperator } from "../../contracts/list.js";
 export { formatTargetDisplay, formatTargetTablePreview, TARGET_TABLE_PREVIEW_LENGTH, } from "../../utils/list-target.js";
 import { type ListRecord } from "./records.js";
 export type ListTargetOperator = ListOperator;
@@ -43,6 +43,7 @@ export interface NormalizedListDetailSession extends NormalizedListSession {
     completedAt?: string;
     workspacePath: string;
     agents: NormalizedListAgent[];
+    selection?: ListJsonVerificationSelection;
 }
 export declare function normalizeListSession(operator: ListOperator, record: ListOperatorRecord): NormalizedListSession;
 export declare function normalizeListDetailSession(operator: ListOperator, record: ListOperatorRecord): NormalizedListDetailSession;

package/dist/configs/agents/defaults.js

@@ -21,7 +21,8 @@ const GEMINI_DEFAULT_ARGV = [
     MODEL_PLACEHOLDER,
     "--output-format",
     "json",
-    "--yolo",
+    "--approval-mode",
+    "yolo",
 ];
 const DEFAULT_ARGV_BY_PROVIDER = {
     claude: CLAUDE_DEFAULT_ARGV,
@@ -177,25 +178,15 @@ const DEFAULT_AGENT_CATALOG_ENTRIES = [
         extraArgs: ["--config", "model_reasoning_effort=xhigh"],
     },
     {
-        id: "gemini-2-5-flash",
+        id: "gemini-3-1-flash-lite-preview",
         provider: "gemini",
-        model: "gemini-2.5-flash",
-    },
-    {
-        id: "gemini-2-5-flash-lite",
-        provider: "gemini",
-        model: "gemini-2.5-flash-lite",
+        model: "gemini-3.1-flash-lite-preview",
     },
     {
         id: "gemini-3-flash-preview",
         provider: "gemini",
         model: "gemini-3-flash-preview",
     },
-    {
-        id: "gemini-2-5-pro",
-        provider: "gemini",
-        model: "gemini-2.5-pro",
-    },
     {
         id: "gemini-3-1-pro-preview",
         provider: "gemini",
@@ -235,9 +226,9 @@ const LITE_AGENT_PRESET_ENTRIES = [
         model: "gpt-5.4-mini",
     },
     {
-        id: "gemini-3-flash-preview",
+        id: "gemini-3-1-flash-lite-preview",
         provider: "gemini",
-        model: "gemini-3-flash-preview",
+        model: "gemini-3.1-flash-lite-preview",
         runOnly: true,
     },
 ];

package/dist/contracts/list.d.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { SelectionDecisionUnresolvedReason } from "../policy/result.js";
 export declare const listOperators: readonly ["spec", "run", "reduce", "verify", "message", "interactive"];
 export declare const listModes: readonly ["summary", "detail"];
 export type ListOperator = (typeof listOperators)[number];
@@ -42,12 +43,24 @@ export interface ListJsonAgent {
     changes?: ListJsonChanges;
     artifacts: ListJsonArtifact[];
 }
+export type ListJsonVerificationSelectionUnresolvedReason = SelectionDecisionUnresolvedReason | {
+    code: "verification_not_succeeded";
+    status: "failed" | "aborted";
+};
+export type ListJsonVerificationSelection = {
+    state: "resolvable";
+    selectedCanonicalAgentId: string;
+} | {
+    state: "unresolved";
+    unresolvedReasons: readonly ListJsonVerificationSelectionUnresolvedReason[];
+};
 export interface ListJsonDetailSession extends ListJsonSessionBase {
     startedAt?: string;
     completedAt?: string;
     workspacePath: string;
     description?: string | null;
     agents: ListJsonAgent[];
+    selection?: ListJsonVerificationSelection;
 }
 export interface ListJsonSummaryOutput {
     operator: ListOperator;
@@ -74,6 +87,98 @@ export declare const listModeSchema: z.ZodEnum<{
     detail: "detail";
     summary: "summary";
 }>;
+export declare const listJsonVerificationSelectionUnresolvedReasonSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    code: z.ZodLiteral<"no_successful_verifiers">;
+    failedVerifierAgentIds: z.ZodArray<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    code: z.ZodLiteral<"verifier_failed">;
+    failedVerifierAgentIds: z.ZodArray<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    code: z.ZodLiteral<"verifier_preference_missing">;
+    verifierAgentId: z.ZodString;
+}, z.core.$loose>, z.ZodObject<{
+    code: z.ZodLiteral<"verifier_preference_unresolved">;
+    verifierAgentId: z.ZodString;
+    preferredCandidateId: z.ZodOptional<z.ZodString>;
+    resolvedPreferredCandidateId: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    code: z.ZodLiteral<"verifier_disagreement">;
+    selections: z.ZodArray<z.ZodObject<{
+        verifierAgentId: z.ZodString;
+        selectedCanonicalAgentId: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>, z.ZodObject<{
+    code: z.ZodLiteral<"selector_unresolved">;
+    selector: z.ZodString;
+    availableCanonicalAgentIds: z.ZodArray<z.ZodString>;
+    availableAliases: z.ZodArray<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    code: z.ZodLiteral<"selector_ambiguous">;
+    selector: z.ZodString;
+    resolutions: z.ZodArray<z.ZodObject<{
+        sourceId: z.ZodString;
+        selectedCanonicalAgentId: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>, z.ZodObject<{
+    code: z.ZodLiteral<"selected_candidate_failed_programmatic">;
+    selectedCanonicalAgentId: z.ZodString;
+    eligibleCanonicalAgentIds: z.ZodArray<z.ZodString>;
+}, z.core.$loose>, z.ZodObject<{
+    code: z.ZodLiteral<"verification_not_succeeded">;
+    status: z.ZodEnum<{
+        failed: "failed";
+        aborted: "aborted";
+    }>;
+}, z.core.$loose>], "code">;
+export declare const listJsonVerificationSelectionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    state: z.ZodLiteral<"resolvable">;
+    selectedCanonicalAgentId: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    state: z.ZodLiteral<"unresolved">;
+    unresolvedReasons: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        code: z.ZodLiteral<"no_successful_verifiers">;
+        failedVerifierAgentIds: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        code: z.ZodLiteral<"verifier_failed">;
+        failedVerifierAgentIds: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        code: z.ZodLiteral<"verifier_preference_missing">;
+        verifierAgentId: z.ZodString;
+    }, z.core.$loose>, z.ZodObject<{
+        code: z.ZodLiteral<"verifier_preference_unresolved">;
+        verifierAgentId: z.ZodString;
+        preferredCandidateId: z.ZodOptional<z.ZodString>;
+        resolvedPreferredCandidateId: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        code: z.ZodLiteral<"verifier_disagreement">;
+        selections: z.ZodArray<z.ZodObject<{
+            verifierAgentId: z.ZodString;
+            selectedCanonicalAgentId: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>, z.ZodObject<{
+        code: z.ZodLiteral<"selector_unresolved">;
+        selector: z.ZodString;
+        availableCanonicalAgentIds: z.ZodArray<z.ZodString>;
+        availableAliases: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        code: z.ZodLiteral<"selector_ambiguous">;
+        selector: z.ZodString;
+        resolutions: z.ZodArray<z.ZodObject<{
+            sourceId: z.ZodString;
+            selectedCanonicalAgentId: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>, z.ZodObject<{
+        code: z.ZodLiteral<"selected_candidate_failed_programmatic">;
+        selectedCanonicalAgentId: z.ZodString;
+        eligibleCanonicalAgentIds: z.ZodArray<z.ZodString>;
+    }, z.core.$loose>, z.ZodObject<{
+        code: z.ZodLiteral<"verification_not_succeeded">;
+        status: z.ZodEnum<{
+            failed: "failed";
+            aborted: "aborted";
+        }>;
+    }, z.core.$loose>], "code">>;
+}, z.core.$strict>], "state">;
 export declare const listJsonOutputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     operator: z.ZodEnum<{
         message: "message";
@@ -175,6 +280,55 @@ export declare const listJsonOutputSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
                 path: z.ZodString;
             }, z.core.$loose>>;
         }, z.core.$loose>>;
+        selection: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            state: z.ZodLiteral<"resolvable">;
+            selectedCanonicalAgentId: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            state: z.ZodLiteral<"unresolved">;
+            unresolvedReasons: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                code: z.ZodLiteral<"no_successful_verifiers">;
+                failedVerifierAgentIds: z.ZodArray<z.ZodString>;
+            }, z.core.$loose>, z.ZodObject<{
+                code: z.ZodLiteral<"verifier_failed">;
+                failedVerifierAgentIds: z.ZodArray<z.ZodString>;
+            }, z.core.$loose>, z.ZodObject<{
+                code: z.ZodLiteral<"verifier_preference_missing">;
+                verifierAgentId: z.ZodString;
+            }, z.core.$loose>, z.ZodObject<{
+                code: z.ZodLiteral<"verifier_preference_unresolved">;
+                verifierAgentId: z.ZodString;
+                preferredCandidateId: z.ZodOptional<z.ZodString>;
+                resolvedPreferredCandidateId: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>, z.ZodObject<{
+                code: z.ZodLiteral<"verifier_disagreement">;
+                selections: z.ZodArray<z.ZodObject<{
+                    verifierAgentId: z.ZodString;
+                    selectedCanonicalAgentId: z.ZodString;
+                }, z.core.$loose>>;
+            }, z.core.$loose>, z.ZodObject<{
+                code: z.ZodLiteral<"selector_unresolved">;
+                selector: z.ZodString;
+                availableCanonicalAgentIds: z.ZodArray<z.ZodString>;
+                availableAliases: z.ZodArray<z.ZodString>;
+            }, z.core.$loose>, z.ZodObject<{
+                code: z.ZodLiteral<"selector_ambiguous">;
+                selector: z.ZodString;
+                resolutions: z.ZodArray<z.ZodObject<{
+                    sourceId: z.ZodString;
+                    selectedCanonicalAgentId: z.ZodString;
+                }, z.core.$loose>>;
+            }, z.core.$loose>, z.ZodObject<{
+                code: z.ZodLiteral<"selected_candidate_failed_programmatic">;
+                selectedCanonicalAgentId: z.ZodString;
+                eligibleCanonicalAgentIds: z.ZodArray<z.ZodString>;
+            }, z.core.$loose>, z.ZodObject<{
+                code: z.ZodLiteral<"verification_not_succeeded">;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    aborted: "aborted";
+                }>;
+            }, z.core.$loose>], "code">>;
+        }, z.core.$strict>], "state">>;
     }, z.core.$loose>>;
     warnings: z.ZodArray<z.ZodString>;
 }, z.core.$loose>], "mode">;

package/dist/contracts/list.js

@@ -66,6 +66,96 @@ const listJsonAgentSchema = z
     artifacts: z.array(listJsonArtifactSchema),
 })
     .passthrough();
+const listJsonVerifierAgreementSelectionSchema = z
+    .object({
+    verifierAgentId: z.string(),
+    selectedCanonicalAgentId: z.string(),
+})
+    .passthrough();
+const listJsonSelectorResolutionMatchSchema = z
+    .object({
+    sourceId: z.string(),
+    selectedCanonicalAgentId: z.string(),
+})
+    .passthrough();
+export const listJsonVerificationSelectionUnresolvedReasonSchema = z.discriminatedUnion("code", [
+    z
+        .object({
+        code: z.literal("no_successful_verifiers"),
+        failedVerifierAgentIds: z.array(z.string()),
+    })
+        .passthrough(),
+    z
+        .object({
+        code: z.literal("verifier_failed"),
+        failedVerifierAgentIds: z.array(z.string()),
+    })
+        .passthrough(),
+    z
+        .object({
+        code: z.literal("verifier_preference_missing"),
+        verifierAgentId: z.string(),
+    })
+        .passthrough(),
+    z
+        .object({
+        code: z.literal("verifier_preference_unresolved"),
+        verifierAgentId: z.string(),
+        preferredCandidateId: z.string().optional(),
+        resolvedPreferredCandidateId: z.string().optional(),
+    })
+        .passthrough(),
+    z
+        .object({
+        code: z.literal("verifier_disagreement"),
+        selections: z.array(listJsonVerifierAgreementSelectionSchema),
+    })
+        .passthrough(),
+    z
+        .object({
+        code: z.literal("selector_unresolved"),
+        selector: z.string(),
+        availableCanonicalAgentIds: z.array(z.string()),
+        availableAliases: z.array(z.string()),
+    })
+        .passthrough(),
+    z
+        .object({
+        code: z.literal("selector_ambiguous"),
+        selector: z.string(),
+        resolutions: z.array(listJsonSelectorResolutionMatchSchema),
+    })
+        .passthrough(),
+    z
+        .object({
+        code: z.literal("selected_candidate_failed_programmatic"),
+        selectedCanonicalAgentId: z.string(),
+        eligibleCanonicalAgentIds: z.array(z.string()),
+    })
+        .passthrough(),
+    z
+        .object({
+        code: z.literal("verification_not_succeeded"),
+        status: z.enum(["failed", "aborted"]),
+    })
+        .passthrough(),
+]);
+const listJsonResolvableVerificationSelectionSchema = z
+    .object({
+    state: z.literal("resolvable"),
+    selectedCanonicalAgentId: z.string(),
+})
+    .strict();
+const listJsonUnresolvedVerificationSelectionSchema = z
+    .object({
+    state: z.literal("unresolved"),
+    unresolvedReasons: z.array(listJsonVerificationSelectionUnresolvedReasonSchema),
+})
+    .strict();
+export const listJsonVerificationSelectionSchema = z.discriminatedUnion("state", [
+    listJsonResolvableVerificationSelectionSchema,
+    listJsonUnresolvedVerificationSelectionSchema,
+]);
 const listJsonDetailSessionSchema = listJsonSessionBaseSchema
     .extend({
     startedAt: z.string().optional(),
@@ -73,6 +163,7 @@ const listJsonDetailSessionSchema = listJsonSessionBaseSchema
     workspacePath: z.string(),
     description: z.string().nullable().optional(),
     agents: z.array(listJsonAgentSchema),
+    selection: listJsonVerificationSelectionSchema.optional(),
 })
     .passthrough();
 const listJsonSummaryOutputSchema = z

package/dist/domain/interactive/prompt.d.ts

@@ -1,3 +1,3 @@
 import type { ToolAttachmentStatus } from "./model/types.js";
-export declare const FIRST_PARTY_ATTACHED_LAUNCH_PROMPT: "Voratiq MCP tools are attached to this repository: voratiq_spec, voratiq_run, voratiq_reduce, voratiq_verify, voratiq_message, voratiq_list, and voratiq_apply. For Voratiq session history and workflow actions, prefer these tools over bash, search, or direct file reads. Read the guide resource at voratiq://guide for the full operator reference, workflow composition, and usage guidance.";
+export declare const FIRST_PARTY_ATTACHED_LAUNCH_PROMPT: "Voratiq MCP tools are attached to this repository: voratiq_spec, voratiq_run, voratiq_reduce, voratiq_verify, voratiq_message, voratiq_list, and voratiq_apply. Your role is to orchestrate Voratiq workflows for the user through these tools. Use Voratiq tools for workflow state and actions unless explicitly instructed otherwise, preserving sessions and apply outcomes instead of switching to local edits, replacement stages, or manual apply paths; read voratiq://guide for the operating contract, discipline rules, workflow composition, and operator reference.";
 export declare function resolveFirstPartyLaunchPrompt(toolAttachmentStatus: ToolAttachmentStatus): string | undefined;

package/dist/domain/interactive/prompt.js

@@ -1,4 +1,4 @@
-export const FIRST_PARTY_ATTACHED_LAUNCH_PROMPT = "Voratiq MCP tools are attached to this repository: voratiq_spec, voratiq_run, voratiq_reduce, voratiq_verify, voratiq_message, voratiq_list, and voratiq_apply. For Voratiq session history and workflow actions, prefer these tools over bash, search, or direct file reads. Read the guide resource at voratiq://guide for the full operator reference, workflow composition, and usage guidance.";
+export const FIRST_PARTY_ATTACHED_LAUNCH_PROMPT = "Voratiq MCP tools are attached to this repository: voratiq_spec, voratiq_run, voratiq_reduce, voratiq_verify, voratiq_message, voratiq_list, and voratiq_apply. Your role is to orchestrate Voratiq workflows for the user through these tools. Use Voratiq tools for workflow state and actions unless explicitly instructed otherwise, preserving sessions and apply outcomes instead of switching to local edits, replacement stages, or manual apply paths; read voratiq://guide for the operating contract, discipline rules, workflow composition, and operator reference.";
 export function resolveFirstPartyLaunchPrompt(toolAttachmentStatus) {
     if (toolAttachmentStatus !== "attached") {
         return undefined;

package/dist/domain/message/model/types.d.ts

@@ -42,6 +42,8 @@ export declare const messageRecipientEntrySchema: z.ZodObject<{
         output_tokens: z.ZodOptional<z.ZodNumber>;
         cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
         cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+        cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+        cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
         input_tokens: z.ZodOptional<z.ZodNumber>;
         cached_input_tokens: z.ZodOptional<z.ZodNumber>;
@@ -108,6 +110,8 @@ export declare const messageRecordSchema: z.ZodObject<{
             output_tokens: z.ZodOptional<z.ZodNumber>;
             cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
             cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+            cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+            cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>, z.ZodObject<{
             input_tokens: z.ZodOptional<z.ZodNumber>;
             cached_input_tokens: z.ZodOptional<z.ZodNumber>;

package/dist/domain/reduce/model/types.d.ts

@@ -39,6 +39,8 @@ export declare const reductionRecordReducerSchema: z.ZodObject<{
         output_tokens: z.ZodOptional<z.ZodNumber>;
         cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
         cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+        cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+        cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
         input_tokens: z.ZodOptional<z.ZodNumber>;
         cached_input_tokens: z.ZodOptional<z.ZodNumber>;
@@ -100,6 +102,8 @@ export declare const reductionRecordSchema: z.ZodObject<{
             output_tokens: z.ZodOptional<z.ZodNumber>;
             cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
             cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+            cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+            cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>, z.ZodObject<{
             input_tokens: z.ZodOptional<z.ZodNumber>;
             cached_input_tokens: z.ZodOptional<z.ZodNumber>;

package/dist/domain/run/model/types.d.ts

@@ -349,6 +349,8 @@ export declare const claudeExtractedTokenUsageSchema: z.ZodObject<{
     output_tokens: z.ZodOptional<z.ZodNumber>;
     cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
     cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+    cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+    cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>;
 export type ClaudeExtractedTokenUsage = z.infer<typeof claudeExtractedTokenUsageSchema>;
 export declare const codexExtractedTokenUsageSchema: z.ZodObject<{
@@ -374,6 +376,8 @@ export declare const extractedTokenUsageSchemaByProvider: {
         output_tokens: z.ZodOptional<z.ZodNumber>;
         cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
         cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+        cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+        cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
     readonly codex: z.ZodObject<{
         input_tokens: z.ZodOptional<z.ZodNumber>;
@@ -396,6 +400,8 @@ export declare const extractedTokenUsageSchema: z.ZodUnion<readonly [z.ZodObject
     output_tokens: z.ZodOptional<z.ZodNumber>;
     cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
     cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+    cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+    cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strict>, z.ZodObject<{
     input_tokens: z.ZodOptional<z.ZodNumber>;
     cached_input_tokens: z.ZodOptional<z.ZodNumber>;
@@ -459,6 +465,8 @@ export declare const agentInvocationRecordSchema: z.ZodObject<{
         output_tokens: z.ZodOptional<z.ZodNumber>;
         cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
         cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+        cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+        cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
         input_tokens: z.ZodOptional<z.ZodNumber>;
         cached_input_tokens: z.ZodOptional<z.ZodNumber>;
@@ -654,6 +662,8 @@ export declare const runRecordSchema: z.ZodObject<{
             output_tokens: z.ZodOptional<z.ZodNumber>;
             cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
             cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+            cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+            cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>, z.ZodObject<{
             input_tokens: z.ZodOptional<z.ZodNumber>;
             cached_input_tokens: z.ZodOptional<z.ZodNumber>;

package/dist/domain/run/model/types.js

@@ -137,6 +137,8 @@ export const claudeExtractedTokenUsageSchema = withAtLeastOneUsageField({
     output_tokens: billingTokenCountSchema.optional(),
     cache_read_input_tokens: billingTokenCountSchema.optional(),
     cache_creation_input_tokens: billingTokenCountSchema.optional(),
+    cache_creation_ephemeral_5m_input_tokens: billingTokenCountSchema.optional(),
+    cache_creation_ephemeral_1h_input_tokens: billingTokenCountSchema.optional(),
 });
 export const codexExtractedTokenUsageSchema = withAtLeastOneUsageField({
     input_tokens: billingTokenCountSchema.optional(),

package/dist/domain/spec/model/types.d.ts

@@ -21,6 +21,8 @@ export declare const specAgentEntrySchema: z.ZodObject<{
         output_tokens: z.ZodOptional<z.ZodNumber>;
         cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
         cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+        cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+        cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
         input_tokens: z.ZodOptional<z.ZodNumber>;
         cached_input_tokens: z.ZodOptional<z.ZodNumber>;
@@ -74,6 +76,8 @@ export declare const specRecordSchema: z.ZodObject<{
             output_tokens: z.ZodOptional<z.ZodNumber>;
             cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
             cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+            cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+            cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>, z.ZodObject<{
             input_tokens: z.ZodOptional<z.ZodNumber>;
             cached_input_tokens: z.ZodOptional<z.ZodNumber>;

package/dist/domain/verify/model/types.d.ts

@@ -98,6 +98,8 @@ export declare const verificationMethodResultRefSchema: z.ZodObject<{
         output_tokens: z.ZodOptional<z.ZodNumber>;
         cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
         cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+        cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+        cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>, z.ZodObject<{
         input_tokens: z.ZodOptional<z.ZodNumber>;
         cached_input_tokens: z.ZodOptional<z.ZodNumber>;
@@ -368,6 +370,8 @@ export declare const verificationRecordSchema: z.ZodObject<{
             output_tokens: z.ZodOptional<z.ZodNumber>;
             cache_read_input_tokens: z.ZodOptional<z.ZodNumber>;
             cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
+            cache_creation_ephemeral_5m_input_tokens: z.ZodOptional<z.ZodNumber>;
+            cache_creation_ephemeral_1h_input_tokens: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>, z.ZodObject<{
             input_tokens: z.ZodOptional<z.ZodNumber>;
             cached_input_tokens: z.ZodOptional<z.ZodNumber>;

package/dist/interactive/providers/launch.js

@@ -144,8 +144,12 @@ function sanitizeGeminiArgs(agent) {
             index += 1;
             continue;
         }
-        if (token === "--yolo") {
-            continue;
+        if (token === "--approval-mode") {
+            const next = agent.argv[index + 1] ?? "";
+            if (next === "yolo") {
+                index += 1;
+                continue;
+            }
         }
         sanitized.push(token);
     }

package/dist/mcp/server.js

@@ -69,7 +69,7 @@ const toolSpecs = [
     {
         name: "voratiq_run",
         operator: "run",
-        description: "Execute a Voratiq spec session and create a run with agent outputs and artifacts.",
+        description: "Execute a Voratiq spec and create a recorded run session with agent outputs and artifacts.",
         inputSchemaSource: externalRunExecutionInputSchema,
         buildArgs: (input) => buildRunExecutionArgs(input),
         outputContract: "execution",
@@ -77,7 +77,7 @@ const toolSpecs = [
     {
         name: "voratiq_reduce",
         operator: "reduce",
-        description: "Reduce a set of Voratiq artifacts into a summarized output for comparison or follow-on work.",
+        description: "Synthesize Voratiq artifacts into a reduced output for comparison or follow-on work.",
         inputSchemaSource: externalReduceExecutionInputSchema,
         buildArgs: (input) => buildReduceExecutionArgs(input),
         outputContract: "execution",
@@ -85,7 +85,7 @@ const toolSpecs = [
     {
         name: "voratiq_verify",
         operator: "verify",
-        description: "Verify a Voratiq spec, run, reduction, or message session and record the evaluation result.",
+        description: "Evaluate a Voratiq spec, run, reduction, or message session and record a structured verdict.",
         inputSchemaSource: externalVerifyExecutionInputSchema,
         buildArgs: (input) => buildVerifyExecutionArgs(input),
         outputContract: "execution",
@@ -101,7 +101,7 @@ const toolSpecs = [
     {
         name: "voratiq_apply",
         operator: "apply",
-        description: "Apply an accepted Voratiq run diff into the current working tree.",
+        description: "Apply an accepted Voratiq run diff into the current working tree and record applyStatus.",
         inputSchemaSource: externalApplyExecutionInputSchema,
         buildArgs: (input) => buildApplyExecutionArgs(input),
         outputContract: "execution",
@@ -109,7 +109,7 @@ const toolSpecs = [
     {
         name: "voratiq_list",
         operator: "list",
-        description: "Inspect recorded Voratiq sessions for one operator (`spec`, `run`, `reduce`, `verify`, `message`, or `interactive`) in summary or detail scope.",
+        description: "Inspect or poll recorded Voratiq sessions for one operator (`spec`, `run`, `reduce`, `verify`, `message`, or `interactive`) in summary or detail scope.",
         inputSchemaSource: mcpListInspectionInputSchema,
         mcpInputSchema: createListMcpInputSchema(),
         buildArgs: (input) => buildListInspectionArgs(input),
@@ -124,65 +124,70 @@ const toolDefinitions = toolSpecs.map((tool) => ({
 export const VORATIQ_GUIDE_RESOURCE_URI = "voratiq://guide";
 const VORATIQ_GUIDE_RESOURCE_CONTENT = `# Voratiq Operator Guide
 
-Voratiq is a workflow system built around composable operators that launch, evaluate, and manage multi-agent work against a repository. It gives interactive agents a structured way to delegate coding tasks, inspect recorded state, verify outcomes, and apply accepted changes without doing all of that inline.
+## Operating Contract
 
-## Operator Classes
+Voratiq is a stateful workflow control plane for multi-agent work in a repository. Its records connect session state, verification decisions, artifacts, orchestration choices, and accepted work across stages.
 
-Voratiq operators fall into two main classes:
+Your role is to orchestrate Voratiq workflows for the user through Voratiq tools. This means using Voratiq tools for workflow state and actions and preserving sessions and apply outcomes.
 
-- **Swarm operators** dispatch agents to produce, synthesize, or evaluate work: spec, run, reduce, verify, message
-- **Control operators** inspect state or mutate accepted outcomes: apply, list
+- **Voratiq state is authoritative.** Sessions, verifier decisions, reductions, unresolved outcomes, and apply records are durable workflow state. A terminal session status means a stage stopped; the recorded output still needs interpretation before the next stage.
+- **Orchestration controls define meaning.** **agentIds**, **profile**, and **maxParallel** shape which swarm produced the result and how that result should be understood.
+- **Artifacts carry lineage.** Artifact paths are workflow outputs with a producing operator, role, and surrounding decision state. The producing context determines whether an artifact is suitable input for another operator.
+- **Apply through Voratiq.** **voratiq_apply** materializes an accepted run candidate and records **applyStatus**, including which agent result was accepted.
 
-## Swarm Operators
+## Discipline Rules
 
-**spec** – Drafts or refines a specification for a task from a description, an existing spec, or related repository context. Launches one or more spec agents and records their outputs as a spec session.
+Unless explicitly instructed otherwise:
 
-**run** – Executes a spec session by launching run agents that read the spec, work against a sandboxed workspace, and produce artifacts including diffs and transcripts. Records a run session.
+- **Keep workflow actions in Voratiq.** Do not edit repository files, manually patch diffs, cherry-pick, or materialize changes outside the recorded run/apply path while a Voratiq workflow is active.
+- **Respect stage boundaries.** Do not advance from spec to run, run to apply, or unresolved verification to rerun/apply until the relevant session state is terminal and understood; use **voratiq_list** and bring unresolved decisions back to the user.
+- **Do not duplicate active swarm work.** If a spec, run, reduce, verify, or message session is queued or running, poll it with **voratiq_list** instead of launching a replacement because it is slow or unclear.
+- **Leave orchestration controls unset by default.** Do not pass **agentIds**, **profile**, or **maxParallel** unless the user explicitly asks for them. **maxParallel** limits concurrency; it does not choose a smaller swarm.
+- **Apply accepted runs through Voratiq.** Use **voratiq_apply** so **applyStatus** records the accepted agent. Surface conflicts, dirty state, or base mismatch instead of bypassing apply.
 
-**reduce** – Summarizes artifacts from a spec, run, or message session into a single reduced output suitable for comparison or follow-on work. Records a reduce session.
+## Operators
 
-**verify** – Evaluates a spec, run, reduction, or message session and records a structured verdict. This is Voratiq's main decision operator: use it to compare outputs, choose stronger candidates, and decide whether work should be applied, inspected further, rerun, or redirected.
+Swarm operators create recorded sessions and may acknowledge before finishing:
 
-**message** – Sends an isolated prompt to one or more agents and persists each reply independently as a message session. Use for standalone questions, reviews, or exploration that does not require a full spec/run workflow.
+- **spec** drafts or refines a task specification.
+- **run** executes a spec and records agent outputs, diffs, and transcripts.
+- **reduce** synthesizes artifacts from a spec, run, verify, or message session for comparison or follow-on work.
+- **verify** records a structured verdict over a spec, run, reduction, or message session.
+- **message** sends an isolated prompt to agents and records independent replies.
 
-## Control Operators
+Control operators inspect or materialize recorded state:
 
-**list** – Lists or inspects recorded sessions for a given operator. This is the primary way to inspect swarm sessions; use it to poll progress, retrieve session IDs, and inspect recorded workflow state.
-
-**apply** – Applies an accepted run diff into the current working tree. Synchronous and non-durable; only invoke after verifying that the target run is in an acceptable state.
+- **list** is the primary control plane for session history, progress polling, and detail inspection.
+- **apply** materializes an accepted run diff into the working tree and records the apply outcome.
 
 ## Workflow Composition
 
-Operators compose into many workflow shapes rather than one required path. Common patterns include: using message for standalone exploration or review; using spec → verify to compare candidate specs before execution; using spec → run when a task needs structured execution; using run → verify to choose among competing implementations; using reduce when multiple outputs need synthesis before a decision; and using verify whenever a workflow needs a structured recommendation instead of ad hoc judgment. The list operator can be called at any point to inspect recorded state across all operators.
-
-## Swarm Session Behavior
+Operators compose into different workflow shapes. Use **message** for standalone exploration, **spec -> verify** to compare candidate specs, **spec -> run** for structured execution, **run -> verify** to choose among implementations, and **reduce** when several artifacts need synthesis before a decision. A typical accepted-change path is **spec -> verify -> run -> verify -> apply**.
 
-The five swarm operators are spec, run, reduce, verify, and message. Each one creates a recorded session and may return before the session is finished. Once a session has been created, treat that session as the unit of work. A returned sessionId means the work has been launched, not completed. Use voratiq_list to inspect active sessions.
+Keep one workflow objective per sequence. Before moving to the next stage, inspect the recorded state with **voratiq_list**. Queued, running, timed-out, or unclear sessions are normally handled by polling the recorded session; launching another swarm stage creates a separate workflow event.
 
-## Status Interpretation
+## Sessions, Status, and Polling
 
-Session status is primary; recipient status is supporting detail.
+The session is the unit of work. A returned **sessionId** means work was launched, not completed. **queued** and **running** are expected latency states. Mixed recipient states are supporting detail and do not override session status.
 
-- **queued** means the session has been accepted and recorded but its work has not started yet.
-- **running** means the session is active and remains the canonical in-flight unit of work.
-- **succeeded** means the session reached a successful terminal state; inspect its outputs and decide what should happen next.
-- **failed** means the session reached a terminal failure state.
-- **unresolved** means the session reached a terminal state without a clear winner or confident decision.
+Terminal statuses still require interpretation:
 
-Mixed recipient states do not imply session failure. Some recipients may fail while others continue running, and the session remains active until its session status becomes terminal.
+- **succeeded** means the operator produced its recorded output; inspect it in context before acting.
+- **failed** means the stage ended in failure.
+- **unresolved** means verification or selection ended without a clear winner or confident decision; review the evidence and decide the next step from that recorded state.
 
-## extraContext Contract
+Advance only after the verification state you depend on is terminal and understood.
 
-The extraContext field accepts an array of file paths pointing to additional readable files staged alongside the operator workspace. Pass file paths only — not raw text content, and not paths to files that operators already see by default (such as standard repository context). Passing raw content or redundant paths increases token usage without providing new information.
+## Lineage and Inputs
 
-## maxParallel Semantics
+Treat artifact paths as typed workflow inputs. **run** expects a spec input. **reduce** and **verify** evaluate recorded sessions or artifacts in their producing context. A reduction can summarize evidence for follow-on work, but its role still matters when carrying it into another operator.
 
-The maxParallel field controls the maximum number of agent recipients running in parallel for an operator invocation. Set it deliberately: it directly affects cost and latency. Higher values increase concurrency but also increase total token expenditure and can create contention. Do not treat maxParallel as a free dial to increase throughput without modeling the downstream cost and latency impact.
+The **extraContext** field accepts file paths to additional readable files staged beside the operator workspace. Pass paths only, not raw text, and avoid files the operator already receives by default.
 
-## Key Discipline Rules
+## Orchestration Controls
 
-Commit to one workflow objective per session; do not interleave unrelated operator calls in the same sequence. Wait for stage boundaries before acting on results: read voratiq_list output before proceeding from one stage to the next. Use voratiq_list as the primary control plane for inspecting recorded state rather than reading session files directly.`;
-const VORATIQ_MCP_SERVER_INSTRUCTIONS = "Voratiq tools operate on Voratiq workflow state in the current repository. Use voratiq_list for questions about recent or specific spec, run, reduce, verify, message, or interactive sessions. The swarm operators (voratiq_spec, voratiq_run, voratiq_reduce, voratiq_verify, voratiq_message) create recorded sessions and may acknowledge before finishing; once launched, treat the session as the unit of work. If a swarm call times out or returns a non-terminal status, inspect progress with voratiq_list instead of retrying. Use voratiq_apply for synchronous control actions. Prefer these tools over shell inspection when the task is about Voratiq workflow history or state.";
+**agentIds**, **profile**, and **maxParallel** are semantic inputs. They determine which agents are compared and how the swarm result should be read. Use them when intentionally selecting participants, a profile, or concurrency. **maxParallel** also affects cost, latency, and contention, so set it deliberately.`;
+const VORATIQ_MCP_SERVER_INSTRUCTIONS = "Voratiq MCP tools operate on durable workflow state. Your role is to orchestrate Voratiq workflows for the user through Voratiq MCP tools. Use voratiq_list to inspect and poll sessions. Unless explicitly instructed otherwise: keep workflow actions in Voratiq; wait for terminal stage state and bring unresolved decisions back to the user; do not launch replacement stages for queued/running work; do not pass agentIds, profile, or maxParallel without an explicit user request; use voratiq_apply for accepted runs so applyStatus records the accepted agent, and surface blockers instead of bypassing. Read voratiq://guide for the full contract.";
 const toolSpecsByName = new Map(toolSpecs.map((tool) => [tool.name, tool]));
 export function getVoratiqMcpToolDefinitions() {
     return toolDefinitions;
@@ -267,7 +272,7 @@ export function createVoratiqMcpRequestHandler(options = {}) {
                         {
                             uri: VORATIQ_GUIDE_RESOURCE_URI,
                             name: "Voratiq Operator Guide",
-                            description: "Complete reference for Voratiq operators, workflow composition, swarm-session behavior, extraContext contract, and maxParallel semantics.",
+                            description: "Operating contract and reference for Voratiq state, orchestration controls, artifact lineage, operators, polling, and apply attribution.",
                             mimeType: "text/plain",
                         },
                     ],

package/dist/workspace/chat/usage-extractor.d.ts

@@ -18,7 +18,7 @@ interface ExtractClaudeChatUsageFromJsonlOptions {
     content: string;
     modelId: string;
 }
-interface ExtractGeminiChatUsageFromJsonOptions {
+interface ExtractGeminiChatUsageFromJsonlOptions {
     artifactPath: string;
     content: string;
     modelId: string;
@@ -26,5 +26,5 @@ interface ExtractGeminiChatUsageFromJsonOptions {
 export declare function extractChatUsageFromArtifact(options: ExtractChatUsageArtifactOptions): Promise<ChatUsageExtractionResult>;
 export declare function extractCodexChatUsageFromJsonl(options: ExtractCodexChatUsageFromJsonlOptions): ChatUsageExtractionResult;
 export declare function extractClaudeChatUsageFromJsonl(options: ExtractClaudeChatUsageFromJsonlOptions): ChatUsageExtractionResult;
-export declare function extractGeminiChatUsageFromJson(options: ExtractGeminiChatUsageFromJsonOptions): ChatUsageExtractionResult;
+export declare function extractGeminiChatUsageFromJsonl(options: ExtractGeminiChatUsageFromJsonlOptions): ChatUsageExtractionResult;
 export {};

package/dist/workspace/chat/usage-extractor.js

@@ -38,7 +38,7 @@ export async function extractChatUsageFromArtifact(options) {
             message: `Usage extraction is not implemented for provider \`${providerId}\` yet.`,
         });
     }
-    if (format !== providerShape.artifactFormat) {
+    if (!isProviderArtifactFormatSupported(providerId, format)) {
         const providerLabel = formatProviderLabel(providerId);
         return buildUnavailableResult({
             reason: "unsupported_provider",
@@ -63,7 +63,7 @@ export async function extractChatUsageFromArtifact(options) {
                 modelId,
             });
         case "gemini":
-            return extractGeminiChatUsageFromJson({
+            return extractGeminiChatUsageFromJsonl({
                 artifactPath,
                 content,
                 modelId,
@@ -110,16 +110,6 @@ export function extractCodexChatUsageFromJsonl(options) {
         });
     }
     const latestTokenCountEvent = tokenCountEvents.at(-1);
-    if (!latestTokenCountEvent) {
-        return buildUnavailableResult({
-            reason: "missing",
-            artifactPath,
-            format: "jsonl",
-            providerId: "codex",
-            modelId,
-            message: "No Codex token_count usage events were found in chat.jsonl.",
-        });
-    }
     const totalTokenUsage = asRecord(latestTokenCountEvent.info.total_token_usage);
     if (!totalTokenUsage) {
         return buildUnavailableResult({
@@ -193,7 +183,14 @@ export function extractClaudeChatUsageFromJsonl(options) {
         });
     }
     const normalizedUsage = [];
+    const seenResponseKeys = new Set();
     for (const usageMessage of usageMessages) {
+        if (usageMessage.responseKey) {
+            if (seenResponseKeys.has(usageMessage.responseKey)) {
+                continue;
+            }
+            seenResponseKeys.add(usageMessage.responseKey);
+        }
         const usageRecord = asRecord(usageMessage.usage);
         if (!usageRecord) {
             return buildUnavailableResult({
@@ -241,44 +238,69 @@ export function extractClaudeChatUsageFromJsonl(options) {
         tokenUsage: usage,
     };
 }
-export function extractGeminiChatUsageFromJson(options) {
+export function extractGeminiChatUsageFromJsonl(options) {
     const { artifactPath, content, modelId } = options;
-    let parsedRoot;
-    try {
-        parsedRoot = JSON.parse(content);
-    }
-    catch (error) {
-        return buildUnavailableResult({
-            reason: "malformed",
-            artifactPath,
-            format: "json",
-            providerId: "gemini",
-            modelId,
-            message: `Invalid JSON: ${error instanceof Error ? error.message : String(error)}`,
-        });
-    }
-    const root = asRecord(parsedRoot);
-    if (!root) {
-        return buildUnavailableResult({
-            reason: "malformed",
-            artifactPath,
-            format: "json",
-            providerId: "gemini",
-            modelId,
-            message: "Gemini chat artifact must be a JSON object.",
-        });
+    const tokensPayloadsByResponseId = new Map();
+    const tokensPayloadsWithoutResponseId = [];
+    const lines = content.split(/\r?\n/u);
+    for (const [index, rawLine] of lines.entries()) {
+        const trimmed = rawLine.trim();
+        if (trimmed.length === 0) {
+            continue;
+        }
+        let parsedLine;
+        try {
+            parsedLine = JSON.parse(trimmed);
+        }
+        catch (error) {
+            return buildUnavailableResult({
+                reason: "malformed",
+                artifactPath,
+                format: "jsonl",
+                providerId: "gemini",
+                modelId,
+                message: `Invalid JSONL at line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+        const root = asRecord(parsedLine);
+        if (!root || !("tokens" in root)) {
+            continue;
+        }
+        const tokensPayload = {
+            location: `line ${index + 1}.tokens`,
+            tokens: root.tokens,
+        };
+        const responseId = typeof root.id === "string" ? root.id.trim() : "";
+        if (responseId.length > 0) {
+            tokensPayloadsByResponseId.set(responseId, tokensPayload);
+        }
+        else {
+            tokensPayloadsWithoutResponseId.push(tokensPayload);
+        }
     }
-    const tokensPayloads = parseGeminiTokensPayloads(root);
+    const tokensPayloads = [
+        ...tokensPayloadsWithoutResponseId,
+        ...tokensPayloadsByResponseId.values(),
+    ];
     if (tokensPayloads.length === 0) {
         return buildUnavailableResult({
             reason: "missing",
             artifactPath,
-            format: "json",
+            format: "jsonl",
             providerId: "gemini",
             modelId,
-            message: "No Gemini tokens payloads were found in chat.json.",
+            message: "No Gemini tokens payloads were found in chat.jsonl.",
         });
     }
+    return extractGeminiTokenUsageFromPayloads({
+        artifactPath,
+        format: "jsonl",
+        modelId,
+        tokensPayloads,
+    });
+}
+function extractGeminiTokenUsageFromPayloads(options) {
+    const { artifactPath, format, modelId, tokensPayloads } = options;
     const normalizedUsage = [];
     for (const tokensPayload of tokensPayloads) {
         const tokensRecord = asRecord(tokensPayload.tokens);
@@ -286,7 +308,7 @@ export function extractGeminiChatUsageFromJson(options) {
             return buildUnavailableResult({
                 reason: "malformed",
                 artifactPath,
-                format: "json",
+                format,
                 providerId: "gemini",
                 modelId,
                 message: `Gemini ${tokensPayload.location} is not an object.`,
@@ -300,7 +322,7 @@ export function extractGeminiChatUsageFromJson(options) {
             return buildUnavailableResult({
                 reason: "malformed",
                 artifactPath,
-                format: "json",
+                format,
                 providerId: "gemini",
                 modelId,
                 message: `Gemini ${tokensPayload.location} did not contain any valid token usage fields.`,
@@ -313,7 +335,7 @@ export function extractGeminiChatUsageFromJson(options) {
         return buildUnavailableResult({
             reason: "malformed",
             artifactPath,
-            format: "json",
+            format,
             providerId: "gemini",
             modelId,
             message: "Gemini tokens payloads did not contain any valid token usage fields.",
@@ -323,7 +345,7 @@ export function extractGeminiChatUsageFromJson(options) {
         status: "available",
         provider: "gemini",
         artifactPath,
-        format: "json",
+        format,
         modelId,
         tokenUsage: usage,
     };
@@ -342,24 +364,6 @@ function buildUnavailableResult(options) {
 }
 function parseCodexTokenCountEvent(value) {
     const root = asRecord(value);
-    const eventMsg = parseCodexEnvelope(root);
-    if (eventMsg) {
-        const info = asRecord(eventMsg.info);
-        if (info) {
-            return { info };
-        }
-    }
-    const legacyEventMsg = asRecord(root?.event_msg);
-    if (legacyEventMsg?.type !== "token_count") {
-        return undefined;
-    }
-    const info = asRecord(legacyEventMsg.info);
-    if (!info) {
-        return undefined;
-    }
-    return { info };
-}
-function parseCodexEnvelope(root) {
     if (root?.type !== "event_msg") {
         return undefined;
     }
@@ -367,59 +371,37 @@ function parseCodexEnvelope(root) {
     if (payload?.type !== "token_count") {
         return undefined;
     }
-    return payload;
+    const info = asRecord(payload.info);
+    if (!info) {
+        return undefined;
+    }
+    return { info };
 }
 function parseClaudeUsageMessage(value, lineNumber) {
     const root = asRecord(value);
     const message = asRecord(root?.message);
-    if (!message || !("usage" in message)) {
+    if (!root || !message || !("usage" in message)) {
         return undefined;
     }
     return {
         lineNumber,
+        responseKey: buildClaudeResponseKey(root, message),
         usage: message.usage,
     };
 }
-function parseGeminiTokensPayloads(root) {
-    const tokensPayloads = [];
-    if ("tokens" in root) {
-        tokensPayloads.push({
-            location: "tokens",
-            tokens: root.tokens,
-        });
-    }
-    if ("transcripts" in root) {
-        if (!Array.isArray(root.transcripts)) {
-            return [{ location: "transcripts", tokens: undefined }];
-        }
-        for (const [index, transcript] of root.transcripts.entries()) {
-            const transcriptRecord = asRecord(transcript);
-            const payload = asRecord(transcriptRecord?.payload);
-            if (!payload) {
-                continue;
-            }
-            if ("tokens" in payload) {
-                tokensPayloads.push({
-                    location: `transcripts[${index}].payload.tokens`,
-                    tokens: payload.tokens,
-                });
-            }
-            if (!Array.isArray(payload.messages)) {
-                continue;
-            }
-            for (const [messageIndex, message] of payload.messages.entries()) {
-                const messageRecord = asRecord(message);
-                if (!messageRecord || !("tokens" in messageRecord)) {
-                    continue;
-                }
-                tokensPayloads.push({
-                    location: `transcripts[${index}].payload.messages[${messageIndex}].tokens`,
-                    tokens: messageRecord.tokens,
-                });
-            }
-        }
+function buildClaudeResponseKey(root, message) {
+    const messageId = typeof message.id === "string" ? message.id.trim() : "";
+    if (messageId.length === 0) {
+        return undefined;
     }
-    return tokensPayloads;
+    const requestId = typeof root.requestId === "string" ? root.requestId.trim() : "";
+    return requestId.length > 0
+        ? `request:${requestId}:message:${messageId}`
+        : `message:${messageId}`;
+}
+function isProviderArtifactFormatSupported(providerId, format) {
+    const providerShape = PROVIDER_USAGE_SHAPE_MAPPINGS[providerId];
+    return format === providerShape.artifactFormat;
 }
 function formatProviderLabel(providerId) {
     switch (providerId) {

package/dist/workspace/chat/usage-mappings.d.ts

@@ -2,6 +2,7 @@ import { type ChatUsageProviderId, type ExtractedTokenUsage } from "../../domain
 import type { ChatArtifactFormat } from "./types.js";
 export interface ProviderUsageFieldMapping {
     artifactFieldPath: string;
+    usagePayloadFieldPath?: string;
     usageFieldPath: string;
 }
 export interface ProviderUsageShapeMapping {

package/dist/workspace/chat/usage-mappings.js

@@ -22,40 +22,50 @@ export const PROVIDER_USAGE_SHAPE_MAPPINGS = {
                 artifactFieldPath: "usage.cache_creation_input_tokens",
                 usageFieldPath: "cache_creation_input_tokens",
             },
+            {
+                artifactFieldPath: "usage.cache_creation.ephemeral_5m_input_tokens",
+                usagePayloadFieldPath: "cache_creation.ephemeral_5m_input_tokens",
+                usageFieldPath: "cache_creation_ephemeral_5m_input_tokens",
+            },
+            {
+                artifactFieldPath: "usage.cache_creation.ephemeral_1h_input_tokens",
+                usagePayloadFieldPath: "cache_creation.ephemeral_1h_input_tokens",
+                usageFieldPath: "cache_creation_ephemeral_1h_input_tokens",
+            },
         ],
     },
     codex: {
         providerId: "codex",
         artifactFormat: "jsonl",
-        artifactShape: "event_msg(type=token_count).info.total_token_usage",
-        usageRootPath: "event_msg.info.total_token_usage",
+        artifactShape: "event_msg(type=token_count).payload.info.total_token_usage",
+        usageRootPath: "payload.info.total_token_usage",
         billingRelevantFields: [
             {
-                artifactFieldPath: "event_msg.info.total_token_usage.input_tokens",
+                artifactFieldPath: "payload.info.total_token_usage.input_tokens",
                 usageFieldPath: "input_tokens",
             },
             {
-                artifactFieldPath: "event_msg.info.total_token_usage.cached_input_tokens",
+                artifactFieldPath: "payload.info.total_token_usage.cached_input_tokens",
                 usageFieldPath: "cached_input_tokens",
             },
             {
-                artifactFieldPath: "event_msg.info.total_token_usage.output_tokens",
+                artifactFieldPath: "payload.info.total_token_usage.output_tokens",
                 usageFieldPath: "output_tokens",
             },
             {
-                artifactFieldPath: "event_msg.info.total_token_usage.reasoning_output_tokens",
+                artifactFieldPath: "payload.info.total_token_usage.reasoning_output_tokens",
                 usageFieldPath: "reasoning_output_tokens",
             },
             {
-                artifactFieldPath: "event_msg.info.total_token_usage.total_tokens",
+                artifactFieldPath: "payload.info.total_token_usage.total_tokens",
                 usageFieldPath: "total_tokens",
             },
         ],
     },
     gemini: {
         providerId: "gemini",
-        artifactFormat: "json",
-        artifactShape: "transcript.tokens",
+        artifactFormat: "jsonl",
+        artifactShape: "jsonl row tokens",
         usageRootPath: "tokens",
         billingRelevantFields: [
             {
@@ -93,7 +103,7 @@ export function extractObservedProviderNativeUsage(options) {
     }
     const nativeUsage = {};
     for (const fieldMapping of mapping.billingRelevantFields) {
-        const value = getPathValue(usageRecord, fieldMapping.usageFieldPath);
+        const value = getPathValue(usageRecord, fieldMapping.usagePayloadFieldPath ?? fieldMapping.usageFieldPath) ?? getPathValue(usageRecord, fieldMapping.usageFieldPath);
         const tokenCount = normalizeTokenCount(value);
         if (tokenCount !== undefined) {
             nativeUsage[fieldMapping.usageFieldPath] = tokenCount;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voratiq",
-  "version": "0.1.0-beta.25",
+  "version": "0.1.0-beta.26",
   "description": "Run workflows, delegate to swarms, and verify outputs before you apply them.",
   "keywords": [
     "agent-ensembles",