@elizaos/app-core 2.0.0-alpha.85 → 2.0.0-beta.2

package/scripts/aosp/lib/load-variant-config.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// Read the host app's `app.config.ts` and extract the `aosp:` variant
+// block via regex. Mirrors `run-mobile-build.mjs:readAppIdentity()` —
+// build-time scripts never TS-import `app.config.ts` because they have
+// to run under bare node before any build step has produced the
+// transpiled JS.
+//
+// Returns:
+//   - the parsed `AospVariantConfig` object on success,
+//   - `null` when `app.config.ts` exists but has no `aosp:` block (the
+//     fork doesn't ship an AOSP image — toolkit scripts treat this as
+//     "nothing to do" and exit 0),
+//   - throws when `app.config.ts` cannot be read or is malformed.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Load the AOSP variant config from a host app's `app.config.ts`.
+ *
+ * @param {object} options
+ * @param {string} options.appConfigPath  Absolute path to app.config.ts.
+ *                                        Caller resolves relative to
+ *                                        the host's main app dir.
+ * @returns {object|null}
+ */
+export function loadAospVariantConfig({ appConfigPath }) {
+  if (!fs.existsSync(appConfigPath)) {
+    throw new Error(
+      `[aosp] app.config.ts not found at ${appConfigPath}. ` +
+        `Pass --app-config <PATH> if your config lives elsewhere.`,
+    );
+  }
+  const src = fs.readFileSync(appConfigPath, "utf8");
+
+  // Find the `aosp: { ... }` block. Use a balanced-brace scan so nested
+  // objects (none today, but reserved) don't trip a greedy regex.
+  const blockBody = extractObjectBlockBody(src, "aosp");
+  if (blockBody === null) {
+    // Fork without an AOSP image. The caller decides whether that's an
+    // error or a no-op.
+    return null;
+  }
+
+  const productLunch = matchString(blockBody, "productLunch");
+  const vendorDir = matchString(blockBody, "vendorDir");
+  const variantName = matchString(blockBody, "variantName");
+  const productName = matchString(blockBody, "productName");
+  const packageName = matchString(blockBody, "packageName");
+  const appName = matchString(blockBody, "appName");
+  const commonMk = matchString(blockBody, "commonMk");
+  const modelSourceLabel = matchString(blockBody, "modelSourceLabel");
+  const bootanimationAssetDir = matchString(blockBody, "bootanimationAssetDir");
+  const cuttlefishDeviceDir = matchString(blockBody, "cuttlefishDeviceDir");
+  const propertyPrefix = matchString(blockBody, "propertyPrefix");
+
+  const required = {
+    productLunch,
+    vendorDir,
+    variantName,
+    productName,
+    packageName,
+    appName,
+    commonMk,
+    modelSourceLabel,
+  };
+  const missing = Object.entries(required)
+    .filter(([, value]) => !value)
+    .map(([key]) => key);
+  if (missing.length > 0) {
+    throw new Error(
+      `[aosp] app.config.ts > aosp: block is missing required field(s): ` +
+        `${missing.join(", ")}. See AospVariantConfig in @elizaos/app-core.`,
+    );
+  }
+
+  return {
+    productLunch,
+    vendorDir,
+    variantName,
+    productName,
+    packageName,
+    appName,
+    commonMk,
+    modelSourceLabel,
+    // System-property prefix used by `init.<vendorDir>.rc` (e.g.
+    // `miladyos.boot_phase`, `elizaos.boot_phase`). Defaults to the
+    // vendor dir when forks haven't customized — that's the common
+    // Android convention. Forks like Milady whose property namespace
+    // differs from the vendor dir name (vendor=milady, props=miladyos)
+    // declare it explicitly.
+    propertyPrefix: propertyPrefix ?? vendorDir,
+    bootanimationAssetDir: bootanimationAssetDir ?? undefined,
+    cuttlefishDeviceDir: cuttlefishDeviceDir ?? undefined,
+  };
+}
+
+/**
+ * Resolve an `app.config.ts` path. CLI flag wins; otherwise default to
+ * `<repoRoot>/apps/app/app.config.ts` (the elizaOS host convention).
+ *
+ * @param {object} options
+ * @param {string} options.repoRoot
+ * @param {string|null|undefined} options.flagValue  The value passed
+ *                                                   to --app-config.
+ * @returns {string}  Absolute path to app.config.ts.
+ */
+export function resolveAppConfigPath({ repoRoot, flagValue }) {
+  if (flagValue) return path.resolve(flagValue);
+  return path.join(repoRoot, "apps", "app", "app.config.ts");
+}
+
+/**
+ * Walk the source from the start of `<key>:` looking for a matching
+ * pair of braces. Returns the inner text (between the outer `{` and
+ * `}`) or `null` when the key is not present.
+ *
+ * Handles nested braces, simple string-literal escapes, and line
+ * comments (// ...). Does NOT handle block comments inside the body —
+ * `app.config.ts` doesn't ship those today, and rejecting them is
+ * fine.
+ */
+function extractObjectBlockBody(src, key) {
+  const re = new RegExp(`\\b${key}\\s*:\\s*\\{`);
+  const m = re.exec(src);
+  if (!m) return null;
+  const start = m.index + m[0].length; // position of the char after `{`
+  let depth = 1;
+  let i = start;
+  while (i < src.length && depth > 0) {
+    const ch = src[i];
+    if (ch === "{") {
+      depth += 1;
+      i += 1;
+      continue;
+    }
+    if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        return src.slice(start, i);
+      }
+      i += 1;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      i = skipStringLiteral(src, i);
+      continue;
+    }
+    if (ch === "/" && src[i + 1] === "/") {
+      const nl = src.indexOf("\n", i + 2);
+      i = nl < 0 ? src.length : nl + 1;
+      continue;
+    }
+    i += 1;
+  }
+  throw new Error(
+    `[aosp] Could not parse app.config.ts: unbalanced braces in \`${key}:\` block.`,
+  );
+}
+
+function skipStringLiteral(src, start) {
+  const quote = src[start];
+  let i = start + 1;
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === "\\") {
+      i += 2;
+      continue;
+    }
+    if (ch === quote) return i + 1;
+    i += 1;
+  }
+  throw new Error(
+    `[aosp] Could not parse app.config.ts: unterminated string literal.`,
+  );
+}
+
+function matchString(body, key) {
+  const re = new RegExp(`\\b${key}\\s*:\\s*["'\`]([^"'\`]+)["'\`]`);
+  const m = re.exec(body);
+  return m ? m[1] : null;
+}

