sealkeep 0.9.0 → 0.11.0

package/dist/src/adapters.js

@@ -1,7 +1,10 @@
-import { access, mkdir, open, readdir, readFile, rename, stat, writeFile } from "node:fs/promises";
+import { access, mkdir, open, readdir, readFile, realpath, rename, stat, writeFile } from "node:fs/promises";
 import { constants } from "node:fs";
-import { randomUUID } from "node:crypto";
-import { dirname, join, resolve, sep } from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { fileURLToPath } from "node:url";
 import { fail } from "./errors.js";
 /**
  * One table, so detection, hook installation and the setup API answer from the
@@ -12,10 +15,12 @@ const AGENTS = {
     codex: {
         label: "Codex CLI",
         root: (home) => join(home, ".codex"),
-        // Codex configures itself in TOML, so its hooks cannot be merged in by this
-        // build; `installAgentHooks` produces a reviewable fragment instead.
-        hookFile: (home) => join(home, ".codex", "config.toml"),
-        hookFileFormat: "toml",
+        // Codex reads lifecycle hooks from ~/.codex/hooks.json as well as inline
+        // config.toml tables. The dedicated JSON file is the safe integration
+        // surface: Sealkeep can merge it without parsing or rewriting the person's
+        // TOML settings, and Codex still applies its normal one-time trust review.
+        hookFile: (home) => join(home, ".codex", "hooks.json"),
+        hookFileFormat: "json",
         archivable: true,
         transcriptRoots: (home) => [join(home, ".codex", "sessions"), join(home, ".codex", "archived_sessions")]
     },
@@ -64,6 +69,7 @@ const AGENTS = {
 export const SETUP_AGENT_IDS = Object.keys(AGENTS);
 /** The subset with a session adapter. Mirrors `AgentId` at runtime for schema use. */
 export const ARCHIVING_AGENT_IDS = ["codex", "claude"];
