@bli-cockpit/telemetry-core 0.1.20 → 0.1.23

package/dist/evidence-upload.d.ts

@@ -28,7 +28,10 @@ export declare const RawEvidenceLegacyUploadResponseSchema: z.ZodObject<{
         byte_size: z.ZodNumber;
         redaction: z.ZodOptional<z.ZodObject<{
             schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-            status: z.ZodLiteral<"sanitized">;
+            status: z.ZodEnum<{
+                sanitized: "sanitized";
+                scanned_clean: "scanned_clean";
+            }>;
             mode: z.ZodLiteral<"deterministic_text_replacement">;
             applied_by: z.ZodArray<z.ZodEnum<{
                 local_collector: "local_collector";
@@ -90,7 +93,10 @@ export declare const RawEvidenceUploadBeginObjectSchema: z.ZodObject<{
         redacted_summary: z.ZodOptional<z.ZodString>;
         redaction: z.ZodOptional<z.ZodObject<{
             schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-            status: z.ZodLiteral<"sanitized">;
+            status: z.ZodEnum<{
+                sanitized: "sanitized";
+                scanned_clean: "scanned_clean";
+            }>;
             mode: z.ZodLiteral<"deterministic_text_replacement">;
             applied_by: z.ZodArray<z.ZodEnum<{
                 local_collector: "local_collector";
@@ -186,7 +192,10 @@ export declare const RawEvidenceUploadBeginRequestSchema: z.ZodObject<{
             redacted_summary: z.ZodOptional<z.ZodString>;
             redaction: z.ZodOptional<z.ZodObject<{
                 schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-                status: z.ZodLiteral<"sanitized">;
+                status: z.ZodEnum<{
+                    sanitized: "sanitized";
+                    scanned_clean: "scanned_clean";
+                }>;
                 mode: z.ZodLiteral<"deterministic_text_replacement">;
                 applied_by: z.ZodArray<z.ZodEnum<{
                     local_collector: "local_collector";
@@ -351,7 +360,10 @@ export declare const RawEvidenceUploadCommitResponseSchema: z.ZodObject<{
     chunk_count: z.ZodNumber;
     redaction: z.ZodOptional<z.ZodObject<{
         schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-        status: z.ZodLiteral<"sanitized">;
+        status: z.ZodEnum<{
+            sanitized: "sanitized";
+            scanned_clean: "scanned_clean";
+        }>;
         mode: z.ZodLiteral<"deterministic_text_replacement">;
         applied_by: z.ZodArray<z.ZodEnum<{
             local_collector: "local_collector";

package/dist/ingest-dto.d.ts

@@ -290,7 +290,10 @@ export declare const TelemetryIngestEventDtoSchema: z.ZodObject<{
         redacted_summary: z.ZodOptional<z.ZodString>;
         redaction: z.ZodOptional<z.ZodObject<{
             schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-            status: z.ZodLiteral<"sanitized">;
+            status: z.ZodEnum<{
+                sanitized: "sanitized";
+                scanned_clean: "scanned_clean";
+            }>;
             mode: z.ZodLiteral<"deterministic_text_replacement">;
             applied_by: z.ZodArray<z.ZodEnum<{
                 local_collector: "local_collector";
@@ -763,7 +766,10 @@ export declare const TelemetryIngestEnvelopeSchema: z.ZodObject<{
             redacted_summary: z.ZodOptional<z.ZodString>;
             redaction: z.ZodOptional<z.ZodObject<{
                 schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-                status: z.ZodLiteral<"sanitized">;
+                status: z.ZodEnum<{
+                    sanitized: "sanitized";
+                    scanned_clean: "scanned_clean";
+                }>;
                 mode: z.ZodLiteral<"deterministic_text_replacement">;
                 applied_by: z.ZodArray<z.ZodEnum<{
                     local_collector: "local_collector";
@@ -913,7 +919,10 @@ export declare const TelemetryIngestEnvelopeSchema: z.ZodObject<{
                 redacted_summary: z.ZodOptional<z.ZodString>;
                 redaction: z.ZodOptional<z.ZodObject<{
                     schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-                    status: z.ZodLiteral<"sanitized">;
+                    status: z.ZodEnum<{
+                        sanitized: "sanitized";
+                        scanned_clean: "scanned_clean";
+                    }>;
                     mode: z.ZodLiteral<"deterministic_text_replacement">;
                     applied_by: z.ZodArray<z.ZodEnum<{
                         local_collector: "local_collector";

package/dist/privacy.d.ts

@@ -68,7 +68,10 @@ export declare const RawEvidencePointerSchema: z.ZodObject<{
     redacted_summary: z.ZodOptional<z.ZodString>;
     redaction: z.ZodOptional<z.ZodObject<{
         schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-        status: z.ZodLiteral<"sanitized">;
+        status: z.ZodEnum<{
+            sanitized: "sanitized";
+            scanned_clean: "scanned_clean";
+        }>;
         mode: z.ZodLiteral<"deterministic_text_replacement">;
         applied_by: z.ZodArray<z.ZodEnum<{
             local_collector: "local_collector";

package/dist/secret-guards.d.ts

@@ -43,9 +43,27 @@ export declare const RawEvidenceRedactionRangeSchema: z.ZodObject<{
     rule_id: z.ZodString;
 }, z.core.$strict>;
 export type RawEvidenceRedactionRange = z.infer<typeof RawEvidenceRedactionRangeSchema>;
+/**
+ * The verdict of a secret scan — NOT "did the bytes change" (BLI-3277).
+ *
+ * `sanitized` means the scan matched and the uploaded bytes differ from what was
+ * read. `scanned_clean` means the same scan ran over the same bytes and matched
+ * nothing, so the uploaded bytes are the original ones. The second value exists
+ * because every reader downstream asks "was this scanned?", and for 70% of
+ * transcripts — the ones with no secret in them — the honest answer used to be
+ * an absent record, which reads identically to "nobody ever looked".
+ */
+export declare const RawEvidenceRedactionStatusSchema: z.ZodEnum<{
+    sanitized: "sanitized";
+    scanned_clean: "scanned_clean";
+}>;
+export type RawEvidenceRedactionStatus = z.infer<typeof RawEvidenceRedactionStatusSchema>;
 export declare const RawEvidenceRedactionMetadataSchema: z.ZodObject<{
     schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-    status: z.ZodLiteral<"sanitized">;
+    status: z.ZodEnum<{
+        sanitized: "sanitized";
+        scanned_clean: "scanned_clean";
+    }>;
     mode: z.ZodLiteral<"deterministic_text_replacement">;
     applied_by: z.ZodArray<z.ZodEnum<{
         local_collector: "local_collector";

package/dist/secret-guards.js

@@ -48,6 +48,41 @@ const SECRET_NAME_PATTERN_SOURCE = [
     "client[_-]?secret",
     "secret[_-]?access[_-]?key",
 ].join("|");
+/**
+ * Credential names live INSIDE longer identifiers, so `\b` is the wrong fence
+ * (BLI-3116).
+ *
+ * Every name fragment above used to be wrapped in `\b(?:…)\b`. Underscore is a
+ * word character, so there is no word boundary between `AWS_` and `SECRET`:
+ * `AWS_SECRET_ACCESS_KEY=AKIA…` — the most common real spelling of the most
+ * common real leak — never matched and uploaded unmasked from every fleet
+ * machine, while the bare `SECRET_ACCESS_KEY=…` matched fine. The same hole hid
+ * `AZURE_OPENAI_API_KEY`, `VITE_SUPABASE_ANON_KEY`, `GITHUB_ACCESS_TOKEN`,
+ * `MY_APP_CLIENT_SECRET` and every other prefixed spelling: the bug was the
+ * fence, not the vocabulary, so the whole list is fenced differently now.
+ *
+ * `_`, `-` and `.` are identifier JOINERS here, not boundaries:
+ *
+ * - leading `(?<![A-Za-z0-9])` — the fragment may begin right after a joiner or
+ *   at a real boundary, but a letter or digit immediately before it still
+ *   blocks the match (`notapikey=…` stays out, as before).
+ * - trailing `[A-Za-z0-9_-]{0,40}` — a bounded identifier tail, so
+ *   `OPENAI_API_KEY_2=…` and `AWS_SECRET_ACCESS_KEY_ID=…` are seen too.
+ *
+ * Prose is unaffected because the assignment requirement below is unchanged:
+ * "rotate your secret access key" has no `=`/`:` + opaque value and is not a
+ * leak. The guard's job is assignments, not vocabulary.
+ */
+const SECRET_NAME_MATCH_SOURCE = `(?<![A-Za-z0-9])(?:${SECRET_NAME_PATTERN_SOURCE})[A-Za-z0-9_-]{0,40}`;
+/**
+ * The assignment operator, with the closing quote of a JSON/YAML key allowed
+ * before it. Found while auditing the fence above: `{"aws_secret_access_key":
+ * "…"}` never matched either, because the name was followed by `"` and the
+ * pattern demanded `[:=]` immediately. Transcripts are JSONL, so this is the
+ * shape a leaked credential most often has on the way in. The sibling redactor
+ * in harvest-analysis (`study/prepare.ts`) already allowed it; this one did not.
+ */
+const SECRET_ASSIGNMENT_SOURCE = `["']?\\s*[:=]\\s*["']?`;
 /**
  * Credential names that are only a leak when assigned a value (D13). The value
  * shape mirrors the long-standing generic pattern: an assignment operator
@@ -55,10 +90,18 @@ const SECRET_NAME_PATTERN_SOURCE = [
  * `GRANT ... TO service_role` (no assignment) do not match; the same name with
  * an assigned value does.
  */
-const SECRET_NAME_WITH_VALUE_PATTERN = new RegExp(`\\b(?:${SECRET_NAME_PATTERN_SOURCE})\\b\\s*[:=]\\s*["']?[A-Za-z0-9_./+=-]{12,}`, "i");
+const SECRET_NAME_WITH_VALUE_PATTERN = new RegExp(`${SECRET_NAME_MATCH_SOURCE}${SECRET_ASSIGNMENT_SOURCE}[A-Za-z0-9_./+=-]{12,}`, "i");
 /**
  * Self-identifying secret values — blocked regardless of context because the
  * token shape itself is the credential, with no benign reading.
+ *
+ * `\b` is deliberately KEPT here, unlike the name fragments above (BLI-3116).
+ * These patterns are whole tokens, not fragments of a longer identifier: a
+ * `ghp_`/`sk-`/`AKIA…` run that continues into surrounding alphanumerics is not
+ * that provider's token, and unanchoring them would mask ordinary identifiers
+ * (`chart_m0_2024_revenue…`) for no safety gain. A real leak of any of these
+ * shapes is preceded by a quote, whitespace, `=`, `:` or `/` — all of which
+ * `\b` already admits.
  */
 const SECRET_VALUE_PATTERNS = [
     /-----BEGIN [A-Z ]*PRIVATE KEY-----/,
@@ -110,14 +153,28 @@ export const RawEvidenceRedactionRangeSchema = z
         });
     }
 });
+/**
+ * The verdict of a secret scan — NOT "did the bytes change" (BLI-3277).
+ *
+ * `sanitized` means the scan matched and the uploaded bytes differ from what was
+ * read. `scanned_clean` means the same scan ran over the same bytes and matched
+ * nothing, so the uploaded bytes are the original ones. The second value exists
+ * because every reader downstream asks "was this scanned?", and for 70% of
+ * transcripts — the ones with no secret in them — the honest answer used to be
+ * an absent record, which reads identically to "nobody ever looked".
+ */
+export const RawEvidenceRedactionStatusSchema = z.enum([
+    "sanitized",
+    "scanned_clean",
+]);
 export const RawEvidenceRedactionMetadataSchema = z
     .object({
     schema_version: z.literal("raw-evidence-redaction.v1"),
-    status: z.literal("sanitized"),
+    status: RawEvidenceRedactionStatusSchema,
     mode: z.literal("deterministic_text_replacement"),
     applied_by: z.array(RawEvidenceRedactionSourceSchema).min(1),
-    rule_counts: z.array(RawEvidenceRedactionRuleCountSchema).min(1),
-    secret_like_match_count: z.number().int().positive(),
+    rule_counts: z.array(RawEvidenceRedactionRuleCountSchema),
+    secret_like_match_count: z.number().int().nonnegative(),
     redacted_fields: z.array(z.string().trim().min(1).max(160)).default([]),
     redacted_ranges: z.array(RawEvidenceRedactionRangeSchema).max(200).default([]),
     original_content_hash_sha256: z.string().regex(/^[a-f0-9]{64}$/).optional(),
@@ -125,8 +182,81 @@ export const RawEvidenceRedactionMetadataSchema = z
     original_byte_size: z.number().int().nonnegative().optional(),
     sanitized_byte_size: z.number().int().nonnegative().optional(),
 })
-    .strict();
-const SECRET_ASSIGNMENT_REDACTION_PATTERN = new RegExp(`(\\b(?:${SECRET_NAME_PATTERN_SOURCE})\\b\\s*[:=]\\s*["']?)([A-Za-z0-9_./+=-]{12,})`, "gi");
+    .strict()
+    // The per-status invariants the old `z.literal("sanitized")` + `.min(1)` +
+    // `.positive()` shape enforced structurally. They still hold for a sanitized
+    // record; a clean one has to prove the opposite — no rule fired, no range was
+    // replaced, no field was masked, and the bytes came out the way they went in.
+    .superRefine((metadata, context) => {
+    if (metadata.status === "sanitized") {
+        if (metadata.rule_counts.length === 0) {
+            context.addIssue({
+                code: "custom",
+                message: "a sanitized redaction must name at least one rule",
+                path: ["rule_counts"],
+            });
+        }
+        if (metadata.secret_like_match_count < 1) {
+            context.addIssue({
+                code: "custom",
+                message: "a sanitized redaction must count at least one match",
+                path: ["secret_like_match_count"],
+            });
+        }
+        return;
+    }
+    if (metadata.rule_counts.length > 0) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot name a rule that fired",
+            path: ["rule_counts"],
+        });
+    }
+    if (metadata.secret_like_match_count !== 0) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot count a match",
+            path: ["secret_like_match_count"],
+        });
+    }
+    if (metadata.redacted_ranges.length > 0) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot redact a range",
+            path: ["redacted_ranges"],
+        });
+    }
+    if (metadata.redacted_fields.length > 0) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot redact a field",
+            path: ["redacted_fields"],
+        });
+    }
+    if (metadata.original_content_hash_sha256 !== undefined &&
+        metadata.sanitized_content_hash_sha256 !== undefined &&
+        metadata.original_content_hash_sha256 !==
+            metadata.sanitized_content_hash_sha256) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot change the content hash",
+            path: ["sanitized_content_hash_sha256"],
+        });
+    }
+    if (metadata.original_byte_size !== undefined &&
+        metadata.sanitized_byte_size !== undefined &&
+        metadata.original_byte_size !== metadata.sanitized_byte_size) {
+        context.addIssue({
+            code: "custom",
+            message: "a clean scan cannot change the byte size",
+            path: ["sanitized_byte_size"],
+        });
+    }
+});
+// Same fence as the detector (BLI-3116) — the two must agree or a prefixed
+// name would be detected and then left unredacted, which costs whole sessions
+// (see findSecretRedactionMatches).
+const SECRET_ASSIGNMENT_REDACTION_PATTERN = new RegExp(`(${SECRET_NAME_MATCH_SOURCE}${SECRET_ASSIGNMENT_SOURCE})([A-Za-z0-9_./+=-]{12,})`, "gi");
 const SECRET_REDACTION_RULES = [
     {
         ruleId: "credential_assignment",

package/dist/source-adapter.d.ts

@@ -76,7 +76,10 @@ export declare const SourceScanEventSummarySchema: z.ZodObject<{
         redacted_summary: z.ZodOptional<z.ZodString>;
         redaction: z.ZodOptional<z.ZodObject<{
             schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-            status: z.ZodLiteral<"sanitized">;
+            status: z.ZodEnum<{
+                sanitized: "sanitized";
+                scanned_clean: "scanned_clean";
+            }>;
             mode: z.ZodLiteral<"deterministic_text_replacement">;
             applied_by: z.ZodArray<z.ZodEnum<{
                 local_collector: "local_collector";
@@ -190,7 +193,10 @@ export declare const SourceScanResultSchema: z.ZodObject<{
             redacted_summary: z.ZodOptional<z.ZodString>;
             redaction: z.ZodOptional<z.ZodObject<{
                 schema_version: z.ZodLiteral<"raw-evidence-redaction.v1">;
-                status: z.ZodLiteral<"sanitized">;
+                status: z.ZodEnum<{
+                    sanitized: "sanitized";
+                    scanned_clean: "scanned_clean";
+                }>;
                 mode: z.ZodLiteral<"deterministic_text_replacement">;
                 applied_by: z.ZodArray<z.ZodEnum<{
                     local_collector: "local_collector";

package/dist/upload-failure-class.d.ts

@@ -34,6 +34,84 @@ export declare const NO_UPLOAD_ATTEMPT_RECORDED = "no_upload_attempt_recorded";
 export declare const STORAGE_REJECTED_OBJECT_TOO_LARGE = "storage_rejected_object_too_large";
 /** Storage refused the finished object because of its declared media type. */
 export declare const STORAGE_REJECTED_MEDIA_TYPE = "storage_rejected_media_type";
+/**
+ * The commit route never survived the object (BLI-3067).
+ *
+ * Fires when the commit call answers `>= 500` with a body that is not the
+ * route's JSON envelope — an HTML error page from the platform. The handler
+ * always answers `{ code, message, … }`, so a non-JSON 5xx means the serverless
+ * process was killed mid-assembly (out of memory, or a hard wall-clock timeout)
+ * and no catch ran, no ledger reason was written and no server log line exists.
+ *
+ * It is a distinct label because the operator-visible difference is total: a
+ * refusal means the server looked at these bytes and said no, this means the
+ * server died holding them. The collector composes the observed status onto the
+ * end (`commit_crashed_platform_http_502`) so a gateway timeout can still be
+ * told from an out-of-memory; `classifyUploadFailure` strips that suffix.
+ */
+export declare const COMMIT_CRASHED_PLATFORM = "commit_crashed_platform";
+/**
+ * The collector deliberately did not offer this object on this sync.
+ *
+ * Fires in the delivery-backoff partition: an object whose delivery keeps
+ * failing is retried on a 15-minute-to-6-hour schedule (~4 attempts a day)
+ * instead of on every sync, after one object failed 1,030 times in nine days
+ * (BLI-3066). The held object is reported as a failed outcome carrying this
+ * label rather than quietly omitted — a hold that read as success is exactly
+ * the green-status-hiding-missing-collection failure the fleet contract
+ * forbids.
+ *
+ * Not `withheld_by_policy`: nothing was refused and nothing needs a human. The
+ * hold expires on a clock, so it is transient in the strict sense — the next
+ * eligible sync offers the same bytes again.
+ */
+export declare const DELIVERY_BACKOFF_HOLDING = "delivery_backoff_holding";
+/**
+ * Raw evidence was never offered because the session's attribution state is not
+ * one the upload policy accepts (BLI-3272).
+ *
+ * `isRawEvidenceUploadableAttributionState` refuses a session whose attribution
+ * produced neither a repository identity nor an approved-root synthetic
+ * workspace. That refusal is a real, explainable decision — but until this label
+ * existed the report builders answered it by spreading `{}`, so the row reached
+ * `ambient_codex_sessions` with `upload_state = NULL` AND `upload_reason = NULL`.
+ * 1,256 sessions sat in that hole on 2026-08-29, 197 of them first seen inside a
+ * week from current 0.2.30 machines, every one `unattributed` /
+ * `cwd_outside_scanned_worktrees`. A withheld session that says nothing is the
+ * exact failure the session-first contract forbids, and the migration comment
+ * claiming "every write path now sets it" was false for all of them.
+ *
+ * Written with the deciding attribution reason appended after a colon
+ * (`not_uploadable_attribution_state:cwd_outside_scanned_worktrees`) so the
+ * upload half of the row explains itself without a join;
+ * `baseUploadFailureReason` strips that qualifier for classification.
+ *
+ * `deterministic` for the same reason as the bare attribution labels below: the
+ * scan completed and produced no target, so repeating it changes nothing.
+ * Widening the operator's approved roots can change it — a human decision, not a
+ * retry.
+ */
+export declare const NOT_UPLOADABLE_ATTRIBUTION_STATE = "not_uploadable_attribution_state";
+/**
+ * Compose the withheld-by-attribution reason for one session.
+ *
+ * The detail is the attribution reason that decided it. Anything outside the
+ * safe-label charset — colons included, so the stem always ends at the first one
+ * — collapses to `_`, and an empty or unusable detail degrades to the bare stem
+ * rather than inventing one.
+ */
+export declare function notUploadableAttributionStateReason(attributionReason: string | null | undefined): string;
+/**
+ * The listed reason a composed label is a variant of, or the label unchanged.
+ *
+ * The collector appends the observed status to some labels so an operator can
+ * tell a 502 from a 500 (`commit_crashed_platform_http_502`). Stripping it is
+ * deliberately NOT pattern matching on the label's words: the suffix is only
+ * removed when what remains is a reason somebody has already classified by
+ * hand, so `commit_failed_http_503` — whose stem nobody has reasoned about —
+ * still classifies as `unknown`, exactly as before.
+ */
+export declare function baseUploadFailureReason(reason: string): string;
 /** Classify a persisted upload reason. Unlisted reasons stay `unknown`. */
 export declare function classifyUploadFailure(reason: string | null | undefined): UploadFailureClass;
 /**

package/dist/upload-failure-class.js

@@ -13,6 +13,12 @@
 // future reason somebody adds, which is the same class of guessing the person
 // resolver refuses to do. An unlisted reason is `unknown` and stays visible
 // until a human decides which bucket it belongs in.
+//
+// The one concession is a trailing `_http_<status>`, which the collector
+// appends to some labels so an operator can tell a 502 from a 500. It is
+// stripped only when the remaining stem is itself a listed reason — see
+// `baseUploadFailureReason` — so the table still decides everything and an
+// unreasoned-about stem stays `unknown`.
 /**
  * The reason written when nothing in the pipeline explained itself.
  *
@@ -34,6 +40,85 @@ export const NO_UPLOAD_ATTEMPT_RECORDED = "no_upload_attempt_recorded";
 export const STORAGE_REJECTED_OBJECT_TOO_LARGE = "storage_rejected_object_too_large";
 /** Storage refused the finished object because of its declared media type. */
 export const STORAGE_REJECTED_MEDIA_TYPE = "storage_rejected_media_type";
+/**
+ * The commit route never survived the object (BLI-3067).
+ *
+ * Fires when the commit call answers `>= 500` with a body that is not the
+ * route's JSON envelope — an HTML error page from the platform. The handler
+ * always answers `{ code, message, … }`, so a non-JSON 5xx means the serverless
+ * process was killed mid-assembly (out of memory, or a hard wall-clock timeout)
+ * and no catch ran, no ledger reason was written and no server log line exists.
+ *
+ * It is a distinct label because the operator-visible difference is total: a
+ * refusal means the server looked at these bytes and said no, this means the
+ * server died holding them. The collector composes the observed status onto the
+ * end (`commit_crashed_platform_http_502`) so a gateway timeout can still be
+ * told from an out-of-memory; `classifyUploadFailure` strips that suffix.
+ */
+export const COMMIT_CRASHED_PLATFORM = "commit_crashed_platform";
+/**
+ * The collector deliberately did not offer this object on this sync.
+ *
+ * Fires in the delivery-backoff partition: an object whose delivery keeps
+ * failing is retried on a 15-minute-to-6-hour schedule (~4 attempts a day)
+ * instead of on every sync, after one object failed 1,030 times in nine days
+ * (BLI-3066). The held object is reported as a failed outcome carrying this
+ * label rather than quietly omitted — a hold that read as success is exactly
+ * the green-status-hiding-missing-collection failure the fleet contract
+ * forbids.
+ *
+ * Not `withheld_by_policy`: nothing was refused and nothing needs a human. The
+ * hold expires on a clock, so it is transient in the strict sense — the next
+ * eligible sync offers the same bytes again.
+ */
+export const DELIVERY_BACKOFF_HOLDING = "delivery_backoff_holding";
+/**
+ * Raw evidence was never offered because the session's attribution state is not
+ * one the upload policy accepts (BLI-3272).
+ *
+ * `isRawEvidenceUploadableAttributionState` refuses a session whose attribution
+ * produced neither a repository identity nor an approved-root synthetic
+ * workspace. That refusal is a real, explainable decision — but until this label
+ * existed the report builders answered it by spreading `{}`, so the row reached
+ * `ambient_codex_sessions` with `upload_state = NULL` AND `upload_reason = NULL`.
+ * 1,256 sessions sat in that hole on 2026-08-29, 197 of them first seen inside a
+ * week from current 0.2.30 machines, every one `unattributed` /
+ * `cwd_outside_scanned_worktrees`. A withheld session that says nothing is the
+ * exact failure the session-first contract forbids, and the migration comment
+ * claiming "every write path now sets it" was false for all of them.
+ *
+ * Written with the deciding attribution reason appended after a colon
+ * (`not_uploadable_attribution_state:cwd_outside_scanned_worktrees`) so the
+ * upload half of the row explains itself without a join;
+ * `baseUploadFailureReason` strips that qualifier for classification.
+ *
+ * `deterministic` for the same reason as the bare attribution labels below: the
+ * scan completed and produced no target, so repeating it changes nothing.
+ * Widening the operator's approved roots can change it — a human decision, not a
+ * retry.
+ */
+export const NOT_UPLOADABLE_ATTRIBUTION_STATE = "not_uploadable_attribution_state";
+/** Longest label the ambient envelope's `SafeLabelSchema` accepts. */
+const MAX_UPLOAD_REASON_LENGTH = 120;
+/**
+ * Compose the withheld-by-attribution reason for one session.
+ *
+ * The detail is the attribution reason that decided it. Anything outside the
+ * safe-label charset — colons included, so the stem always ends at the first one
+ * — collapses to `_`, and an empty or unusable detail degrades to the bare stem
+ * rather than inventing one.
+ */
+export function notUploadableAttributionStateReason(attributionReason) {
+    const detail = (attributionReason ?? "")
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_.-]+/gu, "_")
+        .replace(/^_+|_+$/gu, "");
+    if (!detail)
+        return NOT_UPLOADABLE_ATTRIBUTION_STATE;
+    const budget = MAX_UPLOAD_REASON_LENGTH - NOT_UPLOADABLE_ATTRIBUTION_STATE.length - 1;
+    return `${NOT_UPLOADABLE_ATTRIBUTION_STATE}:${detail.slice(0, budget)}`;
+}
 const UPLOAD_FAILURE_CLASSES = {
     // Budgets and locks: the file was fine and the run simply ran out of room or
     // was beaten to it. The next pass has room.
@@ -51,6 +136,16 @@ const UPLOAD_FAILURE_CLASSES = {
     // now name themselves instead of going silent. Transient because the object
     // was never offered a chance to upload — nothing about it was refused.
     begin_batch_server_error: "transient",
+    // The platform killed the commit process before the route could answer
+    // (BLI-3067). Transient for the same reason as the batch error above: nothing
+    // decided anything about these bytes, so the next attempt is not a repeat of
+    // a refusal. It is bounded rather than infinite because a repeatedly failing
+    // object falls into delivery backoff after the first failure, so a genuinely
+    // un-committable object costs ~4 attempts a day instead of 96.
+    [COMMIT_CRASHED_PLATFORM]: "transient",
+    // Held on purpose by that same backoff. The bytes are staged and eligible;
+    // the clock has not come round yet.
+    [DELIVERY_BACKOFF_HOLDING]: "transient",
     // The file itself is the problem, and it will be the same size and the same
     // shape on the next pass. Retrying is a promise nobody can keep.
     file_too_large: "deterministic",
@@ -69,6 +164,10 @@ const UPLOAD_FAILURE_CLASSES = {
     cwd_not_a_repo: "deterministic",
     no_repo_signals: "deterministic",
     multiple_worktrees_close_scores: "deterministic",
+    // The upload policy declined the session's attribution state outright
+    // (BLI-3272). Same shape of answer as the four above — the scan finished and
+    // there is nowhere to put the object — so the same class.
+    [NOT_UPLOADABLE_ATTRIBUTION_STATE]: "deterministic",
     // Working as designed. Never retry these — a retry here is an attempt to get
     // a redaction guard to change its mind.
     secret_like_content_guard: "withheld_by_policy",
@@ -77,11 +176,46 @@ const UPLOAD_FAILURE_CLASSES = {
     // The server-side name for the same guard, returned by the commit route.
     secret_guard_rejected: "withheld_by_policy",
 };
+const HTTP_STATUS_SUFFIX = /_http_\d{3}$/u;
+/**
+ * The listed reason a composed label is a variant of, or the label unchanged.
+ *
+ * The collector appends the observed status to some labels so an operator can
+ * tell a 502 from a 500 (`commit_crashed_platform_http_502`). Stripping it is
+ * deliberately NOT pattern matching on the label's words: the suffix is only
+ * removed when what remains is a reason somebody has already classified by
+ * hand, so `commit_failed_http_503` — whose stem nobody has reasoned about —
+ * still classifies as `unknown`, exactly as before.
+ */
+export function baseUploadFailureReason(reason) {
+    const httpStem = reason.replace(HTTP_STATUS_SUFFIX, "");
+    if (httpStem !== reason) {
+        return Object.hasOwn(UPLOAD_FAILURE_CLASSES, httpStem) ? httpStem : reason;
+    }
+    // Same contract for the `:detail` qualifier the withheld-by-attribution label
+    // carries (BLI-3272): the colon is only a separator when what precedes it is
+    // already a classified reason, so nothing an unlisted label happens to
+    // contain can smuggle it into a class.
+    const separator = reason.indexOf(":");
+    if (separator > 0) {
+        const qualifierStem = reason.slice(0, separator);
+        if (Object.hasOwn(UPLOAD_FAILURE_CLASSES, qualifierStem)) {
+            return qualifierStem;
+        }
+    }
+    return reason;
+}
 /** Classify a persisted upload reason. Unlisted reasons stay `unknown`. */
 export function classifyUploadFailure(reason) {
     if (!reason)
         return "unknown";
-    return UPLOAD_FAILURE_CLASSES[reason] ?? "unknown";
+    const label = baseUploadFailureReason(reason);
+    // `hasOwn` rather than a bare index: a reason called `constructor` or
+    // `toString` would otherwise resolve to an inherited property and answer
+    // something that is not an UploadFailureClass at all.
+    if (!Object.hasOwn(UPLOAD_FAILURE_CLASSES, label))
+        return "unknown";
+    return UPLOAD_FAILURE_CLASSES[label] ?? "unknown";
 }
 /**
  * Whether repeating the identical attempt could plausibly succeed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bli-cockpit/telemetry-core",
-  "version": "0.1.20",
+  "version": "0.1.23",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",