@hasna/todos 0.15.52 → 0.16.0

package/dist/task-subtree-transfer.js

@@ -46,7 +46,7 @@ function isBlockingDependencyStatus(status) {
 function isTerminalStatus(status) {
   return status === "completed" || status === "failed" || status === "cancelled";
 }
-var TASK_STATUSES, TASK_PRIORITIES, PLAN_STATUSES, VersionConflictError, TaskNotFoundError, TaskNotStartableError, TaskReferenceAmbiguousError, ProjectNotFoundError, ResourceConflictError, PlanRevisionConflictError, PlanNotFoundError, LockError, StaleLockHandoffError, AgentNotFoundError, IdentityAliasAmbiguousError, IdentityIdImmutableError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError, DISPATCH_STATUSES, DispatchNotFoundError;
+var TASK_STATUSES, TASK_PRIORITIES, PLAN_STATUSES, VersionConflictError, TaskNotFoundError, TaskNotStartableError, TaskReferenceAmbiguousError, ProjectNotFoundError, ResourceConflictError, PlanRevisionConflictError, PlanNotFoundError, LockError, StaleLockHandoffError, AgentNotFoundError, IdentityAliasAmbiguousError, IdentityIdImmutableError, TaskListNotFoundError, DependencyCycleError, CompletionGuardError, DISPATCH_STATUSES, DispatchNotFoundError, InputValidationError;
 var init_types = __esm(() => {
   TASK_STATUSES = [
     "pending",
@@ -61,7 +61,7 @@ var init_types = __esm(() => {
     "high",
     "critical"
   ];
-  PLAN_STATUSES = ["active", "completed", "archived"];
+  PLAN_STATUSES = ["active", "completed", "archived", "planning", "cancelled"];
   VersionConflictError = class VersionConflictError extends Error {
     taskId;
     expectedVersion;
@@ -250,6 +250,16 @@ var init_types = __esm(() => {
       this.name = "DispatchNotFoundError";
     }
   };
+  InputValidationError = class InputValidationError extends Error {
+    static code = "INVALID_INPUT";
+    code = InputValidationError.code;
+    suggestion;
+    constructor(message, suggestion) {
+      super(message);
+      this.name = "InputValidationError";
+      this.suggestion = suggestion;
+    }
+  };
 });
 
 // src/lib/slugs.ts
@@ -378,6 +388,171 @@ function deriveTodosTaskSubtreeTransferIdempotencyKey(input) {
   }).slice(0, 48)}`;
 }
 
+// src/storage/machine-registry.ts
+import { randomUUID } from "crypto";
+import { isDeepStrictEqual } from "util";
+class MachineRegistryError extends Error {
+  status;
+  constructor(message, status = 409) {
+    super(message);
+    this.status = status;
+  }
+}
+var fields = new Set(["id", "name", "hostname", "platform", "last_seen_at", "metadata", "created_at", "ssh_address", "is_primary", "archived_at"]);
+function validateMachines(value) {
+  if (!Array.isArray(value) || value.length > 1e4)
+    throw new MachineRegistryError("machines must be an array of at most 10000 complete records", 400);
+  for (const row of value) {
+    if (!row || typeof row !== "object" || Array.isArray(row) || Object.keys(row).some((key) => !fields.has(key)))
+      throw new MachineRegistryError("Invalid machine record fields", 400);
+    for (const key of ["id", "name", "last_seen_at", "created_at"])
+      if (typeof row[key] !== "string" || !row[key].trim() || row[key].length > 1024)
+        throw new MachineRegistryError(`Invalid machine ${key}`, 400);
+    for (const key of ["hostname", "platform", "ssh_address", "archived_at"])
+      if (row[key] !== null && typeof row[key] !== "string")
+        throw new MachineRegistryError(`Invalid machine ${key}`, 400);
+    for (const key of ["last_seen_at", "created_at", "archived_at"])
+      if (row[key] !== null && !Number.isFinite(Date.parse(row[key])))
+        throw new MachineRegistryError(`Invalid machine ${key}`, 400);
+    if (typeof row.is_primary !== "boolean" || !row.metadata || typeof row.metadata !== "object" || Array.isArray(row.metadata))
+      throw new MachineRegistryError("Invalid machine flags or metadata", 400);
+    if (!isDeepStrictEqual(JSON.parse(JSON.stringify(row.metadata)), row.metadata))
+      throw new MachineRegistryError("Machine metadata must preserve JSON values exactly", 400);
+    if (JSON.stringify(row.metadata).length > 262144)
+      throw new MachineRegistryError("Machine metadata is too large", 400);
+    if (row.is_primary && row.archived_at !== null)
+      throw new MachineRegistryError("An archived machine cannot be primary", 400);
+  }
+  return value;
+}
+function planMachineImport(existing, incoming) {
+  const rows = validateMachines(incoming);
+  const byId = new Map(existing.map((row) => [row.id, row]));
+  const byName = new Map(existing.map((row) => [row.name, row.id]));
+  const insert = [];
+  let skipped = 0;
+  for (const row of rows) {
+    const prior = byId.get(row.id);
+    if (prior && !isDeepStrictEqual(prior, row))
+      throw new MachineRegistryError("Machine migration conflicts with an existing identity; reconcile before retrying");
+    if (byName.has(row.name) && byName.get(row.name) !== row.id)
+      throw new MachineRegistryError("Machine name belongs to a different identity; migration was not applied");
+    if (prior)
+      skipped++;
+    else {
+      insert.push(row);
+      byId.set(row.id, row);
+      byName.set(row.name, row.id);
+    }
+  }
+  if ([...byId.values()].filter((row) => row.is_primary).length > 1)
+    throw new MachineRegistryError("Machine migration would create multiple primary machines");
+  return { rows: insert, skipped };
+}
+function createPostgresMachineRegistry(client, service, table, ensure) {
+  if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(table))
+    throw new Error("Invalid machine registry table");
+  async function list(connection = client) {
+    await ensure();
+    const result = await connection.query(`SELECT payload FROM ${table} WHERE service=$1 AND object_type='machines' AND deleted_at IS NULL ORDER BY object_id`, [service]);
+    return validateMachines(result.rows.map((row) => typeof row.payload === "string" ? JSON.parse(row.payload) : row.payload));
+  }
+  return { list, async execute(input) {
+    if (!input || typeof input !== "object" || Array.isArray(input) || !["register", "heartbeat", "set-primary", "archive", "unarchive", "delete", "import"].includes(input.action))
+      throw new MachineRegistryError("Invalid machine operation", 400);
+    if (Object.keys(input).some((key) => !["action", "name", "id", "options", "machines"].includes(key)))
+      throw new MachineRegistryError("Unknown machine operation fields", 400);
+    if (input.options !== undefined && (!input.options || typeof input.options !== "object" || Array.isArray(input.options)))
+      throw new MachineRegistryError("Invalid machine options", 400);
+    await ensure();
+    if (!client.transaction)
+      throw new MachineRegistryError("Machine registry requires a transactional server backend", 501);
+    return client.transaction(async (tx) => {
+      await tx.query("SELECT pg_advisory_xact_lock(hashtextextended($1, 0))", [`${service}:machine-registry`]);
+      const current = await list(tx);
+      let changed = [];
+      let skipped = 0;
+      let machine;
+      let deleted;
+      const stamp = new Date().toISOString();
+      if (input.action === "import") {
+        const plan = planMachineImport(current, input.machines);
+        const ids = plan.rows.map((row) => row.id);
+        if (ids.length) {
+          const retired = await tx.query(`SELECT object_id FROM ${table} WHERE service=$1 AND object_type='machines' AND object_id IN (SELECT jsonb_array_elements_text($2::text::jsonb)) AND deleted_at IS NOT NULL`, [service, JSON.stringify(ids)]);
+          if (retired.rows.length)
+            throw new MachineRegistryError("Machine migration contains a retired identity");
+        }
+        changed = plan.rows;
+        skipped = plan.skipped;
+      } else {
+        if (typeof input.name !== "string" || !input.name.trim() || input.name.length > 1024)
+          throw new MachineRegistryError("Machine name or ID is required", 400);
+        const matches = current.filter((row) => row.name === input.name || row.id === input.name);
+        if (matches.length > 1)
+          throw new MachineRegistryError("Machine selector is ambiguous between a name and another identity; use an unambiguous selector");
+        const prior = matches[0];
+        if (input.action === "register" || input.action === "heartbeat") {
+          const opts = input.options ?? {};
+          const allowed = new Set(["hostname", "platform", "ssh_address", "primary", "tailscale_name", "tailscale_ip", "lan_address", "workspace_path", "git_root", "arch"]);
+          for (const [key, value] of Object.entries(opts)) {
+            if (!allowed.has(key) || (key === "primary" ? typeof value !== "boolean" : typeof value !== "string" || value.length > 4096))
+              throw new MachineRegistryError("Invalid machine registration options", 400);
+          }
+          if (input.id !== undefined && (typeof input.id !== "string" || !input.id.trim() || input.id.length > 1024))
+            throw new MachineRegistryError("Invalid stable machine ID", 400);
+          if (prior && input.id && input.id !== prior.id)
+            throw new MachineRegistryError("Machine registration ID does not match existing identity");
+          if (!prior && input.id && current.some((row) => row.id === input.id))
+            throw new MachineRegistryError("Machine ID already belongs to another name");
+          const metadata = { ...prior?.metadata };
+          for (const key of ["tailscale_name", "tailscale_ip", "lan_address", "workspace_path", "git_root", "arch"])
+            if (opts[key] !== undefined)
+              metadata[key] = opts[key];
+          if (!prior && input.id) {
+            const retired = await tx.query(`SELECT object_id FROM ${table} WHERE service=$1 AND object_type='machines' AND object_id=$2 AND deleted_at IS NOT NULL`, [service, input.id]);
+            if (retired.rows.length)
+              throw new MachineRegistryError("Machine identity has been retired");
+          }
+          machine = { id: prior?.id ?? input.id ?? randomUUID(), name: prior?.name ?? input.name, hostname: opts.hostname ?? prior?.hostname ?? null, platform: opts.platform ?? prior?.platform ?? null, ssh_address: opts.ssh_address ?? prior?.ssh_address ?? null, created_at: prior?.created_at ?? stamp, last_seen_at: stamp, archived_at: prior?.archived_at ?? null, is_primary: opts.primary === true || (prior?.is_primary ?? false), metadata };
+          if (machine.archived_at && machine.is_primary)
+            throw new MachineRegistryError("Cannot set archived machine as primary");
+          changed = [machine];
+          if (opts.primary === true)
+            changed.push(...current.filter((row) => row.is_primary && row.id !== machine.id).map((row) => ({ ...row, is_primary: false })));
+        } else {
+          if (!prior)
+            throw new MachineRegistryError("Machine not found", 404);
+          machine = { ...prior };
+          if (input.action === "set-primary") {
+            if (prior.archived_at)
+              throw new MachineRegistryError("Cannot set archived machine as primary");
+            machine.is_primary = true;
+            changed = current.filter((row) => row.is_primary && row.id !== prior.id).map((row) => ({ ...row, is_primary: false }));
+          } else if (input.action === "archive" || input.action === "delete") {
+            if (prior.is_primary)
+              throw new MachineRegistryError("Cannot archive or delete the primary machine");
+            const refs = await tx.query(`SELECT object_id FROM ${table} WHERE service=$1 AND object_type<>'machines' AND deleted_at IS NULL AND payload->>'machine_id'=$2 AND ($3='delete' OR (object_type='tasks' AND payload->>'status' IN ('pending','in_progress'))) LIMIT 1`, [service, prior.id, input.action]);
+            if (refs.rows.length)
+              throw new MachineRegistryError("Machine still has referenced records or active tasks");
+            machine.archived_at = stamp;
+            deleted = input.action === "delete" ? true : undefined;
+          } else if (input.action === "unarchive")
+            machine.archived_at = null;
+          else
+            throw new MachineRegistryError("Unknown machine action", 400);
+          changed.push(machine);
+        }
+      }
+      for (const row of changed) {
+        await tx.query(`INSERT INTO ${table} (service,object_type,object_id,payload,updated_at,deleted_at,version) VALUES ($1,'machines',$2,$3::text::jsonb,$4,$5,1) ON CONFLICT (service,object_type,object_id) DO UPDATE SET payload=EXCLUDED.payload,updated_at=EXCLUDED.updated_at,deleted_at=EXCLUDED.deleted_at,version=COALESCE(${table}.version,0)+1`, [service, row.id, JSON.stringify(row), stamp, deleted && row.id === machine?.id ? stamp : null]);
+      }
+      const machines = await list(tx);
+      return { schema_version: 2, machines, ...machine ? { machine } : {}, inserted: changed.filter((row) => !current.some((old) => old.id === row.id)).length, skipped, ...deleted ? { deleted } : {} };
+    });
+  } };
+}
+
 // src/storage/postgres-sync.ts
 init_types();
 
@@ -600,6 +775,10 @@ class PostgresTodosSyncStore {
     }
   }
   async pushSnapshot(snapshot, context = {}) {
+    if ((snapshot.tombstones ?? []).some((row) => row.object_type === "machines"))
+      throw new Error("Machine tombstones require explicit registry lifecycle operations");
+    if (snapshot.machines !== undefined)
+      validateMachines(snapshot.machines);
     const routingErrors = validateSnapshotRoutingRecords(snapshot.projects, snapshot.taskLists);
     if (routingErrors.length > 0) {
       throw new Error(`Invalid snapshot routing metadata: ${routingErrors.join("; ")}`);
@@ -622,6 +801,14 @@ class PostgresTodosSyncStore {
         throw new ResourceConflictError("SNAPSHOT_DESTINATION_CONFLICT", `Snapshot routing conflicts with destination: ${destinationErrors.join("; ")}`);
       }
       const result = { records: 0, objectTypes: {} };
+      if (snapshot.machines?.length) {
+        if (!this.client.transaction)
+          throw new Error("Machine snapshot migration requires transaction(callback)");
+        const registry = createPostgresMachineRegistry({ query: client.query.bind(client), transaction: (fn) => fn(client) }, this.service, this.tableName, async () => {});
+        const receipt = await registry.execute({ action: "import", machines: snapshot.machines });
+        result.records += receipt.inserted + receipt.skipped;
+        result.objectTypes.machines = receipt.inserted + receipt.skipped;
+      }
       const sourceMachineId = context.requestId ?? this.sourceMachineId ?? null;
       for (const entry of snapshotEntries(snapshot)) {
         if (entry.deletedAt === null)
@@ -785,6 +972,7 @@ function rowsToSnapshot(rows) {
     tasks: [],
     projects: [],
     projectMachinePaths: [],
+    machines: [],
     plans: [],
     agents: [],
     taskLists: [],
@@ -796,6 +984,12 @@ function rowsToSnapshot(rows) {
   for (const row of rows) {
     const payload = payloadRecord(row.payload);
     const deletedAt = stringValue(row.deleted_at);
+    if (row.object_type === "machines") {
+      if (deletedAt)
+        throw new Error("Snapshot contains retired machine identities; use the authoritative registry instead of silently discarding tombstones");
+      snapshot.machines.push(payload);
+      continue;
+    }
     if (deletedAt) {
       snapshot.tombstones ??= [];
       snapshot.tombstones.push({
@@ -1758,12 +1952,12 @@ function nullableUuid(value, field) {
     return null;
   return uuid(value, field);
 }
-function strictObject(input, fields) {
+function strictObject(input, fields2) {
   if (input === null || typeof input !== "object" || Array.isArray(input)) {
     throw new TodosTaskSubtreeTransferError("TODOS_TASK_SUBTREE_TRANSFER_INVALID_INPUT", "Request must be a JSON object");
   }
   const object = input;
-  const allowed = new Set(fields);
+  const allowed = new Set(fields2);
   for (const key of Object.keys(object)) {
     if (!allowed.has(key)) {
       throw new TodosTaskSubtreeTransferError("TODOS_TASK_SUBTREE_TRANSFER_INVALID_INPUT", `Unknown field: ${key}`);

package/dist/testing.d.ts

@@ -3,9 +3,11 @@
  *
  * ## Why this is a shipped export and not a private fixture
  *
- * Every machine on the fleet exports `HASNA_TODOS_API_URL` and `HASNA_TODOS_API_KEY`,
- * so any test that spawns the CLI with `{ ...process.env }`, or loads the SDK in-process,
- * writes into the **shared hosted store**. That is not hypothetical:
+ * Every machine on the fleet can resolve a Todos credential — from `HASNA_TODOS_API_KEY`,
+ * from the macOS Keychain item `hasna.credentials.todos.api-key`, or from
+ * `~/.hasna/todos/config/credentials` — so any test that spawns the CLI with
+ * `{ ...process.env }`, or loads the SDK in-process, writes into the **shared hosted
+ * store**. That is not hypothetical:
  *
  * - a consumer test suite leaked **1,151** rows (`seed-task-<epoch>`,
  *   `Short ID resolution test`, …) between 2026-04-06 and 2026-06-21.
@@ -32,23 +34,56 @@
  * const restore = applyLocalTodosTestEnv({ HASNA_TODOS_DB_PATH: tmpDb });
  * ```
  */
+/**
+ * The single disk credential tier the @hasna/contracts chain reads, relative to
+ * HOME: `~/.hasna/todos/config/credentials`. Exported so a consumer's fixture
+ * can name the exact file rather than rebuilding the path from a doc comment.
+ */
+export declare const TODOS_CREDENTIALS_FILE_SEGMENTS: readonly [".hasna", "todos", "config", "credentials"];
 /**
  * Every environment variable that can point this client at a store shared with other
- * people. Blanking all of them is what makes a test physically unable to reach the
- * hosted authority — `resolveTodosCliTransport` refuses `http` without a URL and key,
- * and there is no fallback path that reintroduces one.
+ * people.
+ *
+ * Blanking them is NO LONGER SUFFICIENT ON ITS OWN, and that is the whole reason the
+ * local opt-in below is defaulted on. Since the credential chain moved into
+ * @hasna/contracts (hasna/apps#1720) a key can also arrive from the machine's login
+ * Keychain or from `~/.hasna/todos/config/credentials`, neither of which an env
+ * dictionary can blank. What makes a test physically unable to reach the hosted
+ * authority is therefore the pair: these variables blanked, AND `HASNA_TODOS_LOCAL=1`,
+ * which `resolveTodosCliTransport` answers BEFORE it consults the resolver — so no
+ * Keychain item and no credential file is ever read.
  *
  * Keep this in sync with the resolver by adding to it, never by deleting from it:
  * `src/testing.test.ts` fails the build if the resolver reads a `*TODOS_*` routing
  * variable that is neither listed here nor named in `LOCAL_ONLY_TODOS_ENV_KEYS`.
  */
-export declare const SHARED_TODOS_STORE_ENV_KEYS: readonly ["HASNA_TODOS_API_URL", "HASNA_TODOS_API_KEY", "HASNA_TODOS_API_SIGNING_KEY", "TODOS_API_URL", "TODOS_API_KEY", "HASNA_TODOS_DATABASE_URL", "TODOS_DATABASE_URL", "DATABASE_URL", "TODOS_ALLOW_ANONYMOUS"];
+export declare const SHARED_TODOS_STORE_ENV_KEYS: readonly ["HASNA_TODOS_API_URL", "HASNA_TODOS_API_KEY", "HASNA_TODOS_API_SIGNING_KEY", "TODOS_API_URL", "TODOS_API_KEY", "HASNA_TODOS_SERVER_API_KEY", "HASNA_TODOS_API_KEY_OVERRIDE", "HASNA_TODOS_API_KEY_REF", "HASNA_PROFILE", "HASNA_TODOS_DATABASE_URL", "TODOS_DATABASE_URL", "DATABASE_URL", "TODOS_ALLOW_ANONYMOUS"];
 /**
  * Routing variables the resolver reads that select a store *kind* rather than a shared
  * destination. They are pinned rather than blanked, so they are exempt from the scrub
- * coverage assertion.
+ * coverage assertion. The local opt-in (`HASNA_TODOS_LOCAL=1`, alias `TODOS_LOCAL=1`)
+ * is the ONLY route to the on-box SQLite client mode since the 2026-09-04 fail-closed
+ * ruling (hasna/apps#1613); local-intent test envs default it on, remote-intent envs
+ * may override it back to "" to exercise the fail-closed arm.
+ */
+export declare const LOCAL_ONLY_TODOS_ENV_KEYS: readonly ["HASNA_TODOS_LOCAL", "TODOS_LOCAL", "HASNA_TODOS_DB_PATH", "TODOS_DB_PATH", "HASNA_STATION"];
+/**
+ * The Keychain account a test environment pins, chosen so that no item can
+ * exist under it.
+ *
+ * The macOS Keychain tier of the @hasna/contracts chain is AMBIENT: it runs for
+ * the live `process.env`, which every spawned CLI has. An env dictionary cannot
+ * blank a login-keychain item, so without this pin a developer's own
+ * `hasna.credentials.todos.api-key` — and the `api-url` item beside it — would
+ * be resolved by the package's own test suite: the fixture's throwaway
+ * authority would collide with the real one ("select different service
+ * authorities"), and worse, a fixture server would receive the operator's live
+ * fleet credential. `HASNA_STATION` decides the account the tier looks under,
+ * so pinning it to a name no item uses makes the tier reliably EMPTY (the
+ * `security` tool answers item-not-found, which is an absent tier rather than a
+ * failure) on a developer Mac and on CI alike.
  */
-export declare const LOCAL_ONLY_TODOS_ENV_KEYS: readonly ["HASNA_TODOS_DB_PATH", "TODOS_DB_PATH"];
+export declare const TODOS_TEST_KEYCHAIN_ACCOUNT = "todos-test-fixture-no-such-station";
 /**
  * The retired storage-mode variables. The resolver never reads them — they are
  * inert — but a test env DELETES them so a test can never depend on a stale
@@ -59,22 +94,28 @@ export declare const REMOVED_TODOS_ENV_KEYS: readonly ["HASNA_TODOS_STORAGE_MODE
 export type SharedTodosStoreEnvKey = (typeof SHARED_TODOS_STORE_ENV_KEYS)[number];
 export type TodosTestEnv = Record<string, string | undefined>;
 /**
- * Deliver an explicitly supplied API key through the primary DISK tier
- * (`$HOME/.hasna/fleet-env/todos.env`) instead of the legacy cloud tier, and
- * return the env unchanged. The contracts client treats `~/.hasna/cloud` as a
- * NOISY deprecated fallback and prints a DEPRECATED notice to stderr whenever
- * the key arrives from there; a CLI subprocess test that asserts empty (or
- * exact) stderr then fails even though authentication succeeded. fleet-env is
- * the primary tier (re-read per call) and is the path the deprecation notice
- * itself recommends.
+ * Deliver an explicitly supplied API key through the DISK tier — the one the
+ * @hasna/contracts chain actually reads, `$HOME/.hasna/todos/config/credentials`
+ * — and return the env unchanged.
+ *
+ * The retired locations are not written and are not inputs anywhere:
+ * `~/.hasna/fleet-env/`, `~/.hasna/cloud/` and `~/.config/hasna/` were removed
+ * from the resolver by the 2026-09-04 home-layout ruling, so a fixture that
+ * still wrote one of them would deliver a credential to a file nothing reads
+ * and fail as "no key" long after the write appeared to succeed.
+ *
+ * The file is created 0600 because the resolver REFUSES a credential file that
+ * is not owner-only 0400/0600 — a group- or world-readable file is treated as
+ * unsafe and throws rather than being read, so a laxer mode here would turn
+ * every fixture using it red.
  *
  * ## This function writes a real file, so it guards itself
  *
  * It THROWS when `env.HOME` resolves to this machine's own home directory,
  * because the write would replace the operator's configured todos credential
  * with a fixture value. That is not hypothetical: on 2026-08-21 a fixture whose
- * env inherited `process.env.HOME` destroyed `~/.hasna/cloud/todos.env` on
- * station01 and cost a seat nine hours without a task system.
+ * env inherited `process.env.HOME` destroyed station01's own todos credential
+ * file and cost a seat nine hours without a task system.
  *
  * The guard lives HERE, in the function, and not only in {@link localTodosTestEnv}.
  * This symbol is exported, so `deliverTodosApiKeyViaDisk(localTodosTestEnv({ ... }))`
@@ -84,25 +125,45 @@ export type TodosTestEnv = Record<string, string | undefined>;
  *
  * Comparison is by EXACT canonical equality with the machine home, never
  * "somewhere underneath it": the artefact at risk is precisely
- * `$HOME/.hasna/fleet-env/todos.env`, and an under-home rule would reject
+ * `$HOME/.hasna/todos/config/credentials`, and an under-home rule would reject
  * fixtures that legitimately create a scratch root inside the home tree.
  *
  * A missing HOME or a missing key stays a silent no-op — nothing is written, so
  * nothing is at risk. Only the machine-home case is loud, because there the
  * caller is about to lose data and needs to be told rather than left believing
  * the credential was delivered.
+ *
+ * ## It also pins the Keychain account, and that is not a side errand
+ *
+ * The Keychain tier sits ABOVE disk. On a developer Mac with a real
+ * `hasna.credentials.todos.api-key` item, delivering a fixture key to disk and
+ * then spawning the CLI resolves the OPERATOR'S LIVE KEY instead — the fixture
+ * server receives a production credential, and the run can even block on a
+ * keychain prompt. "Deliver this key through the disk tier" is therefore only
+ * true if the tier above it is empty, so this stamps `HASNA_STATION` with
+ * {@link TODOS_TEST_KEYCHAIN_ACCOUNT} unless the caller set it themselves.
  */
 export declare function deliverTodosApiKeyViaDisk(env: TodosTestEnv): TodosTestEnv;
 /**
- * `process.env` with every shared-store pointer blanked and the retired
- * storage-mode variables deleted, so the transport resolves to a local SQLite
- * file. Overrides are applied last, so a test that deliberately exercises the
- * hosted transport against a throwaway server can still opt back in explicitly.
- *
- * Blank string, not `delete`, for the shared-store pointers: a blanked URL/key
- * is treated as absent, and there is no partial-config fallback. The retired
- * `*_STORAGE_MODE` variables are DELETED, not blanked, so a test never
- * inherits a stale fragment from the host environment.
+ * `process.env` with every shared-store pointer blanked, the retired
+ * storage-mode variables deleted, and the explicit local opt-in
+ * (`HASNA_TODOS_LOCAL=1` / `TODOS_LOCAL=1`) DEFAULTED ON, so the transport
+ * resolves to the on-box SQLite file. Local SQLite is no longer a default —
+ * the resolver fails closed without the opt-in (hasna/apps#1613) — so a
+ * local-intent env must carry it; a test that deliberately exercises the
+ * hosted transport against a throwaway server, or the fail-closed arm, can
+ * override it (opt-in `""`, or the API pair) because overrides are applied
+ * last.
+ *
+ * DELETED, never blanked. Blanking used to be the spelling for "absent", but a
+ * declared-but-blank authority variable is only inert where the caller
+ * normalises it: the Todos seam removes it before its resolver runs
+ * (src/lib/local-opt-in.ts), so it configures no credential and refuses
+ * nothing there, while a consumer that hands this dictionary straight to
+ * @hasna/contracts gets the resolver's loud "set but blank" refusal. Deleting
+ * is the one spelling that means "absent" on every path. A blank a caller
+ * passes in `overrides` (`{ HASNA_TODOS_API_URL: "" }`) is normalised to an
+ * absent key for the same reason.
  */
 export declare function localTodosTestEnv(overrides?: TodosTestEnv): TodosTestEnv;
 /**

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAMH;;;;;;;;;GASG;AACH,eAAO,MAAM,2BAA2B,qNAa9B,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,mDAG5B,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,+FAKzB,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAElF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAqC9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAmBzE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,GAAE,YAAiB,GAAG,YAAY,CAc5E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,GAAE,YAAiB,GAAG,MAAM,IAAI,CAoB/E;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,YAA0C,GAAG,IAAI,CAQ7F"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAMH;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,uDAAwD,CAAC;AAErG;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,2BAA2B,+TA0B9B,CAAC;AAEX;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,wGAU5B,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,2BAA2B,uCAAuC,CAAC;AAShF;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,+FAKzB,CAAC;AAEX,MAAM,MAAM,sBAAsB,GAAG,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAElF,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAqC9D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CA0BzE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,GAAE,YAAiB,GAAG,YAAY,CAiB5E;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,GAAE,YAAiB,GAAG,MAAM,IAAI,CAqB/E;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,YAA0C,GAAG,IAAI,CAQ7F"}

package/dist/testing.js

@@ -40,24 +40,38 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
 // src/testing.ts
-import { mkdirSync, realpathSync, writeFileSync } from "fs";
+import { chmodSync, mkdirSync, realpathSync, writeFileSync } from "fs";
 import { homedir } from "os";
-import { join, resolve } from "path";
+import { dirname, join, resolve } from "path";
+var TODOS_CREDENTIALS_FILE_SEGMENTS = [".hasna", "todos", "config", "credentials"];
 var SHARED_TODOS_STORE_ENV_KEYS = [
   "HASNA_TODOS_API_URL",
   "HASNA_TODOS_API_KEY",
   "HASNA_TODOS_API_SIGNING_KEY",
   "TODOS_API_URL",
   "TODOS_API_KEY",
+  "HASNA_TODOS_SERVER_API_KEY",
+  "HASNA_TODOS_API_KEY_OVERRIDE",
+  "HASNA_TODOS_API_KEY_REF",
+  "HASNA_PROFILE",
   "HASNA_TODOS_DATABASE_URL",
   "TODOS_DATABASE_URL",
   "DATABASE_URL",
   "TODOS_ALLOW_ANONYMOUS"
 ];
 var LOCAL_ONLY_TODOS_ENV_KEYS = [
+  "HASNA_TODOS_LOCAL",
+  "TODOS_LOCAL",
   "HASNA_TODOS_DB_PATH",
-  "TODOS_DB_PATH"
+  "TODOS_DB_PATH",
+  "HASNA_STATION"
 ];
+var TODOS_TEST_KEYCHAIN_ACCOUNT = "todos-test-fixture-no-such-station";
+var LOCAL_OPT_IN_DEFAULT = {
+  HASNA_TODOS_LOCAL: "1",
+  TODOS_LOCAL: "1",
+  HASNA_STATION: TODOS_TEST_KEYCHAIN_ACCOUNT
+};
 var REMOVED_TODOS_ENV_KEYS = [
   "HASNA_TODOS_STORAGE_MODE",
   "HASNA_TODOS_MODE",
@@ -91,21 +105,28 @@ function deliverTodosApiKeyViaDisk(env) {
     return env;
   const target = canonicalisePath(home);
   if (machineHomeCandidates().includes(target)) {
-    throw new Error(`TODOS_FIXTURE_HOME_IS_MACHINE_HOME: refusing to write ${join(target, ".hasna", "fleet-env", "todos.env")} \u2014 ` + "HOME resolves to this machine's real home directory, so this write would replace the machine's " + "configured todos credential with a fixture value. Pass a throwaway home, e.g. " + 'HOME: mkdtempSync(join(tmpdir(), "todos-fixture-")).');
+    throw new Error(`TODOS_FIXTURE_HOME_IS_MACHINE_HOME: refusing to write ${join(target, ...TODOS_CREDENTIALS_FILE_SEGMENTS)} \u2014 ` + "HOME resolves to this machine's real home directory, so this write would replace the machine's " + "configured todos credential with a fixture value. Pass a throwaway home, e.g. " + 'HOME: mkdtempSync(join(tmpdir(), "todos-fixture-")).');
   }
-  const dir = join(home, ".hasna", "fleet-env");
-  mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, "todos.env"), `HASNA_TODOS_API_KEY=${apiKey}
-`);
+  if ((env.HASNA_STATION ?? "").trim() === "")
+    env.HASNA_STATION = TODOS_TEST_KEYCHAIN_ACCOUNT;
+  const file = join(home, ...TODOS_CREDENTIALS_FILE_SEGMENTS);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, `HASNA_TODOS_API_KEY=${apiKey}
+`, { mode: 384 });
+  chmodSync(file, 384);
   return env;
 }
 function localTodosTestEnv(overrides = {}) {
   const env = { ...process.env };
   for (const key of SHARED_TODOS_STORE_ENV_KEYS)
-    env[key] = "";
+    delete env[key];
   for (const key of REMOVED_TODOS_ENV_KEYS)
     delete env[key];
-  const result = { ...env, ...overrides };
+  const result = { ...env, ...LOCAL_OPT_IN_DEFAULT, ...overrides };
+  for (const key of SHARED_TODOS_STORE_ENV_KEYS) {
+    if ((result[key] ?? "").trim() === "")
+      delete result[key];
+  }
   if (overrides.HOME && result.HASNA_TODOS_API_KEY) {
     deliverTodosApiKeyViaDisk(result);
   }
@@ -115,6 +136,7 @@ function applyLocalTodosTestEnv(overrides = {}) {
   const next = localTodosTestEnv(overrides);
   const touched = [
     ...SHARED_TODOS_STORE_ENV_KEYS,
+    ...LOCAL_ONLY_TODOS_ENV_KEYS,
     ...REMOVED_TODOS_ENV_KEYS,
     ...Object.keys(overrides)
   ];
@@ -148,6 +170,8 @@ export {
   deliverTodosApiKeyViaDisk,
   assertLocalTodosTestEnv,
   applyLocalTodosTestEnv,
+  TODOS_TEST_KEYCHAIN_ACCOUNT,
+  TODOS_CREDENTIALS_FILE_SEGMENTS,
   SHARED_TODOS_STORE_ENV_KEYS,
   REMOVED_TODOS_ENV_KEYS,
   LOCAL_ONLY_TODOS_ENV_KEYS