chore: merge main into codex/audit-python-bytecode

src/application/frida/FridaInstrumentationService.test.ts

@@ -100,7 +100,6 @@ it("keeps default Frida status identity and messages and refreshes every summary
     messages: [{ observed: 1 }],
     messages_truncated: false,
   });
-  expect(complete.value.normalized_result).not.toHaveProperty("capture_limits");
   expect(complete.value.limitations.join("\n")).not.toContain(
     "no runtime override",
   );
@@ -121,7 +120,6 @@ it("keeps default Frida status identity and messages and refreshes every summary
     },
   });
   expect(JSON.stringify(summary.value)).not.toContain('"messages":');
-  expect(JSON.stringify(summary.value)).not.toContain('"capture_limits":');
   expect(reads).toBe(2);
   const parent = [...records.values()][0];
   expect(parent?.normalized_result).toMatchObject({
@@ -129,7 +127,7 @@ it("keeps default Frida status identity and messages and refreshes every summary
   });
   expect(parent?.limitations).toEqual(
     expect.arrayContaining([
-      expect.stringContaining("selected value is unknown"),
+      expect.stringContaining("16777216"),
       expect.stringContaining(
         "Already discarded observations cannot be recovered",
       ),
@@ -164,9 +162,7 @@ it("names the Frida field cap and ignores flags inside a caller payload", () =>
   });
   if (!result.ok) throw result.error;
   const text = result.value.limitations.join("\n");
-  expect(text).toContain("capture_limits.message_text_bytes");
-  expect(text).toContain("selected value is unknown");
-  expect(text).not.toContain("32768");
+  expect(text).toContain("32768");
   expect(text).not.toContain("16777216");
   expect(text).not.toContain("4096");
 });

src/artifacts/pyinstaller/MarshalSubset.test.ts

@@ -20,6 +20,11 @@ it("reads a Python 3.9 reference-flagged PYZ table", () => {
   ]);
 });
 