package/scripts/aosp/lint-init-rc.mjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+// Lints an Android init.rc file against the documented init language.
+//
+// Catches typos that AOSP's init parser would only surface at boot time
+// (e.g. `on bootp`, `setpro foo bar`, missing exec-shell quoting).
+//
+// Reference: https://android.googlesource.com/platform/system/core/+/master/init/README.md
+//
+// Usage:
+//   node eliza/packages/app-core/scripts/aosp/lint-init-rc.mjs <FILE> [<FILE>...]
+//
+// Generic — knows nothing about the AOSP variant config. Callers pass
+// any path; the linter only inspects the file's syntax.
+
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+// init.cpp recognises specific top-level section keywords. Any other
+// keyword at column zero is a syntax error at boot.
+const TOP_LEVEL_KEYWORDS = new Set(["on", "service", "import", "subsystem"]);
+
+// `on <event>` event names. Not exhaustive — init also supports
+// property triggers (`on property:foo=bar`) and AND-combined triggers
+// (`on boot && property:foo=bar`). The validator below handles those.
+const ON_EVENTS = new Set([
+  "early-init",
+  "init",
+  "late-init",
+  "early-fs",
+  "fs",
+  "post-fs",
+  "post-fs-data",
+  "late-fs",
+  "boot",
+  "charger",
+  "fs-encryption-init-user-0",
+  "post-fs-data-init-user-0",
+  "shutdown",
+  "userspace-reboot-requested",
+  "early-boot",
+  "load-persist-props-action",
+]);
+
+// Recognised commands inside `on` / `service` blocks. Init has more
+// (e.g. `bootchart`, `class_reset`), but this list catches the most
+// common typos. Unknown commands warn but don't fail — init drops
+// unknown commands at parse time with a logcat warning, not a halt.
+const KNOWN_COMMANDS = new Set([
+  "bootchart",
+  "chmod",
+  "chown",
+  "class_reset",
+  "class_restart",
+  "class_start",
+  "class_stop",
+  "copy",
+  "domainname",
+  "enable",
+  "exec",
+  "exec_background",
+  "exec_start",
+  "export",
+  "hostname",
+  "ifup",
+  "insmod",
+  "load_system_props",
+  "load_persist_props",
+  "loglevel",
+  "mark_post_data",
+  "mkdir",
+  "mount",
+  "mount_all",
+  "perform_apex_config",
+  "powerctl",
+  "restart",
+  "restorecon",
+  "restorecon_recursive",
+  "rm",
+  "rmdir",
+  "setprop",
+  "setrlimit",
+  "start",
+  "stop",
+  "swapon_all",
+  "symlink",
+  "sysclktz",
+  "trigger",
+  "umount",
+  "umount_all",
+  "verity_load_state",
+  "verity_update_state",
+  "wait",
+  "wait_for_prop",
+  "write",
+  // Vendor-extension common verbs
+  "init_user0",
+  "remount_userdata",
+]);
+
+export function lintInitRc(filePath) {
+  const issues = [];
+  const content = fs.readFileSync(filePath, "utf8");
+  const lines = content.split(/\r?\n/);
+
+  let inBlock = false;
+  let currentBlockKind = null;
+  let lastBlockHeaderLine = 0;
+
+  lines.forEach((rawLine, index) => {
+    const lineNumber = index + 1;
+    const stripped = rawLine.replace(/\r$/, "");
+    const trimmed = stripped.trim();
+
+    if (!trimmed || trimmed.startsWith("#")) return;
+
+    const indented = /^[ \t]/.test(stripped);
+    if (!indented) {
+      // Top-level directive starts a new block.
+      const [keyword, ...rest] = trimmed.split(/\s+/);
+      if (!TOP_LEVEL_KEYWORDS.has(keyword)) {
+        issues.push({
+          line: lineNumber,
+          message: `unknown top-level keyword "${keyword}" — expected one of ${[...TOP_LEVEL_KEYWORDS].join(", ")}`,
+        });
+        inBlock = false;
+        return;
+      }
+      currentBlockKind = keyword;
+      lastBlockHeaderLine = lineNumber;
+      inBlock = true;
+
+      if (keyword === "on") {
+        if (rest.length === 0) {
+          issues.push({
+            line: lineNumber,
+            message: "`on` requires a trigger expression",
+          });
+          return;
+        }
+        // Trigger may be `event` or `property:foo=bar` or combined with
+        // `&&`. Validate each clause.
+        const triggerExpr = rest.join(" ");
+        const clauses = triggerExpr.split(/\s*&&\s*/);
+        for (const clause of clauses) {
+          if (clause.startsWith("property:")) {
+            if (!/^property:[^=]+=/.test(clause)) {
+              issues.push({
+                line: lineNumber,
+                message: `malformed property trigger "${clause}" — expected property:<name>=<value>`,
+              });
+            }
+          } else if (!ON_EVENTS.has(clause)) {
+            issues.push({
+              line: lineNumber,
+              message: `unknown init event "${clause}" — expected one of ${[...ON_EVENTS].slice(0, 6).join(", ")}, ...`,
+            });
+          }
+        }
+      }
+      return;
+    }
+
+    // Indented line — must be a command inside a block.
+    if (!inBlock) {
+      issues.push({
+        line: lineNumber,
+        message: "indented command outside any on/service block",
+      });
+      return;
+    }
+
+    const [command] = trimmed.split(/\s+/);
+    if (currentBlockKind === "on" && !KNOWN_COMMANDS.has(command)) {
+      issues.push({
+        line: lineNumber,
+        message: `unknown init command "${command}" (block opened at line ${lastBlockHeaderLine}); typos here only fail at boot`,
+        soft: true,
+      });
+    }
+
+    // Common typo class: `setprop foo` with no value.
+    if (command === "setprop") {
+      const parts = trimmed.split(/\s+/);
+      if (parts.length < 3) {
+        issues.push({
+          line: lineNumber,
+          message: `setprop requires <name> <value>; got ${parts.length - 1} arg(s)`,
+        });
+      }
+    }
+
+    // exec/exec_background must have a recognised user/group prefix.
+    if (command === "exec" || command === "exec_background") {
+      const parts = trimmed.split(/\s+/).slice(1);
+      if (parts[0] !== "-" && !/^[a-z][\w.-]*$/.test(parts[0] ?? "")) {
+        issues.push({
+          line: lineNumber,
+          message: `exec requires "- <user> <group> -- <argv>" (use - for "no seclabel")`,
+        });
+      }
+      if (!trimmed.includes("--")) {
+        issues.push({
+          line: lineNumber,
+          message: `exec missing argv separator "--"`,
+          soft: true,
+        });
+      }
+    }
+  });
+
+  return issues;
+}
+
+function formatIssue(issue, filePath) {
+  const tag = issue.soft ? "WARN" : "ERROR";
+  return `${filePath}:${issue.line}: [${tag}] ${issue.message}`;
+}
+
+async function main(argv = process.argv.slice(2)) {
+  if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+    console.log(
+      "Usage: node eliza/packages/app-core/scripts/aosp/lint-init-rc.mjs <FILE> [<FILE> ...]",
+    );
+    process.exit(argv.length === 0 ? 1 : 0);
+  }
+  let hardErrors = 0;
+  for (const filePath of argv) {
+    const resolved = path.resolve(filePath);
+    if (!fs.existsSync(resolved)) {
+      console.error(`${resolved}: file not found`);
+      hardErrors += 1;
+      continue;
+    }
+    const issues = lintInitRc(resolved);
+    for (const issue of issues) {
+      const text = formatIssue(issue, resolved);
+      if (issue.soft) {
+        console.warn(text);
+      } else {
+        console.error(text);
+        hardErrors += 1;
+      }
+    }
+    if (issues.length === 0) {
+      console.log(`${resolved}: OK`);
+    }
+  }
+  process.exit(hardErrors > 0 ? 1 : 0);
+}
+
+const isMain =
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  await main();
+}

