@sentropic/h2a-runtime 0.91.1 → 0.93.0

package/dist/registry.js

@@ -18,7 +18,12 @@ import { uptime } from "node:os";
 import { dirname, join } from "node:path";
 import { getLayoutConfig, resolveConfigPath } from "./config.js";
 import { acquireFileLock, releaseFileLock } from "./file-lock.js";
-import { managedSessionCandidates, parseManagedSessionName, listLocalSessions, } from "./tmux.js";
+import { localSessionName, managedSessionCandidates, parseManagedSessionName, listLocalSessions, tmuxAvailable, } from "./tmux.js";
+import { nativeSessionLiveness } from "./native-host.js";
+/** Managed local interactive session hosted by tmux OR the native PTY host. */
+export function isManagedLocalKind(kind) {
+    return kind === "local-tmux" || kind === "local-native";
+}
 /** System boot time in ms epoch (now minus uptime). */
 function defaultBootTimeMs() {
     return Date.now() - uptime() * 1000;
@@ -38,19 +43,204 @@ const CONVERSATION_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[
 export function looksLikeConversationUuid(value) {
     return value !== undefined && CONVERSATION_UUID_RE.test(value);
 }
+function isRestorePinnedCandidate(entry) {
+    return (entry.kind === "local-tmux" &&
+        entry.source === "run" &&
+        entry.sessionClass === "human" &&
+        !entry.endedAt &&
+        looksLikeConversationUuid(entry.convId));
+}
+function shouldPreserveByRestorePin(entry) {
+    if (entry.restorePinned === false)
+        return false;
+    if (isRestorePinnedCandidate(entry))
+        return true;
+    // Invariant: restore pin never preserves positively non-human rows (no implicit pin by absence).
+    // As of 2026-08-08 this affects 0 lines — the 29 role=job rows with absent sessionClass are all kind=remote, already outside the perimeter by the kind/source gates; role==='job' is added by SYMMETRY with sessionClass==='background' so a positively non-human row is never pinned even when classless.
+    if (entry.endedAt || entry.sessionClass === "background" || entry.role === "job")
+        return false;
+    return (entry.kind === "local-tmux" &&
+        entry.source === "run" &&
+        // Invariant: "unknown protects" inside the local-tmux/run restore-pin perimeter.
+        // Restore-pin covers durable human local-tmux/run rows, while remote sessions
+        // are deliberately out of the restore-pin perimeter.
+        // As of 2026-08-08, the architect measured 29 sessionClass-absent lines; all were kind=remote, so this guard currently has no observed effect.
+        (entry.sessionClass === "human" || entry.sessionClass === undefined));
+}
+// Returns the 3-state RegistryReadResult above
+// ({state:"ok",entries,unreadable} | {state:"unknown",reason}), NOT a plain
+// array — a bare `.map()`/`.find()`/`.some()`/`.every()` on the return value
+// is a bug. tsc does NOT type-check `.js` files, so a signature change here
+// is invisible to JS callers (e.g. packages/h2a/test/*.js) even though every
+// `.ts` caller gets a compile error. Anyone widening/changing this return
+// type MUST grep repo-wide for BOTH extensions before trusting the compiler
+// to be exhaustive:
+//   git grep -nE 'loadRegistry\b' -- '**/*.js' '**/*.ts' | grep -v loadRegistryWithDiagnostics
 export function loadRegistry(path = resolveRegistryPath()) {
+    const raw = rawRegistryRead(path);
+    if (raw.state === "unknown")
+        return raw;
+    // B2 — WHOLE-FILE trace, same logic as the per-identity `unreadable` check
+    // applied to the WHOLE file: this file was REBUILT from a registry the
+    // write path could not read (rawRegistryEntriesForWrite moved the
+    // unreadable bytes aside to a sibling registry.corrupt-*.json and rebuilt
+    // from `[]`). Rows that lived in the corrupt bytes are NOT provably absent
+    // from THIS read — a destructive caller must never treat "missing here"
+    // as "no local session existed" while this trace is present. Every reader
+    // (not just this one) must see "unknown", so this is checked on the READ
+    // path (loadRegistry), never on rawRegistryRead itself — the write path
+    // (rawRegistryEntriesForWrite) deliberately ignores this field so a
+    // rebuilt-but-now-valid file keeps accepting new enrolments (REBUILDING is
+    // allowed); only the "was something silently lost?" READ verdict is
+    // poisoned, and only until the next successful write clears the trace.
+    if (raw.rebuiltFromCorruptAt !== undefined) {
+        return {
+            state: "unknown",
+            reason: `registry was rebuilt from an unreadable file at ${raw.rebuiltFromCorruptAt} ` +
+                `(see registry.corrupt-*.json next to the registry) — rows from before the ` +
+                `rebuild are not provably absent`,
+        };
+    }
+    const entries = [];
+    const unreadable = [];
+    for (const row of raw.rows) {
+        if (isRegistryEntry(row)) {
+            entries.push(row);
+        }
+        else if (row && typeof row === "object") {
+            // Counter-mutant guard (PART-A producer): a row that fails
+            // `isRegistryEntry` is TRANSPORTED, never dropped — dropping it here
+            // is exactly the per-row lie this type exists to remove.
+            unreadable.push(row);
+        }
+        // A non-object row (string/number/null/etc.) cannot address any target
+        // by identity (no id/label/tmuxSession to match against) — it is
+        // discarded rather than carried as a formless "unreadable" row.
+    }
+    return { state: "ok", entries, unreadable };
+}
+/** Raw `entries` array of the registry FILE, with the read state preserved. */
+function rawRegistryRead(path) {
+    let text;
     try {
-        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        text = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        // An ABSENT file is provable emptiness (rows cannot exist without a
+        // file); every other read failure (EACCES, EIO, …) is UNKNOWN.
+        if (error.code === "ENOENT") {
+            return { state: "ok", rows: [] };
+        }
+        return {
+            state: "unknown",
+            reason: `registry file is unreadable (${error.code ?? "read error"})`,
+        };
+    }
+    try {
+        const parsed = JSON.parse(text);
         const entries = parsed?.entries;
-        if (!Array.isArray(entries))
-            return [];
-        return entries.filter(isRegistryEntry);
+        if (!Array.isArray(entries)) {
+            return { state: "unknown", reason: "registry has no entries array" };
+        }
+        const rebuiltFromCorruptAt = parsed
+            ?.rebuiltFromCorruptAt;
+        return {
+            state: "ok",
+            rows: entries,
+            ...(typeof rebuiltFromCorruptAt === "string" ? { rebuiltFromCorruptAt } : {}),
+        };
     }
     catch {
-        // missing or corrupt file -> empty registry (it is rebuilt by enrolment)
-        return [];
+        return { state: "unknown", reason: "registry is corrupt (not valid JSON)" };
     }
 }
+/**
+ * Move the unreadable bytes at `path` aside VERBATIM to a sibling
+ * `registry.corrupt-<ts>-<pid>.json` (best-effort: a truly unreadable file,
+ * e.g. EACCES, has nothing left to move — the rebuild still proceeds and is
+ * still flagged by the caller). B2 — "REBUILDING is allowed. DESTROYING is
+ * not.": called by `withRegistryLock` ONLY immediately before a write that
+ * is actually about to REBUILD the file from `[]`, never on a mere read or a
+ * `save:false` no-op (e.g. `prune` finding nothing to change on a corrupt
+ * file) — otherwise a corrupt registry nothing ever mutates would spam a
+ * fresh sibling file on every poll (`remote ls` calls `prune` every time).
+ * Returns the rebuild timestamp to stamp on the save (the WHOLE-FILE trace
+ * `loadRegistry` turns into "unknown" for every destructive reader).
+ */
+function moveAsideUnreadableRegistry(path) {
+    const at = new Date().toISOString();
+    try {
+        const original = readFileSync(path, "utf8");
+        const corruptPath = join(dirname(path), `registry.corrupt-${at.replace(/[:.]/g, "-")}-${process.pid}.json`);
+        writeFileSync(corruptPath, original, "utf8");
+    }
+    catch {
+        // Nothing readable to move aside (EACCES/EIO/ENOENT/…) — the rebuild
+        // still proceeds and is still flagged so destructive readers stay
+        // fail-closed.
+    }
+    return at;
+}
+/**
+ * Pure identity match: does raw row `raw` (already known to have FAILED
+ * `isRegistryEntry`) plausibly address `target` under the SAME identity rules
+ * used to match a VALID row (id / label / exact tmuxSession / managed-name
+ * candidates)? Shared by `unreadableRowsForTarget` (A2's per-identity poison
+ * check inside `resolveManagedHost`) and the legacy path-based helper below.
+ * Defensive: an unreadable row is read WITHOUT presuming a well-formed shape.
+ */
+function rawRowMatchesTarget(target, raw) {
+    const requested = parseManagedSessionName(target);
+    const candidates = requested ? [target] : managedSessionCandidates(target);
+    const id = typeof raw.id === "string" ? raw.id : undefined;
+    const label = typeof raw.label === "string" ? raw.label : undefined;
+    const tmuxSession = typeof raw.tmuxSession === "string" ? raw.tmuxSession : undefined;
+    if (requested) {
+        return (tmuxSession === target ||
+            (tmuxSession === undefined && id === requested.slug));
+    }
+    return (id === target ||
+        label === target ||
+        (tmuxSession !== undefined && candidates.includes(tmuxSession)));
+}
+/**
+ * Unreadable rows (from an ALREADY-READ `loadRegistry()` snapshot) that
+ * plausibly address `target` under the resolver's identity rules. Pure — no
+ * fs — so every caller consults the SAME snapshot instead of re-reading the
+ * file (this is what `resolveManagedHost` calls for its per-identity poison
+ * check, A2). THE RULE: absence must be provable BY IDENTITY — an unknown by
+ * identity for X, never a global unknown that disables every OTHER identity.
+ */
+export function unreadableRowsForTarget(target, unreadable) {
+    return unreadable.filter((raw) => rawRowMatchesTarget(target, raw));
+}
+/**
+ * Path-based convenience wrapper: performs its OWN registry read (a second
+ * read when the caller already has one — prefer `unreadableRowsForTarget`
+ * with an existing `loadRegistry()` snapshot when one is available, e.g.
+ * inside `resolveManagedHost`). Raw rows in the registry FILE that FAIL
+ * validation (e.g. `kind` absent or unreadable) but plausibly address
+ * `target`. `loadRegistry()` cannot return them as `entries` — but a
+ * DESTRUCTIVE caller must know the identity exists in an unreadable state:
+ * such a row makes local host state UNKNOWN (fail closed, sol-2), never "no
+ * local session" — which would let the act fall through to a REMOTE homonym.
+ *
+ * B3 — this is itself a RE-READ on a destructive path (a TOCTOU window: the
+ * caller's own earlier read may have succeeded, then the registry became
+ * unreadable strictly BETWEEN the two reads — another writer, a partial
+ * write, disk pressure). A re-read inherits the SAME 3-state contract as the
+ * first: a whole-file "unknown" here used to flatten to `[]` — "no
+ * unreadable row for this identity" — which is indistinguishable from "the
+ * row is fine" and let the caller fall through past this guard. Returns
+ * `"unknown"` instead so the caller refuses exactly like any other unknown
+ * registry read, never silently re-simplified into an empty collection.
+ */
+export function unreadableRegistryRowsForTarget(target, path = resolveRegistryPath()) {
+    const read = loadRegistry(path);
+    if (read.state === "unknown")
+        return "unknown";
+    return unreadableRowsForTarget(target, read.unreadable);
+}
 /**
  * Read the registry without collapsing a missing/corrupt file into an empty
  * collection.  Operational commands may rebuild their registry; the status
@@ -77,13 +267,162 @@ export function loadRegistryWithDiagnostics(path = resolveRegistryPath()) {
         };
     }
 }
+// ---------------------------------------------------------------------------
+// Native-terminal PTY pgid persistence.
+//
+// Durable session identity (incl. pgid) lives in the single registry store BY
+// DESIGN — h2a keeps ONE durable local store (the owner's SQLite direction);
+// a separate native-terminal store would be exactly the heterogeneity being
+// eliminated. This is NOT a layer leak from native-terminal/host.ts into the
+// registry; do not remove this coupling. The pgid is stored on a real
+// `RegistryEntry` row (same file, same lock, same atomic write as every other
+// registry mutation) keyed by a namespaced id so it can never collide with a
+// real claude/codex/agy session row. `tool`/`source`/`cwd` on that row are
+// syntactically-required placeholders (RegistryTool/RegistrySource are closed
+// enums built around CLI sessions, not arbitrary PTY commands) — the only
+// consumer of this row is `readNativeTerminalPgid` below, which reads `.pgid`
+// and ignores the rest. `kind: "local"` keeps the row OUT of `remote ls`
+// (`localLsRows` only surfaces `kind: "local-tmux"`) and out of delegate's
+// concurrency accounting (`role` is left unset, so `tryClaimSlot`/`listJobs`
+// never see it).
+// ---------------------------------------------------------------------------
+const NATIVE_TERMINAL_PGID_ENTRY_ID_PREFIX = "native-terminal-pty:";
+function nativeTerminalPgidEntryId(sessionId) {
+    return `${NATIVE_TERMINAL_PGID_ENTRY_ID_PREFIX}${sessionId}`;
+}
+export function persistNativeTerminalPgid(sessionId, pgid, path = resolveRegistryPath(), owner, leaderStartTime, groupToken) {
+    if (!Number.isSafeInteger(pgid) || pgid <= 0) {
+        throw new RangeError("pgid must be a positive safe integer");
+    }
+    const id = nativeTerminalPgidEntryId(sessionId);
+    withRegistryLock(path, (entries) => {
+        const now = new Date().toISOString();
+        const idx = entries.findIndex((e) => e.id === id);
+        const entry = {
+            id,
+            tool: "claude",
+            kind: "local",
+            cwd: "",
+            source: "scan",
+            enrolledAt: idx >= 0 ? entries[idx].enrolledAt : now,
+            lastSeenAt: now,
+            pgid,
+            ...(leaderStartTime !== undefined ? { pgidLeaderStartTime: leaderStartTime } : {}),
+            ...(groupToken !== undefined ? { pgidGroupToken: groupToken } : {}),
+            ...(owner !== undefined ? { ownerHostPid: owner.pid } : {}),
+            ...(owner?.startTime !== undefined ? { ownerHostStartTime: owner.startTime } : {}),
+        };
+        const next = idx >= 0
+            ? entries.map((e, i) => (i === idx ? entry : e))
+            : [...entries, entry];
+        return { entries: next, result: undefined };
+    });
+}
+/**
+ * Resolve a native-terminal PTY session's durable pgid, for a reap that may
+ * come from a host that never knew the session (e.g. a fresh host started
+ * after the owning host was killed).
+ *
+ * Reads via `loadRegistryWithDiagnostics`, NEVER via the plain `loadRegistry`
+ * array reader: `loadRegistry` silently flattens a corrupt/unreadable
+ * registry to `[]`, which would conflate two very different situations —
+ * "this session genuinely has no recorded pgid" vs. "the registry could not
+ * be read at all". A reaper must tell those apart: an unreadable registry
+ * must NEVER be treated as "nothing to reap" (that recreates the exact
+ * invisible-orphan bug this mechanism exists to close), so it is reported as
+ * `unresolved` with a diagnostic reason, loudly, by the caller (see
+ * `NativeTerminalHost#reapOrphan`), which must never guess a pgid or kill
+ * silently on either branch below.
+ *
+ * (If/when a future 3-state `loadRegistry` lands — `state: "ok" | "unknown"`
+ * — the migration is a refinement of the condition below, not a new branch:
+ * map `state: "unknown"` to the same `unresolved` result.)
+ */
+export function readNativeTerminalPgid(sessionId, path = resolveRegistryPath()) {
+    const diagnostics = loadRegistryWithDiagnostics(path);
+    if (!diagnostics.known) {
+        return {
+            status: "unresolved",
+            reason: `registry unreadable: ${diagnostics.reason ?? "unknown reason"}`,
+        };
+    }
+    const id = nativeTerminalPgidEntryId(sessionId);
+    const entry = diagnostics.entries.find((e) => e.id === id);
+    if (!entry || typeof entry.pgid !== "number") {
+        return {
+            status: "unresolved",
+            reason: `no pgid recorded for terminal session ${sessionId}`,
+        };
+    }
+    return {
+        status: "resolved",
+        pgid: entry.pgid,
+        ...(typeof entry.pgidLeaderStartTime === "number"
+            ? { leaderStartTime: entry.pgidLeaderStartTime }
+            : {}),
+        ...(typeof entry.pgidGroupToken === "string"
+            ? { groupToken: entry.pgidGroupToken }
+            : {}),
+    };
+}
+/**
+ * Enumerate every durably-persisted native-terminal PTY session, for a
+ * reconcile pass that must decide, PER ENTRY, whether its owning host is
+ * proven dead (see `reconcileDeadHostOrphans` in native-terminal/host.ts, the
+ * sole consumer). Reads via `loadRegistryWithDiagnostics` for the same reason
+ * `readNativeTerminalPgid` does: an unreadable registry must never collapse
+ * to "zero entries" — that would silently make a reconcile pass reap
+ * (or skip) NOTHING while believing it saw the whole truth.
+ */
+export function listNativeTerminalPgidEntries(path = resolveRegistryPath()) {
+    const diagnostics = loadRegistryWithDiagnostics(path);
+    if (!diagnostics.known) {
+        return { known: false, reason: diagnostics.reason ?? "unknown reason" };
+    }
+    const entries = [];
+    for (const e of diagnostics.entries) {
+        if (!e.id.startsWith(NATIVE_TERMINAL_PGID_ENTRY_ID_PREFIX))
+            continue;
+        if (typeof e.pgid !== "number")
+            continue;
+        const sessionId = e.id.slice(NATIVE_TERMINAL_PGID_ENTRY_ID_PREFIX.length);
+        const entry = {
+            sessionId,
+            pgid: e.pgid,
+        };
+        if (typeof e.ownerHostPid === "number") {
+            const owner = { pid: e.ownerHostPid };
+            if (typeof e.ownerHostStartTime === "number")
+                owner.startTime = e.ownerHostStartTime;
+            entry.owner = owner;
+        }
+        entries.push(entry);
+    }
+    return { known: true, entries };
+}
+/**
+ * Remove a single native-terminal-pty row once its orphan group has been
+ * reaped (or it is otherwise confirmed handled). Returns false when the id
+ * was not present (already pruned, or never existed) — a no-op, not an
+ * error, since a reconcile pass may race a concurrent prune of the same row.
+ */
+export function pruneNativeTerminalPgidEntry(sessionId, path = resolveRegistryPath()) {
+    const id = nativeTerminalPgidEntryId(sessionId);
+    return withRegistryLock(path, (entries) => {
+        const idx = entries.findIndex((e) => e.id === id);
+        if (idx < 0)
+            return { entries, result: false, save: false };
+        const next = entries.slice(0, idx).concat(entries.slice(idx + 1));
+        return { entries: next, result: true };
+    });
+}
 function isRegistryEntry(raw) {
     if (!raw || typeof raw !== "object")
         return false;
     const e = raw;
     return (typeof e.id === "string" &&
         (e.tool === "claude" || e.tool === "codex" || e.tool === "agy") &&
-        (e.kind === "local-tmux" || e.kind === "local" || e.kind === "remote") &&
+        (e.kind === "local-tmux" || e.kind === "local-native" || e.kind === "local" || e.kind === "remote") &&
         typeof e.cwd === "string" &&
         typeof e.enrolledAt === "string" &&
         typeof e.lastSeenAt === "string" &&
@@ -102,14 +441,46 @@ function isRegistryEntry(raw) {
             e.delegationOrigin === "mcp:h2a_run" ||
             e.delegationOrigin === "cli:h2a-delegate") &&
         (e.pid === undefined || (typeof e.pid === "number" && Number.isInteger(e.pid) && e.pid > 0)) &&
+        (e.pgid === undefined || (typeof e.pgid === "number" && Number.isInteger(e.pgid) && e.pgid > 0)) &&
+        (e.pgidLeaderStartTime === undefined ||
+            (typeof e.pgidLeaderStartTime === "number" &&
+                Number.isInteger(e.pgidLeaderStartTime) &&
+                e.pgidLeaderStartTime >= 0)) &&
+        (e.pgidGroupToken === undefined || typeof e.pgidGroupToken === "string") &&
+        (e.ownerHostPid === undefined ||
+            (typeof e.ownerHostPid === "number" && Number.isInteger(e.ownerHostPid) && e.ownerHostPid > 0)) &&
+        (e.ownerHostStartTime === undefined ||
+            (typeof e.ownerHostStartTime === "number" &&
+                Number.isInteger(e.ownerHostStartTime) &&
+                e.ownerHostStartTime >= 0)) &&
         (e.delegatorInstance === undefined || typeof e.delegatorInstance === "string") &&
-        (e.delegatorTmuxSession === undefined || typeof e.delegatorTmuxSession === "string"));
+        (e.delegatorTmuxSession === undefined || typeof e.delegatorTmuxSession === "string") &&
+        (e.restorePinned === undefined || typeof e.restorePinned === "boolean"));
 }
-/** Atomic write: tmp file in the same dir, then rename. */
-function saveRegistry(entries, path) {
+/**
+ * Atomic write: tmp file in the same dir, then rename. `preserved` carries
+ * raw rows that FAIL validation (e.g. `kind` unreadable): they are written
+ * back verbatim so a load-mutate-save cycle never silently ERASES an
+ * unreadable row from the file (sol-2 — an erased row turns "host state
+ * unknown" into "no local session", re-routing destructive acts).
+ *
+ * `rebuiltFromCorruptAt` (B2) stamps the WHOLE-FILE trace when this save is
+ * the rebuild that followed a whole-file-unknown read: `loadRegistry` turns
+ * its presence into an "unknown" verdict for every subsequent READ, until a
+ * later `saveRegistry` call (one that did NOT rebuild from corrupt) omits it
+ * again and the trace clears.
+ */
+function saveRegistry(entries, path, preserved = [], rebuiltFromCorruptAt) {
     mkdirSync(dirname(path), { recursive: true });
     const tmp = `${path}.tmp.${process.pid}`;
-    writeFileSync(tmp, JSON.stringify({ version: 1, entries }, null, 2), "utf8");
+    const body = {
+        version: 1,
+        entries: [...entries, ...preserved],
+    };
+    if (rebuiltFromCorruptAt !== undefined) {
+        body.rebuiltFromCorruptAt = rebuiltFromCorruptAt;
+    }
+    writeFileSync(tmp, JSON.stringify(body, null, 2), "utf8");
     renameSync(tmp, path);
 }
 // ---------------------------------------------------------------------------
@@ -143,9 +514,24 @@ function saveRegistry(entries, path) {
 export function withRegistryLock(path, fn) {
     const fd = acquireFileLock(path);
     try {
-        const { entries, result, save } = fn(loadRegistry(path));
-        if (save !== false)
-            saveRegistry(entries, path);
+        // WRITE-path raw read: enrolment deliberately REBUILDS a missing/corrupt
+        // registry (a hiccup must not brick every future enrolment), so an
+        // unknown state flattens to `[]` for `fn`'s input — but see below: the
+        // corrupt BYTES are moved aside (never overwritten in place) before any
+        // write that actually rebuilds from that `[]`.
+        const raw = rawRegistryRead(path);
+        const rows = raw.state === "ok" ? raw.rows : [];
+        const { entries, result, save } = fn(rows.filter(isRegistryEntry));
+        if (save !== false) {
+            // B2 — "REBUILDING is allowed. DESTROYING is not.": only reached when
+            // a write is ACTUALLY about to rebuild the file, never on a read-only
+            // `save:false` no-op (prune finding nothing to change on a corrupt
+            // file must not spam a fresh registry.corrupt-*.json on every poll).
+            const rebuiltFromCorruptAt = raw.state === "unknown" ? moveAsideUnreadableRegistry(path) : undefined;
+            // Unreadable rows are preserved verbatim: a mutation of the VALID
+            // entries must never erase what it could not read (sol-2).
+            saveRegistry(entries, path, rows.filter((row) => !isRegistryEntry(row)), rebuiltFromCorruptAt);
+        }
         return result;
     }
     finally {
@@ -292,6 +678,15 @@ function applyEnroll(entries, input) {
     const gatewayMode = input.gatewayMode ?? prev?.gatewayMode;
     if (gatewayMode !== undefined)
         entry.gatewayMode = gatewayMode;
+    if (input.restorePinned !== undefined) {
+        entry.restorePinned = input.restorePinned;
+    }
+    else if (prev?.restorePinned !== undefined) {
+        entry.restorePinned = prev.restorePinned;
+    }
+    else {
+        entry.restorePinned = shouldPreserveByRestorePin(entry);
+    }
     if (idx >= 0)
         entries[idx] = entry;
     else
@@ -381,7 +776,14 @@ export function advanceJob(id, to, path = resolveRegistryPath()) {
 /** Live job entries (role "job"), liveness reconciled like any other entry. */
 export function listJobs(opts = {}) {
     const path = opts.path ?? resolveRegistryPath();
-    return loadRegistry(path).filter((e) => e.role === "job");
+    const read = loadRegistry(path);
+    // Unknown read → EMPTY VIEW, deliberately: this list feeds supervision
+    // views and job launch planning (acts that only ever START work); no
+    // kill/stop keys off it. Callers that must PROVE local absence go through
+    // resolveManagedHost, which transports the unknown read as a refusal.
+    return read.state === "ok"
+        ? read.entries.filter((e) => e.role === "job")
+        : [];
 }
 /** Refresh lastSeenAt. Returns false when the id is unknown. */
 export function touchEntry(id, path = resolveRegistryPath()) {
@@ -416,6 +818,16 @@ function defaultTmuxHasSession(name) {
         return false;
     }
 }
+function defaultNativeSessionLiveness(name) {
+    try {
+        return nativeSessionLiveness(name);
+    }
+    catch {
+        // The producer already maps its own failures to "unknown"; this belt
+        // keeps an unexpected throw from ever reading as death.
+        return "unknown";
+    }
+}
 function defaultPidAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -468,6 +880,16 @@ function processIsTool(pid, tool, read) {
 export function isLive(e, opts = {}) {
     if (e.endedAt)
         return false;
+    if (e.kind === "local-native") {
+        const liveness = opts.nativeSessionLiveness ?? defaultNativeSessionLiveness;
+        // "unknown" deliberately counts as possibly-live here (`!== false`):
+        // isLive feeds views AND prune — erasing the host pin of an unprovable
+        // session would re-route later destructive acts (F2). Only a POSITIVE
+        // "false" reads as death.
+        return (e.tmuxSession
+            ? [e.tmuxSession]
+            : managedSessionCandidates(e.id)).some((name) => liveness(name) !== false);
+    }
     if (e.kind === "local-tmux") {
         const has = opts.tmuxHasSession ?? defaultTmuxHasSession;
         return (e.tmuxSession
@@ -498,13 +920,39 @@ export function isLive(e, opts = {}) {
 /** Entries considered live right now (see isLive for the per-kind rules). */
 export function listLive(opts = {}) {
     const path = opts.path ?? resolveRegistryPath();
-    return loadRegistry(path).filter((e) => isLive(e, opts));
+    const read = loadRegistry(path);
+    // Unknown read → EMPTY VIEW: `ls`-style projections degrade to showing no
+    // registry rows (the status bar has its own UNKNOWN rendering via
+    // loadRegistryWithDiagnostics). Guards that must prove the ABSENCE of a
+    // writer must not consume this list — convOwners reads the registry itself
+    // and refuses on an unknown read.
+    return read.state === "ok" ? read.entries.filter((e) => isLive(e, opts)) : [];
 }
 /**
  * Drop DEAD entries whose last activity (endedAt, else lastSeenAt) is older
  * than maxAgeHours. Live entries always stay; recently-dead ones stay too so
  * `restore` can still resume them after a reboot via the scan fallback.
  * Returns the number of removed entries.
+ *
+ * RECONCILIATION DECISION (2026-08, #199 rebase — restore-pin x FILE-level
+ * unknown; architect to re-measure): `shouldPreserveByRestorePin` never
+ * observes `loadRegistry()`'s 3-state read directly — it runs INSIDE
+ * `withRegistryLock`, over the already-validated `entries` array only. Two
+ * unprovable cases both resolve CONSERVATIVE-PRESERVE by construction,
+ * neither newly added here:
+ *  - whole-FILE unknown (corrupt/unreadable registry.json):
+ *    `withRegistryLock`'s own raw read flattens to `[]` for its write-path
+ *    contract, so `kept.length === entries.length` (0 === 0) and this prune
+ *    is a NO-OP (`save:false`, see below) — nothing is read, so nothing a
+ *    restore pin could have kept is ever written over or lost.
+ *  - a single restore-pinned row that fails `isRegistryEntry` (per-row
+ *    unreadable, PART A): it never reaches `entries` here at all (excluded
+ *    before this callback runs), but `withRegistryLock`/`saveRegistry`
+ *    re-append every such raw row VERBATIM on every write (sol-2) —
+ *    `shouldPreserveByRestorePin` cannot prune what it never sees, and the
+ *    row survives regardless of what this function decides.
+ * Neither case is exercised through an explicit `state:"unknown"` branch
+ * here (there isn't one to write) — REPORTED, not silently assumed settled.
  */
 export function prune(maxAgeHours, opts = {}) {
     const path = opts.path ?? resolveRegistryPath();
@@ -513,6 +961,8 @@ export function prune(maxAgeHours, opts = {}) {
         const kept = entries.filter((e) => {
             if (isLive(e, opts))
                 return true;
+            if (shouldPreserveByRestorePin(e))
+                return true;
             const last = Date.parse(e.endedAt ?? e.lastSeenAt);
             return Number.isFinite(last) && last >= cutoff;
         });
@@ -544,11 +994,17 @@ export function enrollFromRun(args) {
     const tool = coerceRegistryTool(args.profile);
     if (!tool)
         return; // shell/opencode/… sessions stay tmux-only
+    // Runtime twin of the required-parameter type: an untyped caller that omits
+    // the host gets NO row rather than a row on a guessed host. Never default.
+    if (args.hostKind !== "local-tmux" && args.hostKind !== "local-native") {
+        process.stderr.write(`[h2a] registry enrolment refused for ${args.slug}: caller did not name the terminal host\n`);
+        return;
+    }
     try {
         enroll({
             id: args.slug,
             tool,
-            kind: "local-tmux",
+            kind: args.hostKind,
             cwd: args.cwd,
             source: "run",
             label: args.slug,
@@ -603,7 +1059,7 @@ export function localLsRows(sessions, live) {
     // kind:"local" entries are Claude Code conversation sessions (UUID ids,
     // no tmuxSession) — they are internal CC state, not user-facing sessions.
     for (const e of live) {
-        if (e.kind !== "local-tmux" || matched.has(e.id))
+        if (!isManagedLocalKind(e.kind) || matched.has(e.id))
             continue;
         // A historical record without an exact tmux name cannot authoritatively
         // claim either member of a live h2a-/remote- collision. It already remains
@@ -649,7 +1105,7 @@ export function listLocalForLs(opts = {}) {
 export function resolveLocalTmuxSessionForName(target, entries) {
     const requested = parseManagedSessionName(target);
     const matches = entries.filter((e) => {
-        if (e.role !== undefined || e.kind !== "local-tmux" || e.endedAt) {
+        if (e.role !== undefined || !isManagedLocalKind(e.kind) || e.endedAt) {
             return false;
         }
         // A full managed name is an exact selector, never a slug/label alias.
@@ -692,4 +1148,187 @@ export function localTmuxSessionForName(target, entries) {
     const resolution = resolveLocalTmuxSessionForName(target, entries);
     return resolution.kind === "found" ? resolution.name : undefined;
 }
+/**
+ * DEDICATED resolver for `kind:"local-native"` registry entries — the native
+ * twin of the local-tmux target filter in index.ts. That filter stays
+ * tmux-scoped on purpose: its second caller iterates LIVE tmux sessions by
+ * name inside the destructive relaunch planner, where a broadened match would
+ * be a category error. The two resolvers coexist so neither lies about its
+ * name.
+ *
+ * A native entry's PERSISTED identity, as measured on every native write path
+ * (`enroll` in startJob and `enrollFromRun` on run/resume/relaunch): `id` and
+ * `label` carry the slug, and `tmuxSession` — despite its tmux-era name —
+ * carries the native host session name `localSessionName(slug)`, the
+ * h2a-<slug> naming contract shared across hosts (native-host.ts). Historical
+ * rows without a persisted session name fall back to the managed-name
+ * candidates of their id, exactly like `isLive`.
+ *
+ * NO liveness input exists here by construction: which host a recorded
+ * session belongs to is decided by its persisted kind alone — a dead native
+ * session stays native. Whether an ACT on it can proceed is the caller's
+ * separate liveness gate.
+ * (0 local-native entries in the fleet registry as of 2026-08-08; this
+ * resolver prepares the re-use paths for the sessions #178 will produce.)
+ */
+export function registryEntriesForNativeTarget(target, 
+// No default read: the caller owns the registry READ STATE (an unknown
+// read must refuse upstream, never flatten into "no rows" here).
+entries) {
+    return registryEntriesForManagedKind("local-native", target, entries);
+}
+/**
+ * The SAME exact-identity filter scoped to persisted `kind:"local-tmux"` rows.
+ * It exists so host resolution can consult BOTH persisted kinds symmetrically
+ * (`resolveManagedHost`): recognizing only one kind before falling back to a
+ * probe was the measured F2 defect — a persisted tmux row plus a homonymous
+ * live native process re-routed destructive acts to the wrong host.
+ * (The broader index.ts local-tmux target filter stays separate on purpose:
+ * it also matches LIVE tmux state for the relaunch planner.)
+ */
+export function registryEntriesForLocalTmuxTarget(target, 
+// No default read: the caller owns the registry READ STATE (an unknown
+// read must refuse upstream, never flatten into "no rows" here).
+entries) {
+    return registryEntriesForManagedKind("local-tmux", target, entries);
+}
+function registryEntriesForManagedKind(kind, target, entries) {
+    const requested = parseManagedSessionName(target);
+    const candidates = requested ? [target] : managedSessionCandidates(target);
+    return entries.filter((e) => {
+        if (e.kind !== kind)
+            return false;
+        // A positively-ENDED session no longer pins a host: only current rows
+        // take part in host resolution (mirrors isLive's endedAt short-circuit).
+        if (e.endedAt !== undefined)
+            return false;
+        // A full managed name is an exact selector, never a slug/label alias
+        // (same rule as the tmux filter and resolveLocalTmuxSessionForName).
+        if (requested) {
+            return (e.tmuxSession === target ||
+                (e.tmuxSession === undefined && e.id === requested.slug));
+        }
+        return (e.id === target ||
+            e.label === target ||
+            (e.tmuxSession !== undefined && candidates.includes(e.tmuxSession)));
+    });
+}
+/** Native probe: an op failure is UNKNOWN, never dead (producer is 3-state). */
+export function probeNativeSession(name) {
+    try {
+        const alive = nativeSessionLiveness(name);
+        if (alive === true)
+            return "live";
+        if (alive === false)
+            return "dead";
+        return "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+/**
+ * Tmux probe. No tmux binary/server means no tmux session CAN exist (a tmux
+ * session cannot outlive its server), so that is provable death — only a
+ * spawn-level failure of an installed tmux is UNKNOWN.
+ */
+export function probeTmuxSession(name) {
+    if (!tmuxAvailable())
+        return "dead";
+    try {
+        // "=" prefix forces an exact session-name match (no prefix matching).
+        const r = spawnSync("tmux", ["has-session", "-t", `=${name}`], {
+            stdio: "ignore",
+        });
+        if (r.error)
+            return "unknown";
+        return r.status === 0 ? "live" : "dead";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function isRegistryReadResult(value) {
+    return !Array.isArray(value);
+}
+export function resolveManagedHost(target, entries = loadRegistry(), probes = {}) {
+    // The registry READ STATE is part of the resolution (F2): an unreadable
+    // registry means the persisted host cannot be proven — transported as
+    // "unknown" so every destructive caller refuses instead of treating the
+    // unprovable rows as absent and probing/guessing a host.
+    const read = isRegistryReadResult(entries)
+        ? entries
+        // A plain-array caller carries NO unreadable-row information (it never
+        // had a snapshot to draw one from) — `unreadable:[]` here is a neutral
+        // "none known", not a claim that none exist. Callers that hold a real
+        // `loadRegistry()` snapshot MUST pass it whole (not `.entries`) for the
+        // per-identity poison check below to see the unreadable rows at all.
+        : { state: "ok", entries: [...entries], unreadable: [] };
+    if (read.state === "unknown") {
+        return {
+            state: "unknown",
+            reason: `registry read failed: ${read.reason}`,
+        };
+    }
+    // A2 (PART A — resolver per-identity unreadable check, sol-2): for target
+    // identity X, ask "is there an unreadable row that COULD be X?" — a
+    // same-name/same-form TWIN — never "are there any unreadable rows at all?".
+    // A hit poisons the resolution for X ONLY; every OTHER identity in this
+    // same registry stays fully resolvable. This runs BEFORE the recorded/
+    // discovered/missing branches below (A3 — the kill must not precede the
+    // check): a valid row for X plus an unreadable twin of X must never reach
+    // "recorded" and hand a caller a name to kill.
+    const unreadableForTarget = unreadableRowsForTarget(target, read.unreadable);
+    if (unreadableForTarget.length > 0) {
+        const ids = unreadableForTarget
+            .map((row) => (typeof row.id === "string" ? row.id : "<no id>"))
+            .join(", ");
+        return {
+            state: "unknown",
+            reason: `unreadable registry row(s) for this identity (row id: ${ids})`,
+        };
+    }
+    const rows = read.entries;
+    const nativeRows = registryEntriesForNativeTarget(target, rows);
+    const tmuxRows = registryEntriesForLocalTmuxTarget(target, rows);
+    const exactName = (rows) => rows[0]?.tmuxSession ??
+        (parseManagedSessionName(target)
+            ? target
+            : localSessionName(rows[0]?.id ?? target));
+    if (nativeRows.length > 0 && tmuxRows.length > 0) {
+        return { state: "ambiguous", candidates: ["local-native", "local-tmux"] };
+    }
+    if (nativeRows.length > 0) {
+        return { state: "recorded", kind: "local-native", name: exactName(nativeRows) };
+    }
+    if (tmuxRows.length > 0) {
+        return { state: "recorded", kind: "local-tmux", name: exactName(tmuxRows) };
+    }
+    // Discovery: probes may only run when NO persisted row exists.
+    const probedName = parseManagedSessionName(target)
+        ? target
+        : localSessionName(target);
+    const native = (probes.native ?? probeNativeSession)(probedName);
+    const tmux = (probes.tmux ?? probeTmuxSession)(probedName);
+    if (native === "unknown" || tmux === "unknown") {
+        const failed = [
+            ...(native === "unknown" ? ["native"] : []),
+            ...(tmux === "unknown" ? ["tmux"] : []),
+        ].join("+");
+        return {
+            state: "unknown",
+            reason: `${failed} host probe failed for ${probedName}`,
+        };
+    }
+    if (native === "live" && tmux === "live") {
+        return { state: "ambiguous", candidates: ["local-native", "local-tmux"] };
+    }
+    if (native === "live") {
+        return { state: "discovered", kind: "local-native", name: probedName };
+    }
+    if (tmux === "live") {
+        return { state: "discovered", kind: "local-tmux", name: probedName };
+    }
+    return { state: "missing" };
+}
 //# sourceMappingURL=registry.js.map