+export const HOOK_LIFECYCLE_VERSION = 3;
 /** Narrows a setup id to an archiving one, so callers prove the subset rather than casting to it. */
 export function isArchivingAgent(agent) {
     return ARCHIVING_AGENT_IDS.includes(agent);
@@ -93,19 +99,42 @@ export async function detectAgents(home = process.env.HOME ?? ".") {
  * the naive re-expansion, kept because "which /Users/… did this come from" is
  * still worth answering approximately.
  */
+/**
+ * Which archiving agent wrote a transcript, judged by where it lives. A file
+ * under `~/.claude/projects` is Claude's; under `~/.codex/sessions` (or its
+ * archived sibling) it is Codex's. This is what lets a hand-sealed
+ * `sealkeep archive <file>` carry the same agent — and therefore the same
+ * project derivation — as the watcher would have given it, instead of the
+ * "custom" label that leaves the session untagged and invisible to every
+ * project-scoped recall.
+ */
+export function agentForTranscriptPath(path, home = process.env.HOME ?? ".") {
+    const target = resolve(path);
+    for (const agent of ["codex", "claude"]) {
+        for (const root of AGENTS[agent].transcriptRoots(home)) {
+            const base = resolve(root);
+            if (target === base || target.startsWith(base + sep))
+                return agent;
+        }
+    }
+    return null;
+}
 export function claudeProjectFromPath(path) {
     const marker = `${sep}.claude${sep}projects${sep}`;
     const start = path.indexOf(marker);
     if (start === -1)
-        return { project: null, projectPath: null };
+        return { project: null, projectKey: null, projectPath: null };
     const rest = path.slice(start + marker.length).split(sep);
     // A .jsonl directly under projects/ is a stray file, not a project directory.
     if (rest.length < 2)
-        return { project: null, projectPath: null };
+        return { project: null, projectKey: null, projectPath: null };
     const segments = rest[0].split("-").filter(Boolean);
     if (segments.length === 0)
-        return { project: null, projectPath: null };
-    return { project: segments[segments.length - 1], projectPath: rest[0].replace(/-/g, "/") };
+        return { project: null, projectKey: null, projectPath: null };
+    // The encoded directory is lossy (a literal dash and a path separator are
+    // indistinguishable), so it cannot safely become an access-control key.
+    // Real transcripts contain cwd and take the projectFromCwd path below.
+    return { project: segments[segments.length - 1], projectKey: null, projectPath: rest[0].replace(/-/g, "/") };
 }
 /**
  * A rollout's first line is its session-meta record, and `cwd` in it is the
@@ -118,13 +147,269 @@ export function claudeProjectFromPath(path) {
  */
 const FIRST_LINE_BYTES = 8192;
 const codexIdentityCache = new Map();
+/**
+ * The munged directory name under ~/.claude/projects encodes "/" as "-", so a
+ * folder whose NAME contains a hyphen is indistinguishable from nesting:
+ * ~/tiny-ledger reads back as project "ledger". The transcript itself records
+ * the real cwd on nearly every line, so while the file is on disk the honest
+ * answer is one bounded read away — same cache discipline as the codex
+ * first-line read. The path arithmetic stays as the fallback for transcripts
+ * that carry no cwd at all. Caught live: one folder, two agents, and the
+ * shared project memory split in half.
+ */
+const runGit = promisify(execFile);
+// Project discovery runs while the dashboard is loading every transcript on
+// the machine. A workstation can easily have hundreds of distinct recorded
+// cwd values, and `execFile` has no backpressure of its own: launching one Git
+// process per cwd at once starves the UI even though every individual command
+// is small. Four keeps discovery moving without turning a metadata scan into a
+// process storm.
+const MAX_CONCURRENT_GIT_COMMANDS = 4;
+let activeGitCommands = 0;
+const waitingGitCommands = [];
+async function acquireGitCommandSlot() {
+    if (activeGitCommands < MAX_CONCURRENT_GIT_COMMANDS) {
+        activeGitCommands += 1;
+        return;
+    }
+    await new Promise((ready) => waitingGitCommands.push(ready));
+}
+function releaseGitCommandSlot() {
+    const next = waitingGitCommands.shift();
+    if (next) {
+        // Transfer this occupied slot directly to the oldest waiter. Decrementing
+        // first would let a newly-arrived command jump the queue before `next`
+        // resumes on the microtask queue and could exceed the bound.
+        next();
+    }
+    else {
+        activeGitCommands -= 1;
+    }
+}
+async function runGitCommand(args) {
+    await acquireGitCommandSlot();
+    try {
+        const result = await runGit("git", args, { timeout: 2000, encoding: "utf8" });
+        return { stdout: String(result.stdout), stderr: String(result.stderr) };
+    }
+    finally {
+        releaseGitCommandSlot();
+    }
+}
+const projectIdentityCache = new Map();
+const projectIdentityInFlight = new Map();
+function digestProjectKey(prefix, value) {
+    return `${prefix}:${createHash("sha256").update(value).digest("hex")}`;
+}
+/** Canonicalises the common HTTPS/SSH/scp git spellings without credentials or query data. */
+function canonicalGitRemote(raw, relativeTo) {
+    const input = raw.trim();
+    if (!input)
+        return null;
+    let host = "";
+    let path = "";
+    try {
+        if (input.includes("://")) {
+            const url = new URL(input);
+            if (url.protocol === "file:") {
+                host = "local";
+                path = fileURLToPath(url);
+            }
+            else {
+                // `hostname` deliberately omits the port. That collapsed two independent
+                // self-hosted Git servers at :8443 and :9443 into one access-control key.
+                const defaultPort = (url.protocol === "ssh:" && url.port === "22")
+                    || (url.protocol === "https:" && url.port === "443")
+                    || (url.protocol === "http:" && url.port === "80");
+                // Git hosts are ASCII/punycode. Locale-sensitive casing would let the
+                // same remote hash differently on machines with different locales.
+                host = `${url.hostname.toLowerCase()}${url.port && !defaultPort ? `:${url.port}` : ""}`;
+                path = url.pathname;
+            }
+        }
+        else {
+            // git@github.com:owner/repo.git (also accepts host:owner/repo.git).
+            const scp = /^(?:[^@/\s]+@)?([^:/\s]+):(.+)$/.exec(input);
+            if (scp) {
+                host = scp[1].toLowerCase();
+                path = scp[2];
+            }
+            else {
+                // Local remotes are still stable on this machine. They intentionally
+                // do not converge with a hosted URL because there is no proof that
+                // they name the same repository.
+                host = "local";
+                // Git interprets a relative local remote from the repository, not from
+                // whichever cwd happened to launch the long-running daemon.
+                path = isAbsolute(input) ? input : resolve(relativeTo, input);
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    const cleanPath = path.replace(/[?#].*$/, "").replace(/^\/+|\/+$/g, "").replace(/\.git$/i, "");
+    const label = basename(cleanPath);
+    return host && cleanPath && label ? { host, path: cleanPath, label } : null;
+}
+async function gitProjectForCwd(cwd) {
+    if (!cwd)
+        return { identity: null, configPath: null };
+    try {
+        const { stdout: rootOut } = await runGitCommand(["-C", cwd, "rev-parse", "--show-toplevel"]);
+        const root = rootOut.trim();
+        if (!root)
+            return { identity: null, configPath: null };
+        const canonicalCwd = await realpath(cwd).catch(() => resolve(cwd));
+        const canonicalRoot = await realpath(root).catch(() => resolve(root));
+        const [remoteOut, commonOut] = await Promise.all([
+            runGitCommand(["-C", cwd, "remote", "get-url", "origin"]).then((result) => result.stdout, () => ""),
+            runGitCommand(["-C", cwd, "rev-parse", "--git-common-dir"]).then((result) => result.stdout.trim(), () => ""),
+        ]);
+        const commonDir = commonOut ? (isAbsolute(commonOut) ? commonOut : resolve(canonicalRoot, commonOut)) : "";
+        const configPath = commonDir ? join(commonDir, "config") : null;
+        const remote = canonicalGitRemote(remoteOut, canonicalRoot);
+        if (!remote)
+            return { identity: null, configPath };
+        const inside = relative(canonicalRoot, canonicalCwd).split(sep).join("/");
+        return {
+            configPath,
+            identity: {
+                project: remote.label,
+                projectKey: digestProjectKey("g1", `${remote.host}/${remote.path}\0${inside}`),
+                projectPath: cwd,
+            },
+        };
+    }
+    catch {
+        return { identity: null, configPath: null };
+    }
+}
+async function pathStamp(path) {
+    try {
+        const entry = await stat(path);
+        const object = `${entry.dev}:${entry.ino}`;
+        return { object, modifiedAtMs: entry.mtimeMs, isDirectory: entry.isDirectory() };
+    }
+    catch {
+        return null;
+    }
+}
+async function fileFingerprint(path) {
+    try {
+        const [entry, contents] = await Promise.all([stat(path), readFile(path)]);
+        return `${entry.dev}:${entry.ino}:${contents.length}:${createHash("sha256").update(contents).digest("hex")}`;
+    }
+    catch {
+        return null;
+    }
+}
+async function cachedProjectIdentity(cwd, current) {
+    const cached = projectIdentityCache.get(cwd);
+    if (!cached)
+        return null;
+    if (!current.isDirectory || current.object !== cached.cwdObject)
+        return null;
+    if (cached.gitConfigPath) {
+        const fingerprint = await fileFingerprint(cached.gitConfigPath);
+        if (fingerprint !== (cached.gitConfigFingerprint ?? null))
+            return null;
+    }
+    else if (current.modifiedAtMs !== cached.cwdModifiedAtMs) {
+        return null;
+    }
+    return { ...cached.identity };
+}
+async function resolveProjectIdentity(cwd, segments) {
+    // Transcripts routinely outlive the checkout they were recorded in. Git
+    // cannot add information for a cwd that no longer exists (or is a file), so
+    // do not spawn it. The absence is deliberately not put in the persistent
+    // cache: if the checkout appears later, the next scan detects it normally.
+    const initialStamp = await pathStamp(cwd);
+    if (!initialStamp?.isDirectory) {
+        return {
+            project: segments[segments.length - 1],
+            projectKey: digestProjectKey("p1", resolve(cwd)),
+            projectPath: cwd,
+        };
+    }
+    const cached = await cachedProjectIdentity(cwd, initialStamp);
+    if (cached)
+        return cached;
+    const git = await gitProjectForCwd(cwd);
+    const identity = git.identity ?? {
+        project: segments[segments.length - 1],
+        projectKey: digestProjectKey("p1", await realpath(cwd).catch(() => resolve(cwd))),
+        projectPath: cwd,
+    };
+    const cwdStamp = await pathStamp(cwd);
+    if (cwdStamp?.isDirectory) {
+        const configFingerprint = git.configPath ? await fileFingerprint(git.configPath) : null;
+        projectIdentityCache.set(cwd, {
+            identity,
+            cwdObject: cwdStamp.object,
+            cwdModifiedAtMs: cwdStamp.modifiedAtMs,
+            ...(git.configPath ? { gitConfigPath: git.configPath, gitConfigFingerprint: configFingerprint } : {}),
+        });
+    }
+    return { ...identity };
+}
+/** The project for a session's recorded cwd: the git remote's repo name, else the folder name. */
+export async function projectFromCwd(cwd) {
+    const segments = cwd.split(/[\\/]/).filter(Boolean);
+    if (segments.length === 0)
+        return { project: null, projectKey: null, projectPath: null };
+    // A full transcript scan resolves many files from the same cwd at once. One
+    // immutable in-flight answer is enough; completed answers still use the
+    // freshness-aware cache above, and every caller receives its own object.
+    const running = projectIdentityInFlight.get(cwd);
+    if (running)
+        return { ...await running };
+    const resolution = resolveProjectIdentity(cwd, segments);
+    projectIdentityInFlight.set(cwd, resolution);
+    try {
+        return { ...await resolution };
+    }
+    finally {
+        if (projectIdentityInFlight.get(cwd) === resolution)
+            projectIdentityInFlight.delete(cwd);
+    }
+}
+const claudeIdentityCache = new Map();
+export async function claudeProjectFromTranscript(path, modifiedAt) {
+    const cached = claudeIdentityCache.get(path);
+    let cwd = cached?.modifiedAt === modifiedAt ? cached.cwd : undefined;
+    if (cwd === undefined) {
+        let handle;
+        try {
+            handle = await open(path, "r");
+            const buffer = Buffer.alloc(FIRST_LINE_BYTES);
+            const { bytesRead } = await handle.read(buffer, 0, FIRST_LINE_BYTES, 0);
+            cwd = scannedCwd(buffer.subarray(0, bytesRead).toString("utf8"));
+        }
+        catch {
+            cwd = null; /* an unreadable head falls back to the path arithmetic */
+        }
+        finally {
+            await handle?.close().catch(() => { });
+        }
+        claudeIdentityCache.set(path, { modifiedAt, cwd });
+    }
+    // Cache only what is immutable in the transcript. Repository identity is
+    // intentionally revalidated: a missing checkout can appear later and an
+    // existing checkout can change origin without changing the transcript.
+    return cwd ? projectFromCwd(cwd) : claudeProjectFromPath(path);
+}
 export async function codexProjectFromRollout(path, modifiedAt) {
     const cached = codexIdentityCache.get(path);
-    if (cached && cached.modifiedAt === modifiedAt)
-        return { project: cached.project, projectPath: cached.projectPath };
-    const identity = await codexIdentityFromFirstLine(path);
-    codexIdentityCache.set(path, { modifiedAt, ...identity });
-    return identity;
+    let cwd = cached?.modifiedAt === modifiedAt ? cached.cwd : undefined;
+    if (cwd === undefined) {
+        cwd = await codexCwdFromFirstLine(path);
+        codexIdentityCache.set(path, { modifiedAt, cwd });
+    }
+    return cwd
+        ? projectFromCwd(cwd)
+        : { project: null, projectKey: null, projectPath: null };
 }
 /** `cwd` (or the older `cd`) on the record itself, or one level down in `payload`, where session-meta keeps it. */
 function recordedCwd(record, depth = 0) {
@@ -159,8 +444,7 @@ function scannedCwd(text) {
         return null;
     }
 }
-async function codexIdentityFromFirstLine(path) {
-    const none = { project: null, projectPath: null };
+async function codexCwdFromFirstLine(path) {
     let handle;
     try {
         handle = await open(path, "r");
@@ -177,15 +461,12 @@ async function codexIdentityFromFirstLine(path) {
             // bounded scan reads the head that was fetched and nothing more.
             cwd = scannedCwd(text);
         }
-        if (!cwd)
-            return none;
-        const segments = cwd.split(/[\\/]/).filter(Boolean);
-        return segments.length === 0 ? none : { project: segments[segments.length - 1], projectPath: cwd };
+        return cwd;
     }
     catch {
         // An unreadable first line is a session without a project, not an error:
         // the list must survive whatever a vendor format update does.
-        return none;
+        return null;
     }
     finally {
         await handle?.close().catch(() => { });
@@ -193,24 +474,19 @@ async function codexIdentityFromFirstLine(path) {
 }
 /**
  * Fills project identity in place, after the limit cut — resolving only what
- * will be returned keeps the codex reads proportional to the page, not the
- * disk. Claude's identity is pure path arithmetic; codex needs the bounded
- * first-line read, capped at 16 in flight so hundreds of cold files neither
- * run serially nor open hundreds of descriptors at once.
+ * will be returned keeps the reads proportional to the page, not the disk.
+ * Both agents take a bounded head read (claude for the recorded cwd, codex
+ * for its first-line meta), capped at 16 in flight so hundreds of cold files
+ * neither run serially nor open hundreds of descriptors at once.
  */
 async function attachProjects(candidates) {
-    const rollouts = [];
-    for (const candidate of candidates) {
-        if (candidate.agent === "claude")
-            Object.assign(candidate, claudeProjectFromPath(candidate.path));
-        else
-            rollouts.push(candidate);
-    }
     let next = 0;
-    await Promise.all(Array.from({ length: Math.min(16, rollouts.length) }, async () => {
-        while (next < rollouts.length) {
-            const candidate = rollouts[next++];
-            Object.assign(candidate, await codexProjectFromRollout(candidate.path, candidate.modifiedAt));
+    await Promise.all(Array.from({ length: Math.min(16, candidates.length) }, async () => {
+        while (next < candidates.length) {
+            const candidate = candidates[next++];
+            Object.assign(candidate, candidate.agent === "claude"
+                ? await claudeProjectFromTranscript(candidate.path, candidate.modifiedAt)
+                : await codexProjectFromRollout(candidate.path, candidate.modifiedAt));
         }
     }));
 }
@@ -222,13 +498,20 @@ async function attachProjects(candidates) {
  * arbitrary sessions that happened to be walked first. Only metadata is read,
  * so the cost is one stat per file.
  */
-async function walkJsonl(root, agent, output) {
+async function walkJsonl(root, agent, output, exclude) {
+    // Apply the exclusion before readdir/stat and before project metadata is
+    // attached. "Never watch" therefore means the excluded transcript branch
+    // is not processed merely so it can be thrown away later.
+    if (exclude?.(root))
+        return;
     if (!(await directoryExists(root)))
         return;
     for (const entry of await readdir(root, { withFileTypes: true })) {
         const path = join(root, entry.name);
+        if (exclude?.(path))
+            continue;
         if (entry.isDirectory())
-            await walkJsonl(path, agent, output);
+            await walkJsonl(path, agent, output, exclude);
         else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
             const file = await stat(path);
             output.push({ agent, path, bytes: file.size, modifiedAt: file.mtime.toISOString() });
@@ -240,13 +523,21 @@ async function walkJsonl(root, agent, output) {
  * read into a file is the codex rollout's first line, which is the session's
  * own metadata record — what was said in the session stays unread.
  */
-export async function findTranscripts(agent, home = process.env.HOME ?? ".", limit = 50) {
+export async function findTranscripts(agent, home = process.env.HOME ?? ".", limit, options = {}) {
     const install = (await detectAgents(home)).find((item) => item.agent === agent);
     const files = [];
     for (const root of install.transcriptRoots)
-        await walkJsonl(root, agent, files);
-    const recent = files.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt)).slice(0, limit);
-    await attachProjects(recent);
+        await walkJsonl(root, agent, files, options.exclude);
+    // Automatic preservation must be exhaustive: a fixed cap silently leaves old
+    // sessions behind on a long-lived workstation. Callers that intentionally
+    // render a bounded list can still pass an explicit limit.
+    const ordered = files.sort((a, b) => b.modifiedAt.localeCompare(a.modifiedAt));
+    const recent = limit === undefined ? ordered : ordered.slice(0, Math.max(0, limit));
+    // Watcher admission and enqueueing use only agent/path/size/mtime. Let that
+    // exhaustive background walk skip transcript-head JSON and Git identity;
+    // UI/project callers retain enrichment by default.
+    if (options.includeProjects !== false)
+        await attachProjects(recent);
     return recent;
 }
 /**
@@ -256,8 +547,12 @@ export async function findTranscripts(agent, home = process.env.HOME ?? ".", lim
  * it, so the command and the thing that recognises it can never disagree about
  * what a Sealkeep hook looks like.
  */
-export function hookCommand(agent, executable = "vaultline", dataDir = "~/.vaultline") {
-    return `${executable} ${hookMarker(agent)} --data-dir ${dataDir}`;
+export function hookCommand(agent, executable = "sealkeep", dataDir = "~/.sealkeep") {
+    return `${executable} ${hookMarker(agent)} --data-dir ${shellArgument(dataDir)} --lifecycle ${HOOK_LIFECYCLE_VERSION}`;
+}
+/** One shell argument, including paths with spaces and quotes. */
+function shellArgument(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
 }
 /** The substring that identifies a Sealkeep hook for one agent, wherever it is written. */
 export function hookMarker(agent) {
@@ -268,29 +563,61 @@ export function hookMarker(agent) {
  * an agent's settings: users must review and merge it themselves. The hook only
  * enqueues local work, so it needs no recovery phrase and no network access.
  */
-export function hookConfig(agent, executable = "vaultline", dataDir = "~/.vaultline") {
+export function hookConfig(agent, executable = "sealkeep", dataDir = "~/.sealkeep") {
     const command = hookCommand(agent, executable, dataDir);
     const entry = (timeout) => [{ hooks: [{ type: "command", command, timeout }] }];
-    // The resume side of the pair: SessionStart checks whether the transcript
-    // the agent is about to read left this disk for the vault, and puts it back
-    // first — resume never learns the file was away. Generous timeout, because
-    // an offloaded multi-GB session fetches from the bucket; the command itself
-    // never exits nonzero, so a slow restore is the worst case, not a broken one.
-    const rehydrate = `${executable} hook rehydrate --agent ${agent} --data-dir ${dataDir}`;
-    const rehydrateEntry = [{ matcher: "resume", hooks: [{ type: "command", command: rehydrate, timeout: 300 }] }];
+    // Heavy recall, hosted reconciliation and publishing never sit in front of
+    // the coding agent. An async producer seals context locally; the next safe
+    // boundary consumes that small local cache. This intentionally makes fresh
+    // information one boundary eventual instead of making every prompt wait for
+    // storage/network latency.
+    const context = `${executable} hook context --agent ${agent} --data-dir ${shellArgument(dataDir)} --lifecycle ${HOOK_LIFECYCLE_VERSION}`;
+    const contextSync = `${executable} hook context-sync --agent ${agent} --data-dir ${shellArgument(dataDir)} --lifecycle ${HOOK_LIFECYCLE_VERSION}`;
+    const contextPromptHook = {
+        type: "command", command: context, timeout: 2,
+        ...(agent === "codex" ? { additionalContextLimit: 4000 } : {})
+    };
+    const contextLiveHook = {
+        type: "command", command: context, timeout: 2,
+        ...(agent === "codex" ? { additionalContextLimit: 2000 } : {})
+    };
+    const contextStart = [{
+            matcher: agent === "codex" ? "startup|resume|clear|compact" : "startup|resume|clear",
+            hooks: [{ type: "command", command: contextSync, timeout: 30, async: true }]
+        }];
+    const contextPrompt = [{ hooks: [
+                contextPromptHook,
+                { type: "command", command: contextSync, timeout: 30, async: true },
+            ] }];
+    const contextLive = [{
+            // Claude reports Bash/Edit/Write; Codex reports shell/shell_command or
+            // apply_patch depending on the client build. One config serves both.
+            matcher: agent === "codex" ? "shell|shell_command|exec_command|apply_patch" : "Bash|Edit|Write",
+            hooks: [
+                contextLiveHook,
+                { type: "command", command: contextSync, timeout: 30, async: true },
+            ]
+        }];
     if (agent === "codex")
         return {
-            description: "Sealkeep records an archive intent locally, and puts archived transcripts back before a resume reads them. It holds no secret; rehydration uses this machine's keystore.",
+            description: "Sealkeep automatically recalls project memory, exchanges live team updates, and records archive intent locally. A reclaimed session stays as a lightweight native pointer and full transcript restore is explicit. Hooks use this machine's keystore and never embed a recovery phrase.",
             hooks: {
                 SessionEnd: [{ hooks: [{ type: "command", command, timeout: 3, statusMessage: "Queuing encrypted archive" }] }],
                 PostCompact: entry(3),
-                SessionStart: rehydrateEntry
+                SessionStart: contextStart,
+                UserPromptSubmit: contextPrompt,
+                PostToolUse: contextLive
             },
-            _vaultlineNote: "Run `sealkeep queue run` (with SEALKEEP_RECOVERY_PHRASE set) to encrypt queued sessions. If this Codex version has no SessionStart hook, the entry is ignored; `sealkeep recover <session-file>` is the manual door."
+            _sealkeepNote: "Codex reviews non-managed hooks once. After trust, project memory and teammate updates are injected automatically; the background Sealkeep service encrypts queued sessions."
         };
     return {
-        hooks: { SessionEnd: entry(5), SessionStart: rehydrateEntry },
-        _vaultlineNote: "Merge the hooks object into ~/.claude/settings.json. The hook stores no secret; run `sealkeep queue run` with SEALKEEP_RECOVERY_PHRASE to encrypt queued sessions. SessionStart(resume) puts archived transcripts back before the resume reads them."
+        hooks: {
+            SessionEnd: entry(5),
+            SessionStart: contextStart,
+            UserPromptSubmit: contextPrompt,
+            PostToolUse: contextLive
+        },
+        _sealkeepNote: "After installation, project memory and teammate updates are injected automatically; the background Sealkeep service encrypts queued sessions. Reclaimed transcripts remain lightweight native pointers; restoring their full bytes is an explicit action."
     };
 }
 /**
@@ -333,9 +660,365 @@ async function hookFileText(path) {
         return null;
     }
 }
+/** Every command nested under an agent hook event, without assuming its grouping shape. */
+function commandsIn(value) {
+    if (!value || typeof value !== "object")
+        return [];
+    if (Array.isArray(value))
+        return value.flatMap(commandsIn);
+    const row = value;
+    return [...(typeof row.command === "string" ? [row.command] : []), ...Object.values(row).flatMap(commandsIn)];
+}
+function lifecycleIdentity(command) {
+    const match = /\bhook (enqueue|rehydrate|context|context-sync) --agent (codex|claude)\b/.exec(command);
+    return match ? `${match[1]}:${match[2]}` : null;
+}
+/** Read the one data-directory argument from an owned hook command. This is
+ * intentionally narrower than a shell parser: generated single-quoted values
+ * and historical double-quoted/unquoted values are understood, while missing
+ * or repeated routing is not ownership proof for an automatic rewrite. */
+function hookCommandDataDirs(command) {
+    const values = [];
+    const argument = /(?:^|\s)["']?--data-dir["']?(?:=|\s+)(?:'((?:[^']|'"'"')*)'|"((?:\\.|[^"\\])*)"|([^\s<]+))/gi;
+    for (const match of command.matchAll(argument)) {
+        if (match[1] !== undefined)
+            values.push(match[1].replaceAll(`'"'"'`, "'"));
+        else if (match[2] !== undefined) {
+            try {
+                const decoded = JSON.parse(`"${match[2]}"`);
+                values.push(typeof decoded === "string" ? decoded : match[2]);
+            }
+            catch {
+                values.push(match[2]);
+            }
+        }
+        else if (match[3] !== undefined)
+            values.push(match[3]);
+    }
+    return values;
+}
+function absoluteHookDataDir(value, home) {
+    const expanded = value === "~"
+        ? home
+        : value.startsWith("~/") || value.startsWith("~\\")
+            ? join(home, value.slice(2))
+            : value;
+    return expanded && !expanded.includes("\0") && isAbsolute(expanded) ? resolve(expanded) : null;
+}
+async function sameHookDataDir(left, right) {
+    const [canonicalLeft, canonicalRight] = await Promise.all([
+        realpath(left).catch(() => left),
+        realpath(right).catch(() => right),
+    ]);
+    return canonicalLeft === canonicalRight;
+}
+/** A daemon may refresh only its own prior hook routing. Presence of a generic
+ * Sealkeep marker is not consent for a different vault to take the hook over. */
+/**
+ * The single data directory this agent's owned lifecycle commands route to.
+ * Null when there are no owned commands, when any command carries zero or
+ * several `--data-dir` values, or when the commands disagree — the same
+ * strictness as ownership proof, because a rewrite decision hangs on it.
+ */
+function ownedHooksDataDir(contents, agent, home) {
+    let document;
+    try {
+        const parsed = JSON.parse(contents);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        document = parsed;
+    }
+    catch {
+        return null;
+    }
+    const commands = commandsIn(document.hooks)
+        .filter((command) => lifecycleIdentity(command)?.endsWith(`:${agent}`));
+    if (commands.length === 0)
+        return null;
+    let agreed = null;
+    for (const command of commands) {
+        const values = hookCommandDataDirs(command);
+        if (values.length !== 1)
+            return null;
+        const routed = absoluteHookDataDir(values[0], home);
+        if (!routed)
+            return null;
+        if (agreed === null)
+            agreed = routed;
+        else if (agreed !== routed)
+            return null;
+    }
+    return agreed;
+}
+/** A directory Sealkeep has initialized as a vault, as opposed to a path a hook merely names. */
+async function isInitializedVault(dataDir) {
+    return access(join(dataDir, "config.json")).then(() => true, () => false);
+}
+/**
+ * Whether a data directory is one this home would call its own: the
+ * environment-configured vault, or the default `~/.sealkeep` (and its legacy
+ * name). Anything else running a daemon — a test fixture, a drill vault — has
+ * no standing over the person's real agent hooks.
+ */
+async function isHomesOwnVault(dataDir, home) {
+    const configured = process.env.SEALKEEP_DATA_DIR ?? process.env.VAULTLINE_DATA_DIR;
+    const candidates = [configured, join(home, ".sealkeep"), join(home, ".vaultline")]
+        .filter((candidate) => typeof candidate === "string" && candidate.length > 0);
+    for (const candidate of candidates) {
+        if (resolve(candidate) === resolve(dataDir))
+            return true;
+        if (await sameHookDataDir(resolve(candidate), resolve(dataDir)).catch(() => false))
+            return true;
+    }
+    return false;
+}
+async function ownedHooksTargetDataDir(contents, agent, dataDir, home) {
+    let document;
+    try {
+        const parsed = JSON.parse(contents);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return false;
+        document = parsed;
+    }
+    catch {
+        return false;
+    }
+    const commands = commandsIn(document.hooks)
+        .filter((command) => lifecycleIdentity(command)?.endsWith(`:${agent}`));
+    const target = absoluteHookDataDir(dataDir, home);
+    if (!target || commands.length === 0)
+        return false;
+    const ownership = await Promise.all(commands.map(async (command) => {
+        const values = hookCommandDataDirs(command);
+        if (values.length !== 1)
+            return false;
+        const existing = absoluteHookDataDir(values[0], home);
+        return existing ? sameHookDataDir(existing, target) : false;
+    }));
+    return ownership.every(Boolean);
+}
+/** Remove only owned command handlers, retaining their group's custom siblings. */
+function withoutLifecycleCommands(value, identities) {
+    if (Array.isArray(value)) {
+        const kept = value.map((item) => withoutLifecycleCommands(item, identities)).filter((item) => item !== null);
+        return kept.length ? kept : null;
+    }
+    if (!value || typeof value !== "object")
+        return value;
+    const row = value;
+    if (typeof row.command === "string") {
+        const identity = lifecycleIdentity(row.command);
+        if (identity && identities.has(identity))
+            return null;
+    }
+    const next = { ...row };
+    if (Object.prototype.hasOwnProperty.call(row, "hooks")) {
+        const hooks = withoutLifecycleCommands(row.hooks, identities);
+        if (hooks === null)
+            return null;
+        next.hooks = hooks;
+    }
+    return next;
+}
+function lifecycleInstalled(agent, contents) {
+    if (!contents)
+        return false;
+    try {
+        const document = JSON.parse(contents);
+        const owned = commandsIn(document.hooks).filter((command) => lifecycleIdentity(command)?.endsWith(`:${agent}`));
+        if (owned.some((command) => !command.includes(`--lifecycle ${HOOK_LIFECYCLE_VERSION}`)))
+            return false;
+        const actionCount = (action) => owned.filter((command) => lifecycleIdentity(command) === `${action}:${agent}`).length;
+        if (actionCount("enqueue") !== (agent === "codex" ? 2 : 1)
+            || actionCount("rehydrate") !== 0
+            || actionCount("context") !== 2
+            || actionCount("context-sync") !== 3)
+            return false;
+        const eventHas = (event, action) => commandsIn(document.hooks?.[event]).some((command) => command.includes(`hook ${action} --agent ${agent}`)
+            && command.includes(`--lifecycle ${HOOK_LIFECYCLE_VERSION}`));
+        return eventHas("SessionEnd", "enqueue")
+            && eventHas("UserPromptSubmit", "context")
+            && eventHas("PostToolUse", "context")
+            && eventHas("SessionStart", "context-sync")
+            && eventHas("UserPromptSubmit", "context-sync")
+            && eventHas("PostToolUse", "context-sync")
+            && (agent !== "codex" || eventHas("PostCompact", "enqueue"));
+    }
+    catch {
+        return false;
+    }
+}
+/** Decode the two TOML string forms Codex writes around a hook-state key. */
+function tomlStateKey(value) {
+    const trimmed = value.trim();
+    if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        try {
+            return JSON.parse(trimmed);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (trimmed.startsWith("'") && trimmed.endsWith("'"))
+        return trimmed.slice(1, -1);
+    return null;
+}
+/**
+ * Read only Codex's persisted per-hook consent state.
+ *
+ * This deliberately is not a general TOML parser or writer. Codex owns this
+ * file; Sealkeep recognises the exact `[hooks.state."..."]` tables Codex
+ * itself writes and never mutates one. Unknown TOML remains untouched and is
+ * treated as no proof of trust, which is the safe direction for a status
+ * report.
+ */
+function codexHookStates(contents) {
+    const states = new Map();
+    if (!contents)
+        return states;
+    let current = null;
+    for (const line of contents.split(/\r?\n/)) {
+        const section = /^\s*\[hooks\.state\.(.+)\]\s*(?:#.*)?$/.exec(line);
+        if (section) {
+            current = tomlStateKey(section[1]);
+            if (current && !states.has(current))
+                states.set(current, {});
+            continue;
+        }
+        if (/^\s*\[/.test(line)) {
+            current = null;
+            continue;
+        }
+        if (!current)
+            continue;
+        const enabled = /^\s*enabled\s*=\s*(true|false)\s*(?:#.*)?$/.exec(line);
+        if (enabled) {
+            states.get(current).enabled = enabled[1] === "true";
+            continue;
+        }
+        const trusted = /^\s*trusted_hash\s*=\s*("(?:\\.|[^"\\])*"|'[^']*')\s*(?:#.*)?$/.exec(line);
+        if (trusted) {
+            const value = tomlStateKey(trusted[1]);
+            if (value !== null)
+                states.get(current).trustedHash = value;
+        }
+    }
+    return states;
+}
+function hookEventKey(event) {
+    return event.replace(/([a-z0-9])([A-Z])/g, "$1_$2").toLowerCase();
+}
+function canonicalJson(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalJson);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.keys(value).sort()
+        .map((key) => [key, canonicalJson(value[key])]));
+}
+/**
+ * Codex trusts a normalized hook identity, not the source JSON bytes. This is
+ * the same identity documented by Codex's open-source hook discovery code:
+ * event + matcher group + one normalized handler, recursively key-sorted and
+ * SHA-256 hashed. Keeping this exact lets us distinguish trusted from merely
+ * present without asking Codex to execute anything or writing its consent.
+ */
+function codexHookHash(event, group, handler) {
+    const sessionEndTimeout = event === "SessionEnd" || event === "Interrupt";
+    const rawTimeout = typeof handler.timeout === "number" ? handler.timeout : (sessionEndTimeout ? 1 : 600);
+    const normalized = {
+        type: "command",
+        command: process.platform === "win32" && typeof handler.commandWindows === "string"
+            ? handler.commandWindows
+            : handler.command,
+        timeout: sessionEndTimeout ? Math.min(3, Math.max(1, rawTimeout)) : Math.max(1, rawTimeout),
+        async: handler.async === true,
+    };
+    if (typeof handler.statusMessage === "string")
+        normalized.statusMessage = handler.statusMessage;
+    const contextEvents = new Set(["PreToolUse", "PostToolUse", "SessionStart", "UserPromptSubmit", "SubagentStart"]);
+    if (contextEvents.has(event) && typeof handler.additionalContextLimit === "number" && handler.additionalContextLimit !== 2500) {
+        normalized.additionalContextLimit = handler.additionalContextLimit;
+    }
+    const identity = { event_name: hookEventKey(event), hooks: [normalized] };
+    const matcherEvents = new Set(["PreToolUse", "PermissionRequest", "PostToolUse", "PreCompact", "PostCompact", "SessionStart", "SessionEnd", "SubagentStart", "SubagentStop"]);
+    if (matcherEvents.has(event) && typeof group.matcher === "string")
+        identity.matcher = group.matcher;
+    return `sha256:${createHash("sha256").update(JSON.stringify(canonicalJson(identity))).digest("hex")}`;
+}
+/** The exact current Sealkeep handlers Codex will gate through `/hooks`. */
+function codexLifecycleIssues(hookFile, hookContents, configContents) {
+    if (!hookContents)
+        return [];
+    let document;
+    try {
+        document = JSON.parse(hookContents);
+    }
+    catch {
+        return [];
+    }
+    const states = codexHookStates(configContents);
+    const issues = [];
+    for (const [event, value] of Object.entries(document.hooks ?? {})) {
+        if (!Array.isArray(value))
+            continue;
+        for (const [groupIndex, rawGroup] of value.entries()) {
+            if (!rawGroup || typeof rawGroup !== "object" || Array.isArray(rawGroup))
+                continue;
+            const group = rawGroup;
+            const handlers = Array.isArray(group.hooks) ? group.hooks : [];
+            for (const [handlerIndex, rawHandler] of handlers.entries()) {
+                if (!rawHandler || typeof rawHandler !== "object" || Array.isArray(rawHandler))
+                    continue;
+                const handler = rawHandler;
+                if (handler.type !== "command" || typeof handler.command !== "string")
+                    continue;
+                const identity = lifecycleIdentity(handler.command);
+                if (!identity?.endsWith(":codex"))
+                    continue;
+                const action = identity.slice(0, identity.indexOf(":"));
+                const key = `${hookFile}:${hookEventKey(event)}:${groupIndex}:${handlerIndex}`;
+                const state = states.get(key);
+                const currentHash = codexHookHash(event, group, handler);
+                const reason = state?.enabled === false
+                    ? "disabled"
+                    : !state?.trustedHash
+                        ? "untrusted"
+                        : state.trustedHash !== currentHash
+                            ? "modified"
+                            : null;
+                if (reason)
+                    issues.push({ event, action, reason });
+            }
+        }
+    }
+    return issues;
+}
+function hookIssueNote(issues) {
+    if (issues.length === 0)
+        return null;
+    const named = (items) => [...new Set(items.map((issue) => issue.event))].join(", ");
+    const disabled = issues.filter((issue) => issue.reason === "disabled");
+    if (disabled.length > 0) {
+        const review = issues.filter((issue) => issue.reason !== "disabled");
+        const also = review.length > 0
+            ? ` Codex is also withholding ${named(review)} until ${review.some((issue) => issue.reason === "modified") ? "the changed definitions are reviewed again" : "their one-time review"}.`
+            : "";
+        return `Codex has disabled Sealkeep's ${named(disabled)} hook${disabled.length === 1 ? "" : "s"}.${also} The background watcher still preserves session files automatically. Open /hooks in Codex to review or re-enable these lifecycle actions; Sealkeep will not change your choice.`;
+    }
+    const changed = issues.filter((issue) => issue.reason === "modified");
+    const label = changed.length > 0 ? "changed and needs another review" : "is waiting for its one-time review";
+    return `Sealkeep's Codex lifecycle ${label} (${named(issues)}). Until it is trusted in Codex /hooks, the background watcher still preserves session files, but these recall and live-context triggers do not run.`;
+}
 function statusFor(detection) {
     if (!detection.detected)
         return { status: "not-installed", note: `No ${detection.root} on this machine.` };
+    if (detection.hooksInstalled && detection.hookIssues.some((issue) => issue.reason === "disabled")) {
+        return { status: "hooked-but-disabled", note: hookIssueNote(detection.hookIssues) };
+    }
+    if (detection.hooksInstalled && !detection.hooksActive) {
+        return { status: "hooked-awaiting-review", note: hookIssueNote(detection.hookIssues) };
+    }
     if (detection.hooksInstalled)
         return { status: "hooked", note: null };
     if (!detection.hookFileWritable)
@@ -361,8 +1044,9 @@ function statusFor(detection) {
  * Unlike `detectAgents`, which answers the archiving question and so lists only
  * the agents with a session adapter, this answers the setup question: what is
  * here, where its hooks live, whether ours are already among them, and whether
- * we could write there at all. It reads no transcript and no config value —
- * only whether one string appears in a config file.
+ * we could write there at all. For Codex it also reads the non-secret hook
+ * consent state that Codex itself persists, so a present-but-disabled command
+ * is never presented as active automation.
  */
 /** Total size and count of one agent's transcripts. Reads sizes, never contents. */
 async function measureSessions(roots) {
@@ -371,12 +1055,15 @@ async function measureSessions(roots) {
         await walkJsonl(root, "codex", found);
     return { sessionBytes: found.reduce((total, item) => total + item.bytes, 0), sessionCount: found.length };
 }
-export async function detectSetupAgents(home = process.env.HOME ?? ".") {
+export async function detectSetupAgents(home = process.env.HOME ?? ".", dataDir) {
     return Promise.all(SETUP_AGENT_IDS.map(async (agent) => {
         const definition = AGENTS[agent];
         const root = definition.root(home);
         const hookFile = definition.hookFile(home);
-        const [detected, contents, writable] = await Promise.all([directoryExists(root), hookFileText(hookFile), hookFileWritable(hookFile)]);
+        const [detected, contents, writable, codexConfig] = await Promise.all([
+            directoryExists(root), hookFileText(hookFile), hookFileWritable(hookFile),
+            agent === "codex" ? hookFileText(join(home, ".codex", "config.toml")) : Promise.resolve(null)
+        ]);
         // What this agent is costing in disk right now. It is the reason anyone
         // installs Sealkeep, and until it is on screen the problem is invisible —
         // sessions accumulate in a directory nobody opens. Metadata only, one stat
@@ -385,12 +1072,31 @@ export async function detectSetupAgents(home = process.env.HOME ?? ".") {
         const sessions = detected && definition.archivable
             ? await measureSessions(definition.transcriptRoots(home))
             : { sessionBytes: 0, sessionCount: 0 };
+        const hooksInstalled = isArchivingAgent(agent) && lifecycleInstalled(agent, contents);
+        const hookIssues = hooksInstalled && agent === "codex"
+            ? codexLifecycleIssues(hookFile, contents, codexConfig)
+            : [];
+        // Presence is not routing. A complete lifecycle that feeds some other data
+        // directory looks installed and active while doing nothing for this vault,
+        // so the comparison is made explicitly — but only against a directory the
+        // caller actually asked about; with none there is nothing to be wrong about.
+        const hooksDataDir = contents && isArchivingAgent(agent) ? ownedHooksDataDir(contents, agent, home) : null;
+        const hooksAimedElsewhere = hooksInstalled && dataDir !== undefined && contents !== null
+            && !(await ownedHooksTargetDataDir(contents, agent, dataDir, home));
         const base = {
             agent, label: definition.label, detected, root, hookFile,
             hookFileFormat: definition.hookFileFormat,
             hookFileExists: contents !== null,
             hookFileWritable: writable,
-            hooksInstalled: contents !== null && contents.includes(hookMarker(agent)),
+            // "Installed" means this build's complete lifecycle, not merely the
+            // archive hook an older Sealkeep left behind. Otherwise existing users
+            // would be reported hooked and never receive automatic recall/team
+            // context on upgrade.
+            hooksInstalled,
+            hooksActive: hooksInstalled && hookIssues.length === 0,
+            hooksDataDir,
+            hooksAimedElsewhere,
+            hookIssues,
             archivable: definition.archivable,
             ...sessions
         };
@@ -399,7 +1105,7 @@ export async function detectSetupAgents(home = process.env.HOME ?? ".") {
 }
 /** Written beside the original before Sealkeep edits another program's config, so a bad merge is always undoable. */
 async function backupHookFile(path, contents) {
-    const backup = `${path}.vaultline-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    const backup = `${path}.sealkeep-backup-${new Date().toISOString().replace(/[:.]/g, "-")}`;
     await writeFile(backup, contents, { mode: 0o600 });
     return backup;
 }
@@ -419,7 +1125,14 @@ function mergeHooks(existing, ours) {
         if (!entries)
             continue;
         const current = Array.isArray(base[event]) ? [...base[event]] : [];
-        base[event] = [...current, ...entries];
+        const identities = new Set(commandsIn(entries).map(lifecycleIdentity).filter((identity) => identity !== null));
+        const preserved = identities.size
+            ? current.map((entry) => withoutLifecycleCommands(entry, identities)).filter((entry) => entry !== null)
+            : current;
+        // Re-append the current generated entries. Besides preventing duplicates,
+        // this reconciles changed timeout/matcher/async fields from an older
+        // lifecycle instead of treating a matching command string as current.
+        base[event] = [...preserved, ...entries];
     }
     return base;
 }
@@ -440,14 +1153,29 @@ async function writeJsonAtomic(path, value) {
  */
 export async function installAgentHooks(agents, options) {
     const home = options.home ?? process.env.HOME ?? ".";
-    const executable = options.executable ?? "vaultline";
-    const detections = new Map((await detectSetupAgents(home)).map((detection) => [detection.agent, detection]));
+    const executable = options.executable ?? "sealkeep";
+    const detections = new Map((await detectSetupAgents(home, options.dataDir)).map((detection) => [detection.agent, detection]));
     const outcomes = [];
     for (const agent of agents) {
         const detection = detections.get(agent);
-        const base = { agent, hookFile: detection.hookFile, installed: false, alreadyInstalled: false, backupPath: null, fragmentPath: null, reason: null };
-        if (detection.status === "hooked") {
-            outcomes.push({ ...base, installed: true, alreadyInstalled: true });
+        const base = {
+            agent, hookFile: detection.hookFile, installed: false,
+            alreadyInstalled: false, active: false, backupPath: null,
+            fragmentPath: null, reason: null, attention: null
+        };
+        // Presence and execution are deliberately separate. In particular, never
+        // overwrite Codex's `enabled = false` choice just because every Sealkeep
+        // command is present; report the required /hooks action and leave consent
+        // entirely with Codex and its user.
+        // A complete lifecycle routed to a different vault is not "already
+        // installed" for this one: it is the silent no-op an explicit install is
+        // asked to fix. It falls through to the reconcile below, which replaces the
+        // owned commands as one unit (never duplicating them) after a backup.
+        if (detection.hooksInstalled && !detection.hooksAimedElsewhere) {
+            outcomes.push({
+                ...base, installed: true, alreadyInstalled: true,
+                active: detection.hooksActive, attention: detection.note
+            });
             continue;
         }
         if (detection.status === "not-installed" || detection.status === "found-but-unwritable" || detection.status === "found-but-unsupported") {
@@ -483,10 +1211,127 @@ export async function installAgentHooks(agents, options) {
             }
         }
         const document = parsed && typeof parsed === "object" && !Array.isArray(parsed) ? { ...parsed } : {};
-        document.hooks = mergeHooks(document.hooks, hookConfig(agent, executable, options.dataDir).hooks);
+        // Reconcile the lifecycle as one owned unit. A version can move an action
+        // between events (v2 removed the blocking SessionStart context reader), so
+        // per-event replacement would strand old commands in an event that no
+        // longer has a same-named successor.
+        const identities = new Set([`enqueue:${agent}`, `rehydrate:${agent}`, `context:${agent}`, `context-sync:${agent}`]);
+        const existing = document.hooks && typeof document.hooks === "object" && !Array.isArray(document.hooks)
+            ? { ...document.hooks }
+            : {};
+        for (const [event, entries] of Object.entries(existing)) {
+            const kept = withoutLifecycleCommands(entries, identities);
+            if (kept === null)
+                delete existing[event];
+            else
+                existing[event] = kept;
+        }
+        document.hooks = mergeHooks(existing, hookConfig(agent, executable, options.dataDir).hooks);
         const backupPath = raw && raw.trim() ? await backupHookFile(detection.hookFile, raw) : null;
         await writeJsonAtomic(detection.hookFile, document);
-        outcomes.push({ ...base, installed: true, backupPath });
+        // A newly written Codex hook is intentionally pending its one-time review.
+        // Read the resulting state rather than claiming that writing implies
+        // execution. Claude's local hook file has no equivalent trust gate.
+        const issues = agent === "codex"
+            ? codexLifecycleIssues(detection.hookFile, JSON.stringify(document), await hookFileText(join(home, ".codex", "config.toml")))
+            : [];
+        outcomes.push({
+            ...base, installed: true, active: issues.length === 0,
+            attention: hookIssueNote(issues), backupPath
+        });
+    }
+    return outcomes;
+}
+/**
+ * Upgrades only hook files that already contain a Sealkeep archive hook.
+ *
+ * This is the package-upgrade path: an earlier explicit install is continuing
+ * to consent to Sealkeep-owned lifecycle entries, but a machine that never
+ * installed them is left completely untouched. The daemon calls this once at
+ * startup, so upgrading the package does not require revisiting setup.
+ */
+export async function upgradeOwnedAgentHooks(options) {
+    const home = options.home ?? process.env.HOME ?? ".";
+    // A daemon whose vault is not this home's own vault — a test fixture, a drill,
+    // a rehearsal — has no standing to rewrite the person's real agent hooks,
+    // whatever it finds there. Only an explicitly provided home opts in; that is
+    // how an isolated harness says "these hooks are mine to manage". Without this,
+    // every test that started a daemon re-pointed the developer's real hooks at a
+    // temporary vault, and the fail-open hook contract hid it completely.
+    if (options.home === undefined && !(await isHomesOwnVault(options.dataDir, home)))
+        return [];
+    const detections = await detectSetupAgents(home, options.dataDir);
+    const owned = [];
+    for (const detection of detections) {
+        if (!isArchivingAgent(detection.agent))
+            continue;
+        if (detection.hooksInstalled) {
+            // Complete and routed here: nothing to do. Complete but routed to a vault
+            // that does not exist any more (a deleted fixture, a moved directory): the
+            // hook is orphaned, injects and captures nothing, and nothing else will
+            // ever say so — re-target it to the daemon that is actually running.
+            // Complete but routed to another LIVE vault: that may be deliberate, so
+            // doctor reports it and the person decides.
+            if (detection.hooksAimedElsewhere && detection.hooksDataDir && !(await isInitializedVault(detection.hooksDataDir))) {
+                owned.push(detection.agent);
+            }
+            continue;
+        }
+        const contents = await hookFileText(detection.hookFile);
+        if (contents && await ownedHooksTargetDataDir(contents, detection.agent, options.dataDir, home)) {
+            owned.push(detection.agent);
+        }
+    }
+    return owned.length ? installAgentHooks(owned, options) : [];
+}
+/**
+ * Removes Sealkeep-owned lifecycle handlers and nothing else.
+ *
+ * This is intentionally structural rather than a text replacement: if a user
+ * placed their own handler beside Sealkeep's in one matcher group, their
+ * handler and matcher survive. The original file is backed up before a write.
+ */
+export async function removeOwnedAgentHooks(options) {
+    const home = options.home ?? process.env.HOME ?? ".";
+    const outcomes = [];
+    for (const agent of ARCHIVING_AGENT_IDS) {
+        const path = AGENTS[agent].hookFile(home);
+        const raw = await hookFileText(path);
+        const base = { agent, hookFile: path, removed: false, backupPath: null, reason: null };
+        if (!raw) {
+            outcomes.push(base);
+            continue;
+        }
+        let document;
+        try {
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                throw new Error("not an object");
+            document = { ...parsed };
+        }
+        catch {
+            outcomes.push({ ...base, reason: `${path} is not valid JSON, so Sealkeep will not rewrite it.` });
+            continue;
+        }
+        if (!commandsIn(document).some((command) => lifecycleIdentity(command)?.endsWith(`:${agent}`))) {
+            outcomes.push(base);
+            continue;
+        }
+        const identities = new Set([`enqueue:${agent}`, `rehydrate:${agent}`, `context:${agent}`, `context-sync:${agent}`]);
+        const hooks = document.hooks && typeof document.hooks === "object" && !Array.isArray(document.hooks)
+            ? { ...document.hooks }
+            : {};
+        for (const [event, entries] of Object.entries(hooks)) {
+            const kept = withoutLifecycleCommands(entries, identities);
+            if (kept === null)
+                delete hooks[event];
+            else
+                hooks[event] = kept;
+        }
+        document.hooks = hooks;
+        const backupPath = await backupHookFile(path, raw);
+        await writeJsonAtomic(path, document);
+        outcomes.push({ ...base, removed: true, backupPath });
     }
     return outcomes;
 }
@@ -501,6 +1346,18 @@ function firstString(payload, keys) {
     }
     return undefined;
 }
+/** The lifecycle event a hook payload names; undefined when it names none or is not JSON. */
+export function hookEventNameOf(stdin) {
+    try {
+        const payload = JSON.parse(stdin);
+        if (!payload || typeof payload !== "object" || Array.isArray(payload))
+            return undefined;
+        return firstString(payload, EVENT_KEYS);
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Accepts Codex `SessionEnd`/`PostCompact` and Claude `SessionEnd` payloads. Unknown
  * vendor fields are ignored rather than parsed, so a schema change cannot break preservation.
@@ -531,3 +1388,34 @@ export async function hookEventFromStdin(agent, stdin) {
 export async function transcriptPathFromHook(stdin, agent = "codex") {
     return (await hookEventFromStdin(agent, stdin)).sourcePath;
 }
+/**
+ * The project an archive belongs to: what the seal recorded, or failing that
+ * what its path implies.
+ *
+ * Deriving it from the path is guesswork that only works inside an agent's own
+ * directories — a rehearsal of a company setup archived six sessions into a
+ * shared project and every one of them came back "no project", so membership
+ * could never bind and `rewrap --project` re-keyed nothing while reporting
+ * that the archives "belong to another project". Records written since carry
+ * the answer; older ones still fall back to the path.
+ */
+export async function projectIdentityOfRecord(record) {
+    if (record.source.projectKey) {
+        return { project: record.source.project ?? null, projectKey: record.source.projectKey, projectPath: null };
+    }
+    try {
+        const derived = record.source.agent === "claude"
+            ? await claudeProjectFromTranscript(record.source.path, record.createdAt)
+            : record.source.agent === "codex"
+                ? await codexProjectFromRollout(record.source.path, record.createdAt)
+                : null;
+        if (derived)
+            return { ...derived, project: record.source.project ?? derived.project };
+    }
+    catch { /* an unreadable project is not evidence of anything */ }
+    return { project: record.source.project ?? null, projectKey: null, projectPath: null };
+}
+/** Backward-compatible display-label helper. Access-control callers use projectIdentityOfRecord. */
+export async function projectOfRecord(record) {
+    return (await projectIdentityOfRecord(record)).project;
+}