package/scripts/aosp/llama-cpp-patches/README.md

@@ -0,0 +1,49 @@
+# llama.cpp patches — DEPRECATED archival drop (2026-05-09)
+
+> **Superseded by `milady-ai/llama.cpp @ v0.1.0-milady`.** These patch
+> series are no longer applied on AOSP builds. `compile-libllama.mjs`
+> now points at the unified Milady fork, which has TBQ + QJL + Q4_POLAR
+> baked in (plus the Metal kernel sources). See
+> `docs/porting/unified-fork-strategy.md` for the migration story.
+
+The directory and `apply-patches.mjs` script are kept in-tree for one
+release as a rollback path. To re-enable the legacy flow:
+
+1. In `compile-libllama.mjs`, restore the prior pin:
+   ```js
+   export const LLAMA_CPP_TAG    = "main-b8198-b2b5273";
+   export const LLAMA_CPP_COMMIT = "b2b5273e8b275bb96362fe844a5202632eb3e52b";
+   export const LLAMA_CPP_REMOTE = "https://github.com/Apothic-AI/llama.cpp-1bit-turboquant.git";
+   ```
+2. Re-add the `applyVendoredPatches({ srcDir: cacheDir, log })` call after
+   `patchLlamaCppSourceForMusl` in `ensureLlamaCppCheckout`.
+
+The two flows produce equivalent libraries on AOSP today (W1-A and W1-B
+patches were lifted directly into the fork tree). The fork path:
+- **Eliminates** the quadratic merge-conflict cost between QJL and
+  Polar in `ggml-common.h` / `ggml-cpu.c` (both modified the same
+  type_traits table; in-tree the conflict is resolved once, in patches
+  it's resolved on every cherry-pick from a moving base).
+- **Adds** the Metal kernel sources alongside the C/NEON sources, so a
+  future `bun run build:metal` doesn't need to apply runtime patches.
+- **Standardizes** on a single `LLAMA_CPP_TAG` across the host (DFlash)
+  and AOSP build paths (next agent: align
+  `build-llama-cpp-dflash.mjs` once DFlash is ported into the fork).
+
+Once a follow-up release verifies no consumer pins the patches
+directly, this directory can be deleted.
+
+## Historical content (frozen)
+
+### `qjl/`
+Five patches that added `GGML_TYPE_QJL1_256 = 46` +
+`GGML_OP_ATTN_SCORE_QJL` to apothic@b2b5273. Now landed on
+`milady-ai/llama.cpp` branch `milady/qjl` and merged into
+`milady/integration` (slot 46 unchanged).
+
+### `polarquant/`
+Four patches that added `GGML_TYPE_Q4_POLAR = 45` to apothic@b2b5273.
+Now landed on `milady-ai/llama.cpp` branch `milady/polarquant` —
+**slot bumped from 45 to 47** so QJL (46) and Polar (47) coexist
+without colliding on the reserved hole at 45 (which was
+`GGML_TYPE_COUNT` in the TBQ-only build).

package/scripts/aosp/llama-cpp-patches/apply-patches.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// apply-patches.mjs — apply the QJL + PolarQuant patch series on top
+// of a checked-out apothic/llama.cpp-1bit-turboquant tree.
+//
+// Called from compile-libllama.mjs after the fork is cloned + checked
+// out at the pinned commit, before CMake configure.
+//
+// Idempotent: if `git am --abort` is needed (because a previous run
+// failed mid-series), the script handles it. If the patches are already
+// applied (HEAD matches the recorded final SHA), it's a no-op.
+//
+// Usage:
+//   node apply-patches.mjs --repo <path-to-llama.cpp-checkout>
+//   node apply-patches.mjs --repo <path> --series qjl,polarquant
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+// Read the first ~64 KB of a patch file as utf8 — enough to see the
+// `Subject:` line. Patches can be hundreds of KB once they include the
+// vendored kernel sources, so we cap the read.
+function readPatchFile(p) {
+  const buf = readFileSync(p);
+  return buf.subarray(0, Math.min(buf.length, 64 * 1024)).toString("utf8");
+}
+
+// Pull the `Subject:` line out of a `git format-patch`-style header.
+// Multi-line subjects are joined; the leading `[PATCH n/N]` prefix is
+// stripped so the subject matches what `git log --format=%s` emits.
+function extractSubject(text) {
+  const m = /^Subject:\s*(.+(?:\n[ \t]+.+)*)/m.exec(text);
+  if (!m) return null;
+  const joined = m[1].replace(/\n[ \t]+/g, " ").trim();
+  return joined.replace(/^\[PATCH[^\]]*\]\s*/i, "").trim();
+}
+
+// Escape a string for `git log --grep=<pattern>` when used with
+// --fixed-strings. We pass it through directly; --fixed-strings makes
+// regex metacharacters literal, so the only thing to guard against is
+// embedded newlines (subjects are joined to one line in extractSubject).
+function escapeGrep(s) {
+  return s;
+}
+
+const args = process.argv.slice(2);
+const flag = (name) => {
+  const i = args.indexOf(name);
+  return i >= 0 ? args[i + 1] : null;
+};
+
+const repo = flag("--repo");
+if (!repo) {
+  console.error("usage: apply-patches.mjs --repo <llama.cpp-checkout> [--series qjl,polarquant]");
+  process.exit(1);
+}
+if (!existsSync(path.join(repo, ".git"))) {
+  console.error(`[patches] not a git repo: ${repo}`);
+  process.exit(1);
+}
+
+const seriesArg = flag("--series");
+const seriesNames = seriesArg
+  ? seriesArg.split(",").map((s) => s.trim()).filter(Boolean)
+  : readdirSync(here, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name)
+      .sort();
+
+console.log(`[patches] applying series: ${seriesNames.join(", ")}`);
+console.log(`[patches] target repo: ${repo}`);
+
+// Quick gate: when the target repo already contains the upstream
+// markers for a series (e.g. v0.4.0-milady has QJL baked in via a merge
+// commit, so subject-grep won't match the original patch subjects),
+// skip the entire series rather than trying to apply patches that
+// would conflict with the already-present source.
+const SERIES_BAKED_IN_MARKERS = {
+  qjl: {
+    file: "ggml/include/ggml.h",
+    needle: "GGML_TYPE_QJL1_256",
+  },
+};
+
+function seriesAlreadyBakedIn(seriesName) {
+  const marker = SERIES_BAKED_IN_MARKERS[seriesName];
+  if (!marker) return false;
+  const filePath = path.join(repo, marker.file);
+  if (!existsSync(filePath)) return false;
+  try {
+    const text = readFileSync(filePath, "utf8");
+    return text.includes(marker.needle);
+  } catch {
+    return false;
+  }
+}
+
+const git = (cwd, ...gitArgs) => {
+  const res = spawnSync("git", gitArgs, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+  return {
+    code: res.status,
+    out: (res.stdout?.toString() ?? "").trim(),
+    err: (res.stderr?.toString() ?? "").trim(),
+  };
+};
+
+// If a prior `git am` was interrupted, the .git/rebase-apply dir lingers
+// and blocks new applies. Clean it up.
+if (existsSync(path.join(repo, ".git", "rebase-apply"))) {
+  console.log("[patches] aborting stale git am from previous run");
+  git(repo, "am", "--abort");
+}
+
+let appliedCount = 0;
+let skippedCount = 0;
+
+for (const series of seriesNames) {
+  const seriesDir = path.join(here, series);
+  if (!existsSync(seriesDir) || !statSync(seriesDir).isDirectory()) {
+    console.warn(`[patches] series dir missing: ${seriesDir}; skipping`);
+    continue;
+  }
+  if (seriesAlreadyBakedIn(series)) {
+    const marker = SERIES_BAKED_IN_MARKERS[series];
+    console.log(
+      `[patches] series '${series}' already in source (${marker.file} contains ${marker.needle}); skipping`,
+    );
+    continue;
+  }
+  const patches = readdirSync(seriesDir)
+    .filter((f) => /^\d+.*\.patch$/.test(f))
+    .sort();
+  if (patches.length === 0) {
+    console.warn(`[patches] no .patch files in ${seriesDir}; skipping`);
+    continue;
+  }
+
+  for (const p of patches) {
+    const full = path.join(seriesDir, p);
+    // Idempotency: skip patches whose commit subject is already in the git
+    // log on top of the base. We can't use `git apply --check -R` alone
+    // because earlier patches in a series may be modified by later ones,
+    // making a stand-alone reverse-apply false-negative even when the patch
+    // is in the tree (e.g. qjl/0002 introduces a file that qjl/0004 then
+    // edits — reverse-applying 0002 against the post-0004 tree fails
+    // because the file no longer matches the patch's pre-image).
+    //
+    // Strategy: parse the `Subject:` line out of the patch file and grep
+    // `git log --grep=` for an exact subject match in the current branch's
+    // history. Falls back to the reverse-apply check for patches without a
+    // recognisable subject header.
+    const patchText = readPatchFile(full);
+    const subject = extractSubject(patchText);
+    if (subject) {
+      const found = spawnSync(
+        "git",
+        ["log", "--all", `--grep=${escapeGrep(subject)}`, "--fixed-strings", "--format=%H"],
+        { cwd: repo, stdio: ["ignore", "pipe", "pipe"] },
+      );
+      if (found.status === 0 && (found.stdout?.toString().trim() ?? "") !== "") {
+        console.log(`[patches]   skip (already in git log): ${series}/${p}`);
+        skippedCount += 1;
+        continue;
+      }
+    } else {
+      const reverseCheck = spawnSync("git", ["apply", "--check", "-R", full], {
+        cwd: repo,
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+      if (reverseCheck.status === 0) {
+        console.log(`[patches]   skip (reverse-apply ok): ${series}/${p}`);
+        skippedCount += 1;
+        continue;
+      }
+    }
+
+    // Apply via git am to preserve commit metadata. Fall back to
+    // git apply --3way if the index is dirty (am needs a clean index).
+    const am = spawnSync("git", ["am", "--keep-non-patch", full], {
+      cwd: repo,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    if (am.status === 0) {
+      console.log(`[patches]   apply: ${series}/${p}`);
+      appliedCount += 1;
+    } else {
+      console.error(`[patches]   FAILED: ${series}/${p}`);
+      console.error(am.stderr?.toString() ?? "");
+      git(repo, "am", "--abort");
+      process.exit(1);
+    }
+  }
+}
+
+console.log(`[patches] done. applied=${appliedCount} skipped=${skippedCount}`);