@agent-finops/core 0.8.0 → 0.9.0

package/dist/activitySnapshot.d.ts

@@ -41,6 +41,18 @@ export type ActivitySnapshotBuildInput = {
     /** Explicit provider-billed overage records; must also be trusted. */
     billedOverageRecordIds?: readonly string[];
     providerCoverage?: readonly ActivitySnapshotProviderCoverageInput[];
+    /**
+     * C-lane §2.1: provider-billed subscriptions with no local agent (cursor).
+     * The builder includes a billed30d amount only when the supplied window is
+     * "verified"; anything else is degraded to a missing window (writer-side
+     * lock — the renderer re-checks independently).
+     */
+    providerSubscriptions?: readonly {
+        provider: ActivitySnapshotProvider;
+        planLabel: string | null;
+        committedUsdPerMonth: number | null;
+        billed30d?: ActivitySnapshotBilledWindow;
+    }[];
     pricingAsOf?: string;
     /** Deliberately accepts only false; a runtime true is rejected as defense in depth. */
     sampleData?: false;
@@ -187,6 +199,7 @@ export declare const activitySnapshotSubscriptionAgentSchema: z.ZodObject<{
         "chatgpt-plus": "chatgpt-plus";
         "chatgpt-pro": "chatgpt-pro";
     }>>;
+    committedUsdPerMonth: z.ZodNullable<z.ZodNumber>;
     apiEquivalent: z.ZodObject<{
         oneDay: z.ZodObject<{
             amountUsd: z.ZodNullable<z.ZodNumber>;
@@ -247,6 +260,47 @@ export declare const activitySnapshotSubscriptionAgentSchema: z.ZodObject<{
     }>>;
 }, z.core.$strict>;
 export type ActivitySnapshotSubscriptionAgent = z.infer<typeof activitySnapshotSubscriptionAgentSchema>;
+/**
+ * C-lane §2.1: a provider-billed subscription with no local agent (cursor
+ * today). The writer includes a billed30d amount ONLY when its financial
+ * evidence is "verified"; the renderer independently drops anything else
+ * (double lock: estimated/unverified provider dollars can never reach a
+ * statusline segment).
+ */
+export declare const activitySnapshotProviderSubscriptionSchema: z.ZodObject<{
+    provider: z.ZodEnum<{
+        anthropic: "anthropic";
+        openai: "openai";
+        cursor: "cursor";
+        other: "other";
+        "github-copilot": "github-copilot";
+    }>;
+    billing: z.ZodLiteral<"subscription">;
+    planLabel: z.ZodNullable<z.ZodString>;
+    committedUsdPerMonth: z.ZodNullable<z.ZodNumber>;
+    billed30d: z.ZodObject<{
+        amountUsd: z.ZodNullable<z.ZodNumber>;
+        recordCount: z.ZodNumber;
+        basis: z.ZodLiteral<"provider_billed">;
+        financialEvidence: z.ZodEnum<{
+            verified: "verified";
+            missing: "missing";
+        }>;
+        coverage: z.ZodEnum<{
+            missing: "missing";
+            complete: "complete";
+            partial: "partial";
+        }>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type ActivitySnapshotProviderSubscription = z.infer<typeof activitySnapshotProviderSubscriptionSchema>;
+/** C-lane §2.1: the committed $/mo total across every detected subscription. */
+export declare const activitySnapshotCommittedTotalSchema: z.ZodObject<{
+    amountUsd: z.ZodNullable<z.ZodNumber>;
+    pricedSubs: z.ZodNumber;
+    totalSubs: z.ZodNumber;
+}, z.core.$strict>;
+export type ActivitySnapshotCommittedTotal = z.infer<typeof activitySnapshotCommittedTotalSchema>;
 export declare const activitySnapshotOverageSchema: z.ZodObject<{
     amountUsd: z.ZodNumber;
     currency: z.ZodLiteral<"USD">;
@@ -276,8 +330,8 @@ export declare const activitySnapshotCoverageSchema: z.ZodObject<{
         nonFinancialBytesPrefiltered: z.ZodNumber;
         jsonlValidationCoverage: z.ZodEnum<{
             complete: "complete";
-            financial_events_only: "financial_events_only";
             not_reported: "not_reported";
+            financial_events_only: "financial_events_only";
         }>;
     }, z.core.$strict>>;
     providers: z.ZodArray<z.ZodObject<{
@@ -309,10 +363,10 @@ export declare const activitySnapshotCoverageSchema: z.ZodObject<{
     recordsPriced: z.ZodNumber;
     recordsUnpriced: z.ZodNumber;
     validationStatus: z.ZodEnum<{
-        failed: "failed";
         complete: "complete";
-        not_checked: "not_checked";
         partial: "partial";
+        failed: "failed";
+        not_checked: "not_checked";
     }>;
     pricingAsOf: z.ZodString;
     networkUploaded: z.ZodLiteral<false>;
@@ -320,7 +374,7 @@ export declare const activitySnapshotCoverageSchema: z.ZodObject<{
 export type ActivitySnapshotCoverage = z.infer<typeof activitySnapshotCoverageSchema>;
 export declare const activitySnapshotSchema: z.ZodObject<{
     kind: z.ZodLiteral<"aibill.activity_snapshot">;
-    schemaVersion: z.ZodLiteral<1>;
+    schemaVersion: z.ZodLiteral<2>;
     currency: z.ZodLiteral<"USD">;
     asOf: z.ZodString;
     generatedAt: z.ZodString;
@@ -332,20 +386,20 @@ export declare const activitySnapshotSchema: z.ZodObject<{
         status: z.ZodLiteral<"error">;
         errorCode: z.ZodEnum<{
             unknown: "unknown";
+            timeout: "timeout";
             scan_failed: "scan_failed";
             source_unreadable: "source_unreadable";
             invalid_evidence: "invalid_evidence";
-            timeout: "timeout";
             cache_write_failed: "cache_write_failed";
         }>;
     }, z.core.$strict>], "status">;
     mode: z.ZodEnum<{
         error: "error";
+        empty: "empty";
         subscription: "subscription";
         metered: "metered";
         mixed: "mixed";
         unresolved: "unresolved";
-        empty: "empty";
     }>;
     subscription: z.ZodNullable<z.ZodObject<{
         agents: z.ZodArray<z.ZodObject<{
@@ -358,6 +412,7 @@ export declare const activitySnapshotSchema: z.ZodObject<{
                 "chatgpt-plus": "chatgpt-plus";
                 "chatgpt-pro": "chatgpt-pro";
             }>>;
+            committedUsdPerMonth: z.ZodNullable<z.ZodNumber>;
             apiEquivalent: z.ZodObject<{
                 oneDay: z.ZodObject<{
                     amountUsd: z.ZodNullable<z.ZodNumber>;
@@ -576,6 +631,37 @@ export declare const activitySnapshotSchema: z.ZodObject<{
             }, z.core.$strict>;
         }, z.core.$strict>;
     }, z.core.$strict>>;
+    providers: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        provider: z.ZodEnum<{
+            anthropic: "anthropic";
+            openai: "openai";
+            cursor: "cursor";
+            other: "other";
+            "github-copilot": "github-copilot";
+        }>;
+        billing: z.ZodLiteral<"subscription">;
+        planLabel: z.ZodNullable<z.ZodString>;
+        committedUsdPerMonth: z.ZodNullable<z.ZodNumber>;
+        billed30d: z.ZodObject<{
+            amountUsd: z.ZodNullable<z.ZodNumber>;
+            recordCount: z.ZodNumber;
+            basis: z.ZodLiteral<"provider_billed">;
+            financialEvidence: z.ZodEnum<{
+                verified: "verified";
+                missing: "missing";
+            }>;
+            coverage: z.ZodEnum<{
+                missing: "missing";
+                complete: "complete";
+                partial: "partial";
+            }>;
+        }, z.core.$strict>;
+    }, z.core.$strict>>>;
+    committedTotal: z.ZodObject<{
+        amountUsd: z.ZodNullable<z.ZodNumber>;
+        pricedSubs: z.ZodNumber;
+        totalSubs: z.ZodNumber;
+    }, z.core.$strict>;
     overage: z.ZodNullable<z.ZodObject<{
         amountUsd: z.ZodNumber;
         currency: z.ZodLiteral<"USD">;
@@ -604,8 +690,8 @@ export declare const activitySnapshotSchema: z.ZodObject<{
             nonFinancialBytesPrefiltered: z.ZodNumber;
             jsonlValidationCoverage: z.ZodEnum<{
                 complete: "complete";
-                financial_events_only: "financial_events_only";
                 not_reported: "not_reported";
+                financial_events_only: "financial_events_only";
             }>;
         }, z.core.$strict>>;
         providers: z.ZodArray<z.ZodObject<{
@@ -637,10 +723,10 @@ export declare const activitySnapshotSchema: z.ZodObject<{
         recordsPriced: z.ZodNumber;
         recordsUnpriced: z.ZodNumber;
         validationStatus: z.ZodEnum<{
-            failed: "failed";
             complete: "complete";
-            not_checked: "not_checked";
             partial: "partial";
+            failed: "failed";
+            not_checked: "not_checked";
         }>;
         pricingAsOf: z.ZodString;
         networkUploaded: z.ZodLiteral<false>;
@@ -654,6 +740,12 @@ export type ActivitySnapshot = z.infer<typeof activitySnapshotSchema>;
  * IDs already validated by the external connected-state trust receipt.
  */
 export declare function buildActivitySnapshot(input: ActivitySnapshotBuildInput): ActivitySnapshot;
+/**
+ * The v1 dual-write payload (C-lane §2.1 fleet back-compat): today's fields
+ * only, so an already-installed v1 runner keeps rendering fresh data instead
+ * of decaying into permanent staleness. Exact v1 key set; no v2 fields.
+ */
+export declare function activitySnapshotV1Payload(snapshot: ActivitySnapshot): Record<string, unknown>;
 /** A bounded no-evidence state for an initial failed refresh. */
 export declare function createActivitySnapshotError(attemptedAt: string, errorCode: ActivitySnapshotRefreshErrorCode): ActivitySnapshot;
 //# sourceMappingURL=activitySnapshot.d.ts.map

package/dist/activitySnapshot.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { aggregateCalls, dedupeCumulativeSessionCalls } from "./localAgentLogs.js";
 import { localAgentFormatDescriptors } from "./localAgentFormats/registry.js";
 import { canPriceTokenUsageAtScope, estimateTokenCostUsd, PRICING_TABLE_AS_OF } from "./modelPricing.js";
+import { subscriptionPlans } from "./planMath.js";
 import { isBundledSampleUsage } from "./schema.js";
 import { sourceValidationCoverageValues } from "./sourceStatus.js";
 const DAY_MS = 24 * 60 * 60 * 1_000;
@@ -163,6 +164,8 @@ export const activitySnapshotSubscriptionAgentSchema = z.object({
     agent: agentSchema,
     billing: z.literal("subscription"),
     planId: planIdSchema,
+    /** C-lane §2.1: detected-plan list price; null when the plan is unpriced. */
+    committedUsdPerMonth: usdSchema.nullable(),
     apiEquivalent: activitySnapshotApiEquivalentWindowsSchema,
     limits: z.array(activitySnapshotLimitSchema).max(2),
     pressure: z.enum(["extra_usage_credits_exhausted"]).nullable()
@@ -215,6 +218,41 @@ const activitySnapshotUnresolvedSchema = z.object({
         });
     }
 });
+/**
+ * C-lane §2.1: a provider-billed subscription with no local agent (cursor
+ * today). The writer includes a billed30d amount ONLY when its financial
+ * evidence is "verified"; the renderer independently drops anything else
+ * (double lock: estimated/unverified provider dollars can never reach a
+ * statusline segment).
+ */
+export const activitySnapshotProviderSubscriptionSchema = z.object({
+    provider: z.enum(activitySnapshotProviderValues),
+    billing: z.literal("subscription"),
+    planLabel: z.string().min(1).max(64).nullable(),
+    committedUsdPerMonth: usdSchema.nullable(),
+    billed30d: activitySnapshotBilledWindowSchema
+}).strict();
+/** C-lane §2.1: the committed $/mo total across every detected subscription. */
+export const activitySnapshotCommittedTotalSchema = z.object({
+    amountUsd: usdSchema.nullable(),
+    pricedSubs: countSchema,
+    totalSubs: countSchema
+}).strict().superRefine((total, context) => {
+    if (total.pricedSubs > total.totalSubs) {
+        context.addIssue({
+            code: "custom",
+            path: ["pricedSubs"],
+            message: "Priced subscriptions cannot exceed total subscriptions."
+        });
+    }
+    if ((total.amountUsd === null) !== (total.pricedSubs === 0)) {
+        context.addIssue({
+            code: "custom",
+            path: ["amountUsd"],
+            message: "A committed total exists exactly when at least one subscription is priced."
+        });
+    }
+});
 export const activitySnapshotOverageSchema = z.object({
     amountUsd: z.number().finite().positive(),
     currency: z.literal("USD"),
@@ -330,7 +368,10 @@ export const activitySnapshotCoverageSchema = z.object({
 });
 export const activitySnapshotSchema = z.object({
     kind: z.literal("aibill.activity_snapshot"),
-    schemaVersion: z.literal(1),
+    // v2 (C-lane §2.1): adds per-agent committedUsdPerMonth, provider-billed
+    // subscriptions, and the committed total. The writer dual-writes a v1
+    // payload for already-installed v1 runners during the deprecation window.
+    schemaVersion: z.literal(2),
     currency: z.literal("USD"),
     asOf: isoTimestampSchema,
     generatedAt: isoTimestampSchema,
@@ -347,6 +388,8 @@ export const activitySnapshotSchema = z.object({
     subscription: activitySnapshotSubscriptionSchema.nullable(),
     metered: activitySnapshotMeteredSchema.nullable(),
     unresolved: activitySnapshotUnresolvedSchema.nullable(),
+    providers: z.array(activitySnapshotProviderSubscriptionSchema).max(5).nullable(),
+    committedTotal: activitySnapshotCommittedTotalSchema,
     overage: activitySnapshotOverageSchema.nullable(),
     coverage: activitySnapshotCoverageSchema,
     networkUploaded: z.literal(false)
@@ -372,6 +415,20 @@ export const activitySnapshotSchema = z.object({
         (snapshot.subscription || snapshot.metered || snapshot.unresolved || snapshot.overage)) {
         invalid("Empty and error snapshots cannot carry financial cohorts.", ["mode"]);
     }
+    if ((snapshot.mode === "empty" || snapshot.mode === "error") &&
+        (snapshot.providers || snapshot.committedTotal.amountUsd !== null ||
+            snapshot.committedTotal.totalSubs !== 0)) {
+        invalid("Empty and error snapshots cannot carry subscription pricing.", ["committedTotal"]);
+    }
+    if (snapshot.providers &&
+        new Set(snapshot.providers.map((provider) => provider.provider)).size !== snapshot.providers.length) {
+        invalid("A provider subscription may appear only once.", ["providers"]);
+    }
+    const expectedTotalSubs = (snapshot.subscription?.agents.length ?? 0) +
+        (snapshot.providers?.length ?? 0);
+    if (snapshot.committedTotal.totalSubs !== expectedTotalSubs) {
+        invalid("The committed total must count every subscription row exactly once.", ["committedTotal"]);
+    }
     if (snapshot.mode === "error" && snapshot.refresh.status !== "error") {
         invalid("Error mode requires an error refresh state.", ["refresh"]);
     }
@@ -559,9 +616,32 @@ export function buildActivitySnapshot(input) {
     } : null;
     const overage = buildOverage(meteredBilledRecords, overageIds, asOfMs);
     const coverage = buildCoverage(classified.map((entry) => entry.record), scans, providers, input.pricingAsOf ?? PRICING_TABLE_AS_OF, deduplicated.conflictingIds);
+    const finalSubscription = mode === "metered" || mode === "unresolved" || mode === "empty"
+        ? null
+        : subscription;
+    // Writer-side lock (C-lane §2.1): a provider-billed amount survives only
+    // when its supplied window is verified; anything else degrades to missing.
+    const providerSubscriptionRows = mode === "empty"
+        ? []
+        : (input.providerSubscriptions ?? []).map((row) => ({
+            provider: row.provider,
+            billing: "subscription",
+            planLabel: row.planLabel,
+            committedUsdPerMonth: row.committedUsdPerMonth,
+            billed30d: row.billed30d &&
+                row.billed30d.financialEvidence === "verified" &&
+                row.billed30d.amountUsd !== null
+                ? row.billed30d
+                : missingBilledWindow()
+        }));
+    const committedRows = [
+        ...(finalSubscription?.agents ?? []).map((agent) => agent.committedUsdPerMonth),
+        ...providerSubscriptionRows.map((row) => row.committedUsdPerMonth)
+    ];
+    const pricedRows = committedRows.filter((amount) => amount !== null);
     return activitySnapshotSchema.parse({
         kind: "aibill.activity_snapshot",
-        schemaVersion: 1,
+        schemaVersion: 2,
         currency: "USD",
         asOf: new Date(asOfMs).toISOString(),
         generatedAt,
@@ -569,24 +649,80 @@ export function buildActivitySnapshot(input) {
         lastSuccessAt: generatedAt,
         refresh: { status: "ok" },
         mode,
-        subscription: mode === "metered" || mode === "unresolved" || mode === "empty"
-            ? null
-            : subscription,
+        subscription: finalSubscription,
         metered: mode === "subscription" || mode === "unresolved" || mode === "empty"
             ? null
             : metered,
         unresolved,
+        providers: providerSubscriptionRows.length > 0 ? providerSubscriptionRows : null,
+        committedTotal: {
+            amountUsd: pricedRows.length > 0
+                ? roundUsd(pricedRows.reduce((total, amount) => total + amount, 0))
+                : null,
+            pricedSubs: pricedRows.length,
+            totalSubs: committedRows.length
+        },
         overage: mode === "metered" || mode === "mixed" ? overage : null,
         coverage,
         networkUploaded: false
     });
 }
+/** Detected-plan list price (subscriptionPlans); null when unpriced. */
+function committedPriceForPlanId(planId) {
+    if (!planId)
+        return null;
+    return subscriptionPlans.find((plan) => plan.id === planId)?.monthlyUsd ?? null;
+}
+function missingBilledWindow() {
+    return {
+        amountUsd: null,
+        recordCount: 0,
+        basis: "provider_billed",
+        financialEvidence: "missing",
+        coverage: "missing"
+    };
+}
+/**
+ * The v1 dual-write payload (C-lane §2.1 fleet back-compat): today's fields
+ * only, so an already-installed v1 runner keeps rendering fresh data instead
+ * of decaying into permanent staleness. Exact v1 key set; no v2 fields.
+ */
+export function activitySnapshotV1Payload(snapshot) {
+    return {
+        kind: snapshot.kind,
+        schemaVersion: 1,
+        currency: snapshot.currency,
+        asOf: snapshot.asOf,
+        generatedAt: snapshot.generatedAt,
+        lastAttemptAt: snapshot.lastAttemptAt,
+        lastSuccessAt: snapshot.lastSuccessAt,
+        refresh: snapshot.refresh,
+        mode: snapshot.mode,
+        subscription: snapshot.subscription
+            ? {
+                agents: snapshot.subscription.agents.map((agent) => ({
+                    agent: agent.agent,
+                    billing: agent.billing,
+                    planId: agent.planId,
+                    apiEquivalent: agent.apiEquivalent,
+                    limits: agent.limits,
+                    pressure: agent.pressure
+                }))
+            }
+            : null,
+        metered: snapshot.metered,
+        unresolved: snapshot.unresolved,
+        overage: snapshot.overage,
+        coverage: snapshot.coverage,
+        networkUploaded: snapshot.networkUploaded
+    };
+}
 /** A bounded no-evidence state for an initial failed refresh. */
 export function createActivitySnapshotError(attemptedAt, errorCode) {
     const timestamp = new Date(parseTimestamp(attemptedAt, "attemptedAt")).toISOString();
     return activitySnapshotSchema.parse({
         kind: "aibill.activity_snapshot",
-        schemaVersion: 1,
+        schemaVersion: 2,
         currency: "USD",
         asOf: timestamp,
         generatedAt: timestamp,
@@ -597,6 +733,8 @@ export function createActivitySnapshotError(attemptedAt, errorCode) {
         subscription: null,
         metered: null,
         unresolved: null,
+        providers: null,
+        committedTotal: { amountUsd: null, pricedSubs: 0, totalSubs: 0 },
         overage: null,
         coverage: {
             agents: [],
@@ -650,6 +788,7 @@ function activitySubscriptionAgents(records, calls, allCalls, plans, scans, trus
             agent,
             billing: "subscription",
             planId: isKnownPlanId(plan.planId) ? plan.planId : null,
+            committedUsdPerMonth: committedPriceForPlanId(plan.planId),
             apiEquivalent: buildApiWindows(agentRecords, allCalls.filter((call) => call.agent === agent), trustedProviderIds, asOfMs, localCoverageForAgent(agent, scans)),
             limits: latestReportedLimits(agentCalls, asOfMs),
             pressure: plan.limitSignal === "extra-usage credits exhausted"

package/dist/activitySnapshotCache.d.ts

@@ -1,6 +1,13 @@
 import { type ActivitySnapshot, type ActivitySnapshotRefreshErrorCode } from "./activitySnapshot.js";
 export declare const activitySnapshotCacheEnvironmentVariable = "AIBILL_CACHE_DIR";
-export declare const activitySnapshotCacheFileName = "statusline-v1.json";
+/** The v2 snapshot cache (C-lane §2.1). */
+export declare const activitySnapshotCacheFileName = "statusline-v2.json";
+/**
+ * Deprecation-window dual-write target: installed v1 runners are frozen
+ * copies that read only this file, so every v2 write also refreshes a v1
+ * payload here (today's fields only) instead of stranding them stale.
+ */
+export declare const activitySnapshotLegacyCacheFileName = "statusline-v1.json";
 export declare const activitySnapshotCacheMaxBytes: number;
 export type ActivitySnapshotCacheOptions = {
     /** Test/embedding override. Production defaults to ~/.aibill/cache. */

package/dist/activitySnapshotCache.js

@@ -1,18 +1,30 @@
 import { constants } from "node:fs";
+import { execFile as execFileCallback } from "node:child_process";
 import { open, lstat, mkdir, chmod, realpath, rename, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
-import { activitySnapshotSchema, createActivitySnapshotError } from "./activitySnapshot.js";
+import { promisify } from "node:util";
+import { activitySnapshotSchema, activitySnapshotV1Payload, createActivitySnapshotError } from "./activitySnapshot.js";
 export const activitySnapshotCacheEnvironmentVariable = "AIBILL_CACHE_DIR";
-export const activitySnapshotCacheFileName = "statusline-v1.json";
+/** The v2 snapshot cache (C-lane §2.1). */
+export const activitySnapshotCacheFileName = "statusline-v2.json";
+/**
+ * Deprecation-window dual-write target: installed v1 runners are frozen
+ * copies that read only this file, so every v2 write also refreshes a v1
+ * payload here (today's fields only) instead of stranding them stale.
+ */
+export const activitySnapshotLegacyCacheFileName = "statusline-v1.json";
 export const activitySnapshotCacheMaxBytes = 64 * 1_024;
+// The lock name is shared with pre-v2 writers on purpose: during the fleet
+// deprecation window both CLI generations serialize through one lock.
 const lockFileName = ".statusline-v1.lock";
 const defaultLockTimeoutMs = 2_000;
 const staleLockMs = 15_000;
 const lockPollMs = 20;
 const lockMetadataMaxBytes = 512;
+const execFile = promisify(execFileCallback);
 export class ActivitySnapshotCacheError extends Error {
     code;
     constructor(code, message) {
@@ -207,7 +219,7 @@ async function readSnapshotFile(directory) {
         catch {
             return { status: "error", code: "malformed" };
         }
-        if (isRecord(value) && value.schemaVersion !== undefined && value.schemaVersion !== 1) {
+        if (isRecord(value) && value.schemaVersion !== undefined && value.schemaVersion !== 2) {
             return { status: "error", code: "unsupported_version" };
         }
         const parsed = activitySnapshotSchema.safeParse(value);
@@ -225,11 +237,17 @@ async function readSnapshotFile(directory) {
     }
 }
 async function atomicWriteSnapshot(directory, snapshot) {
-    const contents = `${JSON.stringify(snapshot)}\n`;
+    await atomicWriteCacheFile(directory, activitySnapshotCacheFileName, `${JSON.stringify(snapshot)}\n`);
+    // C-lane §2.1 fleet back-compat: dual-write the v1 payload so an
+    // already-installed v1 runner keeps rendering fresh data during the
+    // deprecation window instead of decaying into permanent staleness.
+    await atomicWriteCacheFile(directory, activitySnapshotLegacyCacheFileName, `${JSON.stringify(activitySnapshotV1Payload(snapshot))}\n`);
+}
+async function atomicWriteCacheFile(directory, fileName, contents) {
     if (Buffer.byteLength(contents, "utf8") > activitySnapshotCacheMaxBytes) {
         throw new ActivitySnapshotCacheError("invalid_snapshot", "Activity snapshot exceeds the 64 KiB cache limit.");
     }
-    const filePath = join(directory, activitySnapshotCacheFileName);
+    const filePath = join(directory, fileName);
     const existing = await lstat(filePath).catch((error) => {
         if (isNodeError(error, "ENOENT"))
             return undefined;
@@ -238,7 +256,7 @@ async function atomicWriteSnapshot(directory, snapshot) {
     if (existing?.isSymbolicLink() || (existing && !existing.isFile())) {
         throw new ActivitySnapshotCacheError("unsafe_file", "Activity snapshot cache path is not a regular file.");
     }
-    const temporaryPath = join(directory, `.${activitySnapshotCacheFileName}.${process.pid}.${randomUUID()}.tmp`);
+    const temporaryPath = join(directory, `.${fileName}.${process.pid}.${randomUUID()}.tmp`);
     let handle;
     try {
         handle = await open(temporaryPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollowFlag(), 0o600);
@@ -329,6 +347,84 @@ async function ensureDefaultParent(homeDirectory, create) {
     }
     if (create)
         await chmod(parent, 0o700);
+    await ensureDefaultCacheGitPrivacy(parent, create);
+}
+/**
+ * When a synthetic or real HOME is itself inside a Git worktree, protect the
+ * complete top-level private state directory before any cache child is
+ * created. Explicit AIBILL_CACHE_DIR/cacheDirectory overrides intentionally
+ * remain caller-owned and never receive repository files from this helper.
+ */
+async function ensureDefaultCacheGitPrivacy(aibillDirectory, create) {
+    const gitRoot = await findEnclosingGitRoot(aibillDirectory);
+    if (!gitRoot)
+        return;
+    const marker = join(aibillDirectory, ".gitignore");
+    let handle;
+    try {
+        handle = await open(marker, constants.O_RDONLY | noFollowFlag());
+    }
+    catch (error) {
+        if (!isNodeError(error, "ENOENT"))
+            throw error;
+        if (!create) {
+            const missing = new Error("Private aibill Git privacy marker does not exist.");
+            missing.code = "ENOENT";
+            throw missing;
+        }
+        handle = await open(marker, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | noFollowFlag(), 0o600);
+        await handle.writeFile("*\n", "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = await open(marker, constants.O_RDONLY | noFollowFlag());
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || !hasPrivatePermissions(info.mode) || info.size !== 2) {
+            throw new ActivitySnapshotCacheError("unsafe_directory", "Private aibill Git privacy marker is unsafe.");
+        }
+        const buffer = Buffer.alloc(2);
+        const { bytesRead } = await handle.read(buffer, 0, 2, 0);
+        if (bytesRead !== 2 || buffer.toString("utf8") !== "*\n") {
+            throw new ActivitySnapshotCacheError("unsafe_directory", "Private aibill Git privacy marker is invalid.");
+        }
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+    const relativeDirectory = relative(gitRoot, aibillDirectory);
+    const tracked = await execFile("git", ["-C", gitRoot, "ls-files", "--", relativeDirectory], {
+        encoding: "utf8",
+        maxBuffer: 64 * 1024
+    }).then(({ stdout }) => stdout.trim()).catch(() => {
+        throw new ActivitySnapshotCacheError("unsafe_directory", "Private aibill cache tracking status could not be verified.");
+    });
+    if (tracked) {
+        throw new ActivitySnapshotCacheError("unsafe_directory", "Private aibill cache is already tracked by Git.");
+    }
+    const ignored = await execFile("git", [
+        "-C", gitRoot, "check-ignore", "--quiet", "--no-index", "--",
+        join(relativeDirectory, "cache", "privacy-probe.json")
+    ]).then(() => true).catch(() => false);
+    if (!ignored) {
+        throw new ActivitySnapshotCacheError("unsafe_directory", "Private aibill cache is not proven ignored by Git.");
+    }
+}
+async function findEnclosingGitRoot(path) {
+    let current = resolve(path);
+    while (true) {
+        const gitEntry = await lstat(join(current, ".git")).catch((error) => {
+            if (isNodeError(error, "ENOENT") || isNodeError(error, "ENOTDIR"))
+                return undefined;
+            throw error;
+        });
+        if (gitEntry)
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
 }
 function configuredCacheDirectory(options) {
     const configured = options.cacheDirectory?.trim() ||