+it("reads marshal one-byte string tags as Latin-1", () => {
+  for (const hex of ["6101000000e9", "4101000000e9", "7a01e9", "5a01e9"])
+    expect(readMarshalSubset(bytes(hex))).toEqual({ ok: true, value: "é" });
+});
+
 it("decodes CPython marshal Unicode with surrogatepass", () => {
   expect(
     readMarshalSubset(

src/artifacts/pyinstaller/MarshalSubset.ts

@@ -168,14 +168,8 @@ const readAsciiBytes = (
 ): Result<string, PyInstallerFailure> => {
   const bytes = readBytes(cursor, length);
   if (!bytes.ok) return bytes;
-  if (bytes.value.some((byte) => byte > 0x7f))
-    return err(
-      pyInstallerFailure(
-        "format",
-        "PYZ marshal ASCII string contains a non-ASCII byte",
-      ),
-    );
-  return ok(bytes.value.toString("ascii"));
+  // These tags use CPython's one-byte Unicode constructor, not an ASCII check.
+  return ok(bytes.value.toString("latin1"));
 };
 
 const readUtf8 = (

src/contracts/fridaToolContracts.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { toolContract, TOOL_CONTRACTS } from "./toolContracts.js";
+import { TOOL_CONTRACTS } from "./toolContracts.js";
 import { FRIDA_KEEPALIVE_INTERVAL_DESCRIPTION } from "./fridaToolContracts.js";
 import { isValidFridaRemoteAddress } from "../domain/fridaRemoteAddress.js";
 
@@ -168,48 +168,3 @@ describe("Frida tool contracts", () => {
     expect(isValidFridaRemoteAddress("user@frida-target")).toBe(false);
   });
 });
-
-it("keeps request defaults out of observed Frida policies", () => {
-  const start = toolContract("start_frida_session");
-  const identity = {
-    session_id: "00000000-0000-4000-8000-000000000001",
-    device_id: "fixture",
-    target: "fixture",
-    pid: 1,
-    mode: "attach",
-    state: "detached",
-  };
-  expect(
-    start.inputSchema.parse({
-      mode: "attach",
-      pid: 1,
-      capture_limits: { session_bytes: 12345 },
-    }),
-  ).toEqual({
-    mode: "attach",
-    pid: 1,
-    capture_limits: { session_bytes: 12345 },
-  });
-  expect(start.outputSchema.parse(identity)).not.toHaveProperty(
-    "capture_limits",
-  );
-  for (const capture_limits of [
-    {},
-    { session_bytes: 12345 },
-    { session_bytes: -1 },
-  ])
-    expect(
-      start.outputSchema.safeParse({ ...identity, capture_limits }).success,
-    ).toBe(false);
-  const capture_limits = {
-    session_bytes: 12345,
-    message_type_bytes: 456,
-    message_text_bytes: 789,
-    json_nodes: 100,
-    json_depth: 10,
-  };
-  expect(start.outputSchema.parse({ ...identity, capture_limits })).toEqual({
-    ...identity,
-    capture_limits,
-  });
-});

src/domain/fridaCapturePolicy.ts

@@ -7,8 +7,8 @@ export const FRIDA_CAPTURE_MAX_JSON_DEPTH = MAX_JSON_DEPTH - 8;
 const CAPTURE_POLICY_DESCRIPTION =
   "Retention budgets selected before attaching or spawning, fixed for this session. Defaults: 16 MiB session, 4 KiB type, 32 KiB error text, 250000 JSON nodes and depth64. Session bytes include JSON/base64 expansion and capture metadata; a budget too small for one event retains no event. Raising these cannot recover already discarded observations or raise MCP/client delivery limits. Select larger budgets before a new explicitly chosen experiment; no REA restart is required.";
 
-/** Defaults belong to the session owner, before attachment. */
-const sessionCapturePolicySchema = z
+/** Capture policy is accepted before attachment and remains fixed for that session. */
+export const fridaCapturePolicySchema = z
   .strictObject({
     session_bytes: z
       .int()
@@ -27,31 +27,31 @@ const sessionCapturePolicySchema = z
   })
   .describe(CAPTURE_POLICY_DESCRIPTION);
 
-/** Observations report a full policy or omit it; omitted facts have no defaults. */
-export const fridaCapturePolicySchema = z
-  .strictObject({
-    session_bytes:
-      sessionCapturePolicySchema.shape.session_bytes.removeDefault(),
-    message_type_bytes:
-      sessionCapturePolicySchema.shape.message_type_bytes.removeDefault(),
-    message_text_bytes:
-      sessionCapturePolicySchema.shape.message_text_bytes.removeDefault(),
-    json_nodes: sessionCapturePolicySchema.shape.json_nodes.removeDefault(),
-    json_depth: sessionCapturePolicySchema.shape.json_depth.removeDefault(),
-  })
-  .describe(
-    "Retention budgets reported by the session owner. An omitted policy is unknown.",
-  );
-
 /** Request fields preserve omission; defaults are resolved only by the session owner. */
-export const fridaCapturePolicyInputSchema = fridaCapturePolicySchema
-  .partial()
+export const fridaCapturePolicyInputSchema = z
+  .strictObject({
+    session_bytes: fridaCapturePolicySchema.shape.session_bytes
+      .removeDefault()
+      .optional(),
+    message_type_bytes: fridaCapturePolicySchema.shape.message_type_bytes
+      .removeDefault()
+      .optional(),
+    message_text_bytes: fridaCapturePolicySchema.shape.message_text_bytes
+      .removeDefault()
+      .optional(),
+    json_nodes: fridaCapturePolicySchema.shape.json_nodes
+      .removeDefault()
+      .optional(),
+    json_depth: fridaCapturePolicySchema.shape.json_depth
+      .removeDefault()
+      .optional(),
+  })
   .describe(CAPTURE_POLICY_DESCRIPTION);
 
-export const resolveFridaCapturePolicy = (input: unknown) =>
-  sessionCapturePolicySchema.safeParse(input);
-
 export type FridaCapturePolicy = z.output<typeof fridaCapturePolicySchema>;
 export type FridaCapturePolicyInput = z.input<
   typeof fridaCapturePolicyInputSchema
 >;
+export const DEFAULT_FRIDA_CAPTURE_POLICY = Object.freeze(
+  fridaCapturePolicySchema.parse({}),
+);

src/frida/FridaInstrumentationManager.test.ts

@@ -268,13 +268,11 @@ describe("FridaInstrumentationManager", () => {
     expect(fridaCaptureLimitations({ messages_truncated: false })).toEqual([]);
     expect(
       fridaCaptureLimitations({ messages_truncated: true }).join("\n"),
-    ).toContain("selected value is unknown");
+    ).toContain("16777216");
     const field = fridaCaptureLimitations({
       messages: [{ type_truncated: true }],
     }).join("\n");
-    expect(field).toContain("capture_limits.message_type_bytes");
-    expect(field).toContain("selected value is unknown");
-    expect(field).not.toContain("4096");
+    expect(field).toContain("4096");
     expect(field).not.toContain("16777216");
     const text = fridaCaptureLimitations({
       messages: [
@@ -284,9 +282,7 @@ describe("FridaInstrumentationManager", () => {
         },
       ],
     }).join("\n");
-    expect(text).toContain("capture_limits.message_text_bytes");
-    expect(text).toContain("selected value is unknown");
-    expect(text).not.toContain("32768");
+    expect(text).toContain("32768");
     expect(text).not.toContain("16777216");
     expect(text).not.toContain("4096");
     expect(
@@ -1931,21 +1927,3 @@ it("retries only unresolved sessions and resolves the typed close aggregate", as
   expect(calls).toEqual([2, 1]);
   expect(failure.cleanupIncomplete).toBe(false);
 });
-
-// Malformed or partial observations do not establish the session's policy.
-it.each([{}, { session_bytes: 12345 }, { session_bytes: -1 }])(
-  "keeps observed capture policy unknown for %j",
-  (capture_limits) => {
-    const text = fridaCaptureLimitations({
-      capture_limits,
-      messages_truncated: true,
-      messages: [{ type_truncated: true, description_truncated: true }],
-    }).join("\n");
-    expect(text).toContain("selected value is unknown");
-    for (const invented of ["16777216", "4096", "32768"])
-      expect(text).not.toContain(invented);
-    expect(text).toContain(
-      "Already discarded observations cannot be recovered",
-    );
-  },
-);

src/frida/FridaInstrumentationManager.ts

@@ -49,7 +49,7 @@ import {
   type FridaOwnedCaptureLimit,
 } from "./fridaCaptureLimits.js";
 import {
-  resolveFridaCapturePolicy,
+  fridaCapturePolicySchema,
   type FridaCapturePolicy,
 } from "../domain/fridaCapturePolicy.js";
 import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
@@ -305,7 +305,9 @@ export class FridaInstrumentationManager implements FridaInstrumentationPort {
   async #startSession(
     input: StartFridaSessionInput,
   ): Promise<Result<FridaSessionObservation, AnalysisError>> {
-    const policy = resolveFridaCapturePolicy(input.captureLimits ?? {});
+    const policy = fridaCapturePolicySchema.safeParse(
+      input.captureLimits ?? {},
+    );
     if (!policy.success)
       return err(
         analysisInputErrorFromIssues(

src/frida/fridaCaptureLimits.ts

@@ -1,4 +1,5 @@
 import {
+  DEFAULT_FRIDA_CAPTURE_POLICY,
   fridaCapturePolicySchema,
   FRIDA_CAPTURE_MAX_JSON_DEPTH,
   type FridaCapturePolicy,
@@ -31,35 +32,28 @@ const namedLimit = (value: unknown): FridaOwnedCaptureLimit | undefined =>
 
 const limitationFor = (
   limit: FridaOwnedCaptureLimit,
-  policy: FridaCapturePolicy | undefined,
+  policy: FridaCapturePolicy,
 ): string => {
-  const recover = (
-    field: string,
-    value: number | undefined,
-    unit: string,
-  ): string =>
-    value === undefined
-      ? `Frida capture reached capture_limits.${field}; its selected value is unknown because the observation did not report a valid capture policy. Select capture_limits.${field} before starting a new explicitly chosen session or instrument_with_frida experiment. Already discarded observations cannot be recovered. Session bytes and MCP/client delivery budgets remain independent.`
-      : `Frida capture reached capture_limits.${field} (${String(value)} ${unit}). Select a larger capture_limits.${field} before starting a new explicitly chosen session or instrument_with_frida experiment; no REA restart is required. Already discarded observations cannot be recovered. Session bytes and MCP/client delivery budgets remain independent.`;
+  const recover = (field: string, value: number, unit: string): string =>
+    `Frida capture reached capture_limits.${field} (${String(value)} ${unit}). Select a larger capture_limits.${field} before starting a new explicitly chosen session or instrument_with_frida experiment; no REA restart is required. Already discarded observations cannot be recovered. Session bytes and MCP/client delivery budgets remain independent.`;
   switch (limit) {
     case "session_bytes":
     case "payload_bytes":
     case "binary_bytes":
       return recover(
         "session_bytes",
-        policy?.session_bytes,
+        policy.session_bytes,
         "bytes including JSON/base64 expansion and metadata",
       );
     case "message_type":
-      return recover("message_type_bytes", policy?.message_type_bytes, "bytes");
+      return recover("message_type_bytes", policy.message_type_bytes, "bytes");
     case "message_text":
-      return recover("message_text_bytes", policy?.message_text_bytes, "bytes");
+      return recover("message_text_bytes", policy.message_text_bytes, "bytes");
     case "json_nodes":
-      return recover("json_nodes", policy?.json_nodes, "nodes");
+      return recover("json_nodes", policy.json_nodes, "nodes");
     case "json_depth":
-      return policy === undefined ||
-        policy.json_depth < FRIDA_CAPTURE_MAX_JSON_DEPTH
-        ? recover("json_depth", policy?.json_depth, "levels") +
+      return policy.json_depth < FRIDA_CAPTURE_MAX_JSON_DEPTH
+        ? recover("json_depth", policy.json_depth, "levels") +
             ` The maximum is ${String(FRIDA_CAPTURE_MAX_JSON_DEPTH)} levels, reserving the surrounding Evidence envelope.`
         : `Frida capture reached capture_limits.json_depth (${String(policy.json_depth)} levels), the shared JSON representation allowance after reserving the Evidence envelope. No higher depth is supported. Select a script that sends shallower payloads for a new explicitly chosen experiment. Already discarded observations cannot be recovered.`;
     case "unrepresentable":
@@ -106,7 +100,8 @@ export const fridaCaptureLimitations = (result: unknown): readonly string[] => {
     typeof result === "object" && result !== null && "capture_limits" in result
       ? fridaCapturePolicySchema.safeParse(result.capture_limits)
       : undefined;
-  const policy = selected?.success === true ? selected.data : undefined;
+  const policy =
+    selected?.success === true ? selected.data : DEFAULT_FRIDA_CAPTURE_POLICY;
   collectOwnedCaps(result, caps);
   return FRIDA_OWNED_CAPTURE_LIMITS.flatMap((limit) =>
     caps.has(limit) ? [limitationFor(limit, policy)] : [],

src/python/PythonPycParser.test.ts

@@ -407,6 +407,30 @@ it("charges long digits to the string budget and keeps large previews bounded",
   );
 });
 
+it("reads marshal one-byte string tags as Latin-1 with Unicode identity", () => {
+  for (const tag of [0x61, 0x41, 0x7a, 0x5a]) {
+    const encoded = Buffer.concat([
+      Buffer.from([tag]),
+      tag === 0x61 || tag === 0x41 ? u32(1) : Buffer.from([1]),
+      Buffer.from([0xe9]),
+    ]);
+    const sameUnicode = marshalUnicode(Buffer.from("é", "utf8"));
+    const set = Buffer.concat([
+      Buffer.from([0x3c]),
+      u32(2),
+      encoded,
+      sameUnicode,
+    ]);
+    const report = root(parse(withConsts([encoded, set])));
+    expect(report.consts[0]).toMatchObject({
+      kind: "str",
+      value: "é",
+      bytes: 1,
+    });
+    expect(report.consts[1]).toEqual({ kind: "set", length: 1 });
+  }
+});
+
 it("decodes marshal strings with CPython surrogatepass rules", () => {
   const report = parse(
     withConsts([marshalUnicode(Buffer.from("efbbbf73eda080efbbbf", "hex"))]),
@@ -1534,6 +1558,36 @@ it("hashes a long TYPE_REF tuple chain without recursing", () => {
   expect(pythonPycSchema.safeParse(report).success).toBe(true);
 });
 
+it("hashes shallow TYPE_REF code chains without using the JavaScript stack", () => {
+  const links = 3000;
+  const codes = Array.from({ length: links }, (_, index) =>
+    marshalCode("py311", {
+      flagged: true,
+      name: "f",
+      consts: index === 0 ? [Buffer.from([0x4e])] : [marshalRef(index - 1)],
+    }),
+  );
+  const bytes = Buffer.concat([
+    pythonPycHeader(3531),
+    marshalCode("py311", {
+      constsObject: Buffer.concat([
+        Buffer.from([0x28]),
+        u32(links + 1),
+        ...codes,
+        Buffer.from([0x3c]),
+        u32(1),
+        marshalRef(links - 1),
+      ]),
+    }),
+  ]);
+  const report = parseWith(bytes, { max_objects: 65_536 });
+  expect(root(report).consts.at(-1)).toEqual({ kind: "set", length: 1 });
+  expect(report.coverage).toMatchObject({
+    status: "complete",
+    code_objects: links + 1,
+  });
+});
+
 it("rejects code CPython treats as corrupt instead of complete coverage", () => {
   const file = (
     layout: "py37" | "py38" | "py311",

src/python/PythonPycParser.ts

@@ -332,7 +332,7 @@ class MarshalReader {
   readonly #codeKeys = new WeakMap<CodeNode, string>();
   readonly #codeIdentities = new WeakMap<CodeNode, number>();
   readonly #codeEquality = new WeakMap<CodeNode, CodeEquality>();
-  /** Python hashability per code object. False while that check is in progress. */
+  /** Completed Python hashability checks per code object. */
   readonly #codeHashable = new WeakMap<CodeNode, boolean>();
   /** Tuples whose items are still being read; CPython cannot hash them yet. */
   readonly #readingTuples = new WeakSet<MarshalValue>();
@@ -436,13 +436,19 @@ class MarshalReader {
         };
       case TYPE_INTERNED:
       case TYPE_UNICODE:
-        return this.utf8(this.nonNegativeInt32("Marshal string length"), false);
+        return this.string(
+          this.nonNegativeInt32("Marshal string length"),
+          "utf8",
+        );
       case TYPE_ASCII:
       case TYPE_ASCII_INTERNED:
-        return this.utf8(this.nonNegativeInt32("Marshal string length"), true);
+        return this.string(
+          this.nonNegativeInt32("Marshal string length"),
+          "latin1",
+        );
       case TYPE_SHORT_ASCII:
       case TYPE_SHORT_ASCII_INTERNED:
-        return this.utf8(this.u8(), true);
+        return this.string(this.u8(), "latin1");
       case TYPE_TUPLE:
         return this.sequenceValue(
           "tuple",
@@ -1309,13 +1315,70 @@ class MarshalReader {
   #isCodeHashable(node: CodeNode): boolean {
     const known = this.#codeHashable.get(node);
     if (known !== undefined) return known;
-    this.#codeHashable.set(node, false);
-    const material =
-      this.#codeEquality.get(node) ??
-      malformed("Code object is missing equality material.");
-    const hashable = this.#equalityKey(material.constsTuple, "hash") !== null;
-    this.#codeHashable.set(node, hashable);
-    return hashable;
+    const frames: { value: MarshalValue; finish: boolean }[] = [
+      { value: { kind: "code", value: node }, finish: false },
+    ];
+    const gray = new Set<MarshalValue | CodeNode>();
+    const complete = new Set<MarshalValue>();
+    const reject = (): false => {
+      this.#codeHashable.set(node, false);
+      return false;
+    };
+    while (frames.length > 0) {
+      this.#takeKeyStep();
+      const frame = frames.pop()!;
+      const value = frame.value;
+      const identity = value.kind === "code" ? value.value : value;
+      if (frame.finish) {
+        gray.delete(identity);
+        if (value.kind === "code") {
+          const material =
+            this.#codeEquality.get(value.value) ??
+            malformed("Code object is missing equality material.");
+          // Child code checks are now complete, so the existing tuple key
+          // walker preserves its equality and expansion budgets without recursion.
+          const hashable =
+            this.#equalityKey(material.constsTuple, "hash") !== null;
+          this.#codeHashable.set(value.value, hashable);
+          if (!hashable) return reject();
+        } else complete.add(value);
+        continue;
+      }
+      if (value.kind === "code") {
+        const cached = this.#codeHashable.get(value.value);
+        if (cached === false) return reject();
+        if (cached === true) continue;
+      } else {
+        const cached = this.#keyCache.get(value);
+        if (cached === null) return reject();
+        if (cached !== undefined || complete.has(value)) continue;
+      }
+      if (
+        gray.has(identity) ||
+        this.#readingTuples.has(value) ||
+        value.kind === "list" ||
+        value.kind === "set" ||
+        value.kind === "dict" ||
+        value.kind === "null"
+      )
+        return reject();
+      const children =
+        value.kind === "code"
+          ? [
+              (
+                this.#codeEquality.get(value.value) ??
+                malformed("Code object is missing equality material.")
+              ).constsTuple,
+            ]
+          : value.kind === "tuple" || value.kind === "frozenset"
+            ? value.items
+            : [];
+      gray.add(identity);
+      frames.push({ value, finish: true });
+      for (let index = children.length - 1; index >= 0; index -= 1)
+        frames.push({ value: children[index]!, finish: false });
+    }
+    return true;
   }
 
   #codeIdentity(node: CodeNode): number {
@@ -1492,17 +1555,20 @@ class MarshalReader {
     );
   }
 
-  utf8(length: number, ascii: boolean): MarshalValue {
+  string(length: number, encoding: "latin1" | "utf8"): MarshalValue {
     const bytes = this.blob(length);
-    if (ascii) {
-      if (bytes.some((byte) => byte > 0x7f))
-        malformed("Marshal ASCII string contains a non-ASCII byte.");
+    if (encoding === "latin1") {
+      // CPython reads the ASCII-tagged forms as one-byte Unicode, even when
+      // high bytes appear. Identity must agree with the UTF-8 string form.
+      const value = bytes.toString("latin1");
       return {
         kind: "str",
-        value: bytes.toString("latin1"),
+        value,
         previewEnd: Math.min(length, PYTHON_PYC_CONST_PREVIEW_LIMIT),
         bytes: length,
-        raw: bytes,
+        raw: bytes.some((byte) => byte > 0x7f)
+          ? Buffer.from(value, "utf8")
+          : bytes,
       };
     }
     const decoded = decodeMarshalUtf8(bytes, PYTHON_PYC_CONST_PREVIEW_LIMIT);