@cosmicdrift/kumiko-framework 0.220.1 → 0.221.0

package/src/pipeline/__tests__/distributed-lock.integration.test.ts

@@ -90,6 +90,18 @@ describe("distributed lock", () => {
     expect(await lock.acquire("test-lock-7")).not.toBeNull();
   });
 
+  test("renew with ttlSeconds 0 does not drop the lock", async () => {
+    const lock = createDistributedLock(testRedis.redis);
+    const token = await lock.acquire("test-lock-ttl0", { ttlSeconds: 5 });
+    if (!token) throw new Error("expected token");
+    const renewed = await lock.renew("test-lock-ttl0", token, 0);
+    expect(renewed).toBe(false);
+    // Original lock still held — a peer acquire must fail.
+    const peer = await lock.acquire("test-lock-ttl0", { ttlSeconds: 5 });
+    expect(peer).toBeNull();
+    await lock.release("test-lock-ttl0", token);
+  });
+
   test("renew on an expired/absent key fails", async () => {
     const lock = createDistributedLock(testRedis.redis);
     const renewed = await lock.renew("test-lock-8-never-acquired", "some-token", 5);

package/src/pipeline/__tests__/event-dispatcher-pg-listen.integration.test.ts

@@ -1,36 +1,18 @@
 // E.4 — PG LISTEN/NOTIFY wake-up. Without this, delivery latency is
 // bounded below by pollIntervalMs. With LISTEN, event-store.append fires
-// `pg_notify` on commit and any subscribed dispatcher wakes immediately —
-// latency becomes TCP round-trip, typically sub-millisecond on localhost.
+// `pg_notify` on commit and any subscribed dispatcher wakes immediately.
 //
-// The polling timer stays on as a safety net for dropped subscriptions
-// and crashes between commit and wake. These tests pin:
-//
-//   1. NOTIFY → runOnce fires promptly, without waiting for the timer.
-//   2. The dispatcher starts cleanly when pgClient is wired and stops
-//      without leaking the LISTEN connection, and still wakes on NOTIFY
-//      after a restart cycle.
-//
-// #2042: these used to assert an absolute millisecond latency bound
-// (`< 40`, later `< 100`) against the test-stack's default 50ms polling
-// timer. On a shared CI runner a stalled event loop can push even a
-// working LISTEN's delivery past 100ms — measured up to 154ms — so no
-// millisecond bound both clears runner noise and stays under a 50ms
-// timer. Fix: push the polling timer out to 60s for this stack
-// (`eventDispatcherPollIntervalMs`) and assert delivery happens at all
-// inside a 5s window. If LISTEN is dead, nothing arrives before the 5s
-// deadline — a 12x margin under the 60s timer that no runner stall gets
-// anywhere near. If LISTEN works, delivery is near-instant regardless of
-// runner load. Verified by temporarily forcing pgClient to undefined in
-// test-stack.ts: both tests then fail at toHaveLength(1) with 0 received
-// after ~5s, confirming the assertion still discriminates.
+// The polling timer stays as a safety net. These tests pin NOTIFY wake
+// without waiting for the timer, and that start/stop still leaves LISTEN
+// working. #2042: poll interval is 60s here; assert delivery inside 5s —
+// if LISTEN is dead the timer cannot rescue the assertion.
 
 import { afterAll, beforeAll, describe, expect, test } from "bun:test";
 import { createEventStoreExecutor } from "../../db/event-store-executor";
 import { createTenantDb, type TenantDb } from "../../db/tenant-db";
 import { defineFeature } from "../../engine";
 import { setupTestStack, type TestStack, TestUsers, unsafeCreateEntityTable } from "../../stack";
-import { sharedWidgetEntity, sharedWidgetTable } from "../../testing";
+import { sharedWidgetEntity, sharedWidgetTable, waitFor } from "../../testing";
 
 // --- Fixture ---
 
@@ -85,21 +67,22 @@ describe("E.4 — PG NOTIFY/LISTEN wake-up", () => {
     try {
       await executor.create({ name: "latency-test" }, admin, tdb);
 
-      const deadline = Date.now() + 5000;
-      while (Date.now() < deadline && deliveryCount === 0) {
-        await new Promise((r) => setTimeout(r, 5));
-      }
-      expect(deliveryCount).toBe(1);
+      await waitFor(
+        () => {
+          expect(deliveryCount).toBe(1);
+        },
+        { delays: [100, 500, 1000, 3500] },
+      );
     } finally {
       await stack.eventDispatcher?.stop();
     }
   });
 
   test("dispatcher start/stop cycle with LISTEN attached still delivers after restart", async () => {
-    // Repeated start/stop must not leak connections or break LISTEN. After
-    // 3 cycles the last .start() should still wake on NOTIFY — if the
-    // unlisten handle was mishandled, the subscription would either be
-    // stale (LISTEN on a closed connection) or double-registered.
+    // Repeated start/stop must not leak connections or break LISTEN.
+    // Two start/stop cycles, then a third start() that must still wake on
+    // NOTIFY — if the unlisten handle was mishandled, the subscription
+    // would be stale or double-registered.
     for (let i = 0; i < 2; i++) {
       await stack.eventDispatcher?.start();
       await stack.eventDispatcher?.stop();
@@ -110,11 +93,12 @@ describe("E.4 — PG NOTIFY/LISTEN wake-up", () => {
     try {
       await executor.create({ name: "restart-probe" }, admin, tdb);
 
-      const deadline = Date.now() + 5000;
-      while (Date.now() < deadline && deliveryCount === 0) {
-        await new Promise((r) => setTimeout(r, 5));
-      }
-      expect(deliveryCount).toBe(1);
+      await waitFor(
+        () => {
+          expect(deliveryCount).toBe(1);
+        },
+        { delays: [100, 500, 1000, 3500] },
+      );
     } finally {
       await stack.eventDispatcher?.stop();
     }

package/src/pipeline/distributed-lock.ts

@@ -50,6 +50,9 @@ export function createDistributedLock(
     },
 
     async renew(key, token, ttlSeconds) {
+      // EXPIRE with 0/negative deletes the key but still returns 1 — reject
+      // before we claim ownership while releasing the lock.
+      if (!Number.isInteger(ttlSeconds) || ttlSeconds < 1) return false;
       const result = (await redis.eval(
         renewScript,
         1,

package/src/schema-cli.ts

@@ -11,6 +11,7 @@
 import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
 import { join, resolve as resolvePath } from "node:path";
 import {
+  assertValidMigrationName,
   baselineMigrations,
   createDbConnection,
   type DbConnection,
@@ -151,10 +152,14 @@ export async function runSchemaCli(
         out.err("  Usage: schema generate <name>");
         return 1;
       }
-      // name lands unescaped in `${seq}_${name}.sql` (generateMigration) — this
-      // allowlist blocks flag-like names and path traversal (`../../x`).
-      if (name.startsWith("-") || !/^[A-Za-z0-9_-]+$/.test(name)) {
-        out.err(`  Invalid migration name "${name}" — use letters, digits, "-", "_" only.`);
+      // name lands unescaped in `${seq}_${name}.sql` (generateMigration) —
+      // shared allowlist blocks flag-like names, path traversal, and
+      // ENAMETOOLONG-length names.
+      try {
+        assertValidMigrationName(name);
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        out.err(`  ${msg}`);
         out.err("  Usage: schema generate <name>");
         return 1;
       }

package/src/scripts/codemod/crypto-shredding-testing-move.ts

@@ -8,47 +8,55 @@
 //
 // Usage: bun scripts/codemod/crypto-shredding-testing-move.ts <targetDir> [--dry-run]
 
-import { resolve } from "node:path";
-import { Glob } from "bun";
-import { Project } from "ts-morph";
+import { type Dirent, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { Project, type SourceFile } from "ts-morph";
 
 const OLD_SPECIFIER = "@cosmicdrift/kumiko-framework/crypto";
 const NEW_SPECIFIER = "@cosmicdrift/kumiko-framework/testing";
 const MOVED_NAMES = new Set(["resetPiiSubjectKmsForTests", "resetBlindIndexKeyForTests"]);
 
+const EXCLUDE_DIRS = new Set(["node_modules", "dist", "build"]);
+
 function findTargetFiles(rootDir: string): string[] {
-  const glob = new Glob("**/*.{ts,tsx}");
-  const EXCLUDE = ["/node_modules/", "/dist/", "/build/"];
+  // Walk the tree and skip excluded dirs while descending — filtering the
+  // absolute path after a full Glob scan silently no-ops when the repo root
+  // itself contains "/build/" or "/node_modules/" (fw#2289).
   const files: string[] = [];
-  for (const file of glob.scanSync({ cwd: rootDir, dot: false })) {
-    const abs = resolve(rootDir, file);
-    if (EXCLUDE.some((p) => abs.includes(p))) continue;
-    files.push(abs);
-  }
+  const walk = (dir: string): void => {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      // skip: unreadable directory during walk — treat as empty.
+      return;
+    }
+    for (const ent of entries) {
+      if (ent.isDirectory()) {
+        if (EXCLUDE_DIRS.has(ent.name) || ent.name.startsWith(".")) continue;
+        walk(join(dir, ent.name));
+        continue;
+      }
+      if (ent.isFile() && /\.(ts|tsx)$/.test(ent.name)) {
+        files.push(join(dir, ent.name));
+      }
+    }
+  };
+  walk(rootDir);
   return files.sort();
 }
 
-async function main(): Promise<void> {
-  const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
-  const dryRun = process.argv.includes("--dry-run");
-  const rootDir = resolve(positional[0] ?? process.cwd());
-
-  const files = findTargetFiles(rootDir);
-  const project = new Project({
-    skipAddingFilesFromTsConfig: true,
-    skipFileDependencyResolution: true,
-  });
-
-  let touchedFiles = 0;
-  let movedNames = 0;
-
-  for (const file of files) {
-    const sourceFile = project.addSourceFileAtPath(file);
-    const oldImport = sourceFile
-      .getImportDeclarations()
-      .find((d) => d.getModuleSpecifierValue() === OLD_SPECIFIER);
-    if (!oldImport) continue;
+/** Move matching value imports from crypto → testing. Returns count of names moved. */
+function migrateFile(sourceFile: SourceFile): number {
+  // Value imports only — a pre-existing `import type { … } from testing`
+  // must not receive runtime helpers (they would be erased).
+  const oldImports = sourceFile
+    .getImportDeclarations()
+    .filter((d) => d.getModuleSpecifierValue() === OLD_SPECIFIER && !d.isTypeOnly());
+  if (oldImports.length === 0) return 0;
 
+  let fileMoved = 0;
+  for (const oldImport of oldImports) {
     const movedHere = oldImport.getNamedImports().filter((spec) => MOVED_NAMES.has(spec.getName()));
     if (movedHere.length === 0) continue;
 
@@ -56,7 +64,7 @@ async function main(): Promise<void> {
 
     const existingNewImport = sourceFile
       .getImportDeclarations()
-      .find((d) => d.getModuleSpecifierValue() === NEW_SPECIFIER);
+      .find((d) => d.getModuleSpecifierValue() === NEW_SPECIFIER && !d.isTypeOnly());
     if (existingNewImport) {
       const already = new Set(existingNewImport.getNamedImports().map((s) => s.getName()));
       for (const name of names) {
@@ -73,8 +81,32 @@ async function main(): Promise<void> {
       !!oldImport.getNamespaceImport();
     if (!remaining) oldImport.remove();
 
+    fileMoved += names.length;
+  }
+  return fileMoved;
+}
+
+async function main(): Promise<void> {
+  const positional = process.argv.slice(2).filter((a) => !a.startsWith("--"));
+  const dryRun = process.argv.includes("--dry-run");
+  const rootDir = resolve(positional[0] ?? process.cwd());
+
+  const files = findTargetFiles(rootDir);
+  const project = new Project({
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true,
+  });
+
+  let touchedFiles = 0;
+  let movedNames = 0;
+
+  for (const file of files) {
+    const sourceFile = project.addSourceFileAtPath(file);
+    const fileMoved = migrateFile(sourceFile);
+    if (fileMoved === 0) continue;
+
     touchedFiles++;
-    movedNames += names.length;
+    movedNames += fileMoved;
     if (!dryRun) sourceFile.saveSync();
   }
 

package/src/search/purge-subject.ts

@@ -9,11 +9,12 @@
 //      that still carry the subject key in encrypted columns.
 
 import { quoteIdent, subjectCiphertextLikePattern } from "../crypto/ciphertext-pattern";
+import { isSelfPiiField } from "../crypto/is-self-pii-field";
 import type { SubjectId } from "../crypto/kms-adapter";
 import { collectSearchableSubjectFields } from "../crypto/subject-resolver";
 import type { DbRunner } from "../db/connection";
 import { resolveTableName } from "../db/entity-table-meta";
-import { executeRawQuery } from "../db/queries/raw-sql";
+import { executeRawQueryRead } from "../db/queries/raw-sql";
 import type { FeatureDefinition } from "../engine/types";
 import type { EntityDefinition } from "../engine/types/fields";
 import type { EntityId, TenantId } from "../engine/types/identifiers";
@@ -46,7 +47,7 @@ function ownershipPredicates(
           params.push(subject.userId);
           parts.push(`${quoteIdent(col)} = $${n}`);
         }
-      } else if ("pii" in field && field.pii === true && selfIdN === undefined) {
+      } else if (isSelfPiiField(field) && selfIdN === undefined) {
         selfIdN = nextParam();
         params.push(subject.userId);
         parts.push(`${quoteIdent("id")} = $${selfIdN}`);
@@ -78,7 +79,7 @@ async function collectMatchingRowsForEntity(
   let offset = 0;
   for (;;) {
     const offsetN = params.length + 1;
-    const page = await executeRawQuery<MatchedRow>(
+    const page = await executeRawQueryRead<MatchedRow>(
       db,
       `SELECT id, tenant_id FROM ${quoteIdent(tableName)} WHERE ${whereSql}
         ORDER BY ${quoteIdent("id")} ASC

package/src/search/reindex-entity.ts

@@ -7,7 +7,7 @@
 
 import type { DbRunner } from "../db/connection";
 import { resolveTableName } from "../db/entity-table-meta";
-import { executeRawQuery } from "../db/queries/raw-sql";
+import { executeRawQueryRead } from "../db/queries/raw-sql";
 import type { Registry, TenantId } from "../engine/types";
 import {
   buildSearchDocument,
@@ -112,7 +112,7 @@ export async function reindexEntity(
     // across both types needs a text cast that breaks integer ordering.
     // This is a one-time backfill over existing rows, not a live hot path;
     // switch to keyset if it ever needs to run against a churning table.
-    const rows = await executeRawQuery<Record<string, unknown>>(
+    const rows = await executeRawQueryRead<Record<string, unknown>>(
       db,
       `SELECT * FROM ${quoteIdent(tableName)}
         WHERE ${quoteIdent("tenant_id")} = $1 ${deletedFilter}

package/src/stack/__tests__/request-helper.integration.test.ts

@@ -10,7 +10,7 @@ import { NotFoundError, UnprocessableError, writeFailure } from "../../errors";
 import { setupTestStack, type TestStack } from "../test-stack";
 import { TestUsers } from "../test-users";
 
-let stack: TestStack;
+let stack: TestStack | undefined;
 
 const pingFeature = defineFeature("reqhelp", (r) => {
   r.writeHandler(
@@ -49,12 +49,12 @@ beforeAll(async () => {
 });
 
 afterAll(async () => {
-  await stack.cleanup();
+  await stack?.cleanup();
 });
 
 describe("createRequestHelper via setupTestStack.http", () => {
   test("writeOk posts to /api/write and returns handler data", async () => {
-    const data = await stack.http.writeOk<{ note: string; userId: string }>(
+    const data = await stack!.http.writeOk<{ note: string; userId: string }>(
       "reqhelp:write:echo",
       { note: "hello" },
       TestUsers.admin,
@@ -63,7 +63,7 @@ describe("createRequestHelper via setupTestStack.http", () => {
   });
 
   test("queryOk posts to /api/query and returns handler data", async () => {
-    const data = await stack.http.queryOk<{ id: string; ok: boolean }>(
+    const data = await stack!.http.queryOk<{ id: string; ok: boolean }>(
       "reqhelp:query:lookup",
       { id: "abc" },
       TestUsers.admin,
@@ -72,14 +72,14 @@ describe("createRequestHelper via setupTestStack.http", () => {
   });
 
   test("writeErr returns structured WriteErrorInfo with httpStatus", async () => {
-    const err = await stack.http.writeErr("reqhelp:write:boom", {}, TestUsers.admin);
+    const err = await stack!.http.writeErr("reqhelp:write:boom", {}, TestUsers.admin);
     expect(err.code).toBe("unprocessable");
-    expect(err.httpStatus).toBeGreaterThanOrEqual(400);
+    expect(err.httpStatus).toBe(422);
     expect(err.i18nKey).toBe("errors.unprocessable");
   });
 
   test("queryErr returns structured WriteErrorInfo for not-found", async () => {
-    const err = await stack.http.queryErr(
+    const err = await stack!.http.queryErr(
       "reqhelp:query:lookup",
       { id: "missing" },
       TestUsers.admin,
@@ -89,13 +89,13 @@ describe("createRequestHelper via setupTestStack.http", () => {
   });
 
   test("writeOk throws when the write fails (so suites cannot ignore failures)", async () => {
-    await expect(stack.http.writeOk("reqhelp:write:boom", {}, TestUsers.admin)).rejects.toThrow(
+    await expect(stack!.http.writeOk("reqhelp:write:boom", {}, TestUsers.admin)).rejects.toThrow(
       /reqhelp:write:boom/,
     );
   });
 
   test("batch posts commands and returns per-command results", async () => {
-    const res = await stack.http.batch(
+    const res = await stack!.http.batch(
       [
         { type: "reqhelp:write:echo", payload: { note: "a" } },
         { type: "reqhelp:write:echo", payload: { note: "b" } },
@@ -112,7 +112,7 @@ describe("createRequestHelper via setupTestStack.http", () => {
   });
 
   test("writeWithHeaders forwards extra headers alongside auth", async () => {
-    const res = await stack.http.writeWithHeaders(
+    const res = await stack!.http.writeWithHeaders(
       "reqhelp:write:echo",
       { note: "hdr" },
       TestUsers.admin,
@@ -122,5 +122,19 @@ describe("createRequestHelper via setupTestStack.http", () => {
     const body = (await res.json()) as { isSuccess?: boolean; data?: { note?: string } };
     expect(body.isSuccess).toBe(true);
     expect(body.data?.note).toBe("hdr");
+    expect(res.headers.get("X-Correlation-ID")).toBe("corr-42");
+  });
+
+  test("queryWithHeaders forwards extra headers alongside auth", async () => {
+    const res = await stack!.http.queryWithHeaders(
+      "reqhelp:query:lookup",
+      { id: "abc" },
+      TestUsers.admin,
+      { "X-Correlation-ID": "corr-query" },
+    );
+    expect(res.ok).toBe(true);
+    expect(res.headers.get("X-Correlation-ID")).toBe("corr-query");
+    const body = (await res.json()) as { data?: { id?: string; ok?: boolean } };
+    expect(body.data).toEqual({ id: "abc", ok: true });
   });
 });

package/src/ui-types/index.ts

@@ -77,6 +77,7 @@ export type {
   EntityEditScreenDefinition,
   EntityListScreenDefinition,
   FieldCondition,
+  FieldIconKey,
   FieldRenderer,
   FormWidth,
   ListColumnSpec,

package/src/upgrade-cli.ts

@@ -4,6 +4,7 @@ import {
   readdirSync,
   readFileSync,
   realpathSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import { isAbsolute, join, relative, resolve } from "node:path";
@@ -170,7 +171,23 @@ export function findFeaturesDirs(cwd: string): string[] {
 // node_modules after a plain npm/bun install (fw#2301).
 export function findCodemodScriptsRoot(repoRoot: string): string | null {
   const local = join(repoRoot, "packages/framework/src");
-  if (existsSync(join(local, CODEMOD_SUBDIR))) return local;
+  if (existsSync(join(local, CODEMOD_SUBDIR))) {
+    // If package.json exists, require it to be kumiko-framework so a generic
+    // monorepo `packages/framework` cannot shadow the installed package.
+    // Missing package.json (test fixtures / incomplete trees) keeps prior behavior.
+    const pkgPath = join(repoRoot, "packages/framework/package.json");
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as { name?: string };
+        if (pkg.name === "@cosmicdrift/kumiko-framework") return local;
+        // wrong name → fall through
+      } catch {
+        // unreadable → fall through
+      }
+    } else {
+      return local;
+    }
+  }
 
   let dir = repoRoot;
   for (let i = 0; i < 10; i++) {
@@ -187,7 +204,10 @@ export function findCodemodScriptsRoot(repoRoot: string): string | null {
 // Resolves a changes.json `codemod` field to an absolute script path,
 // refusing anything that would escape scripts/codemod/ (path traversal,
 // absolute paths, symlinks pointing outward) or that isn't a real .ts file.
-export function resolveCodemodScript(
+// First arg is the consumer repo root (same as findCodemodScriptsRoot) —
+// not the scripts root — so out-of-tree callers keep compiling against the
+// public upgrade-cli subpath without silently resolving to null (fw#2341).
+function resolveCodemodScriptAt(
   codemodScriptsRoot: string,
   codemodField: string | undefined,
 ): string | null {
@@ -213,6 +233,15 @@ export function resolveCodemodScript(
   return resolved;
 }
 
+export function resolveCodemodScript(
+  repoRoot: string,
+  codemodField: string | undefined,
+): string | null {
+  const scriptsRoot = findCodemodScriptsRoot(repoRoot);
+  if (!scriptsRoot) return null;
+  return resolveCodemodScriptAt(scriptsRoot, codemodField);
+}
+
 type CodemodRunResult = { readonly ok: boolean; readonly output: string };
 
 // Array-form argv only — never a shell string. The script itself decides
@@ -254,6 +283,42 @@ function writeUpgradeMarker(targetDir: string, marker: UpgradeMarker): void {
   writeFileSync(join(dir, "upgrade-state.json"), `${JSON.stringify(marker, null, 2)}\n`, "utf-8");
 }
 
+/** Highest pending version strictly below the earliest open manual breaking
+ *  entry (no codemod). Falls back to highest non-breaking pending when every
+ *  pending version is at/after that manual — never advances onto the manual. */
+/** Highest pending version strictly below the earliest open manual breaking
+ *  entry (no codemod). Falls back to highest non-breaking pending when every
+ *  pending version is at/after that manual. If only manuals remain, returns
+ *  `fallbackInstalled` so the marker stamp moves without claiming manuals done. */
+function markerVersionForPending(
+  pending: readonly ChangelogEntry[],
+  manualEntries: readonly ChangelogEntry[],
+  fallbackInstalled: string,
+): string {
+  const earliestManual = [...manualEntries].sort((a, b) =>
+    compareVersions(a.version, b.version),
+  )[0];
+  const eligible = pending.filter(
+    (e) => earliestManual === undefined || compareVersions(e.version, earliestManual.version) < 0,
+  );
+  const headEligible = eligible[0];
+  if (headEligible !== undefined) {
+    return eligible.reduce(
+      (max, e) => (compareVersions(e.version, max) > 0 ? e.version : max),
+      headEligible.version,
+    );
+  }
+  const nonBreaking = pending.filter((e) => e.type !== "breaking");
+  const headNonBreaking = nonBreaking[0];
+  if (headNonBreaking !== undefined) {
+    return nonBreaking.reduce(
+      (max, e) => (compareVersions(e.version, max) > 0 ? e.version : max),
+      headNonBreaking.version,
+    );
+  }
+  return fallbackInstalled;
+}
+
 // Runs every pending breaking entry's codemod, oldest version first (so a
 // later codemod can assume an earlier one already ran). Stops on the first
 // failure — no partial marker. Writes the marker whenever dryRun is false —
@@ -265,13 +330,16 @@ async function applyCodemods(
   repoRoot: string,
   targetDir: string,
   dryRun: boolean,
-  currentVersion: string,
+  // Installed version for the zero-pending bootstrap marker — never a
+  // `--from` filter override (that would permanently skip real pending
+  // codemods once the CI guard compares against the fake marker).
+  markerVersion: string,
 ): Promise<number> {
   if (pending.length === 0) {
     out.log("  ✓ Nothing new since your version.");
     if (!dryRun) {
       writeUpgradeMarker(targetDir, {
-        version: currentVersion,
+        version: markerVersion,
         appliedAt: Temporal.Now.instant().toString(),
         codemods: [],
       });
@@ -296,15 +364,28 @@ async function applyCodemods(
         ? "  No automatable codemods among the pending breaking changes."
         : "  ✓ No breaking changes pending.",
     );
+    if (!dryRun) {
+      const markerVer = markerVersionForPending(pending, manualEntries, markerVersion);
+      writeUpgradeMarker(targetDir, {
+        version: markerVer,
+        appliedAt: Temporal.Now.instant().toString(),
+        codemods: [],
+      });
+      out.log(`  ✓ Applied 0 codemod(s). Wrote ${join(targetDir, ".kumiko/upgrade-state.json")}`);
+    }
     return 0;
   }
 
   const codemodScriptsRoot = findCodemodScriptsRoot(repoRoot);
+  if (codemodScriptsRoot === null) {
+    out.err(
+      `  ✗ could not locate @cosmicdrift/kumiko-framework/src/scripts/codemod — is the framework installed? searched from ${repoRoot} upward`,
+    );
+    return 1;
+  }
   const ran: UpgradeMarkerCodemod[] = [];
   for (const e of codemodEntries) {
-    const scriptPath = codemodScriptsRoot
-      ? resolveCodemodScript(codemodScriptsRoot, e.codemod)
-      : null;
+    const scriptPath = resolveCodemodScript(repoRoot, e.codemod);
     if (!scriptPath) {
       out.err(`  ✗ ${e.version} · ${e.title} — invalid codemod path "${e.codemod}"`);
       return 1;
@@ -325,12 +406,7 @@ async function applyCodemods(
     return 0;
   }
 
-  const firstPending = pending[0];
-  if (!firstPending) return 0;
-  const latestVersion = pending.reduce(
-    (max, e) => (compareVersions(e.version, max) > 0 ? e.version : max),
-    firstPending.version,
-  );
+  const latestVersion = markerVersionForPending(pending, manualEntries, markerVersion);
   writeUpgradeMarker(targetDir, {
     version: latestVersion,
     appliedAt: Temporal.Now.instant().toString(),
@@ -398,9 +474,19 @@ export async function runUpgradeCli(
   if (getFlag(args, "apply")) {
     const dirFlag = getStringFlag(args, "dir");
     const targetDir = dirFlag ? resolve(dirFlag) : cwd;
+    if (!existsSync(targetDir) || !statSync(targetDir).isDirectory()) {
+      out.err("");
+      out.err(`  --dir path is not a directory: ${targetDir}`);
+      out.err("");
+      return 1;
+    }
+    // Marker must reflect what is actually installed under the target (or
+    // cwd), not a `--from` filter override — otherwise CI stays green forever.
+    const markerVersion =
+      (dirFlag ? readCurrentVersion(targetDir) : null) ?? installedVersion ?? currentVersion;
     const dryRun = getFlag(args, "dry-run");
     out.log("");
-    const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, currentVersion);
+    const code = await applyCodemods(out, pending, repoRoot, targetDir, dryRun, markerVersion);
     out.log("");
     return code;
   }