clinkx 1.0.0 → 1.1.0

package/dist/activity-journal.js

@@ -1,50 +1,171 @@
 import { createHash, randomUUID } from "node:crypto";
-import { chmod, mkdir, open, readFile, readdir, rename, rm, stat, } from "node:fs/promises";
-import { join } from "node:path";
-import { ACTIVITY_RESULT_FILENAME, ACTIVITY_STATE_FILENAME, ActivityIdSchema, ActivityStateV1Schema, DEFAULT_ACTIVITY_HEARTBEAT_INTERVAL_MS, DEFAULT_ACTIVITY_MAX_AGE_MS, DEFAULT_MAX_ACTIVITY_ENTRIES, DEFAULT_MAX_ACTIVITY_RESULT_BYTES, DEFAULT_MAX_ACTIVITY_TOTAL_BYTES, MAX_ACTIVITY_STATE_BYTES, } from "../clinkx-workflows/dist/dashboard/activity-contract.js";
+import { constants as fsConstants } from "node:fs";
+import { chmod, lstat, mkdir, open, readFile, readdir, rename, rm, stat, } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { ACTIVITY_RESULT_FILENAME, ACTIVITY_STATE_FILENAME, ActivityIdSchema, ActivityStateReadSchema, ActivityStateV1Schema, ActivityStateV2Schema, ActivityStateV3Schema, DEFAULT_ACTIVITY_HEARTBEAT_INTERVAL_MS, DEFAULT_ACTIVITY_MAX_AGE_MS, DEFAULT_MAX_ACTIVITY_ENTRIES, DEFAULT_MAX_ACTIVITY_RESULT_BYTES, DEFAULT_MAX_ACTIVITY_TOTAL_BYTES, MAX_ACTIVITY_STATE_BYTES, } from "../clinkx-workflows/dist/dashboard/activity-contract.js";
 import { createDashboardActivityReader } from "../clinkx-workflows/dist/dashboard/activity-reader.js";
+import { deriveActivityGeneration } from "../clinkx-workflows/dist/dashboard/generation.js";
 import { removeSessionLogGeneration } from "../clinkx-workflows/dist/dashboard/session-log-retention.js";
 import { createSessionLogGeneration, readSessionLogGeneration, } from "../clinkx-workflows/dist/dashboard/session-log-identity.js";
+import { invocationAuditV2PersistenceEnabled, observedInvocationPersistenceEnabled, } from "../clinkx-workflows/dist/config.js";
+import { resolveOpenedDescriptorPath } from "../clinkx-workflows/dist/contained-file.js";
 import { logger } from "./logger.js";
-export { ACTIVITY_RESULT_FILENAME, ACTIVITY_STATE_FILENAME, ActivityIdSchema, ActivityKindSchema, ActivityOutcomeKindSchema, ActivityPhaseSchema, ActivityResultReferenceSchema, ActivityStateV1Schema, ActivityTerminalStatusSchema, DEFAULT_ACTIVITY_HEARTBEAT_INTERVAL_MS, DEFAULT_ACTIVITY_MAX_AGE_MS, DEFAULT_MAX_ACTIVITY_ENTRIES, DEFAULT_MAX_ACTIVITY_RESULT_BYTES, DEFAULT_MAX_ACTIVITY_TOTAL_BYTES, MAX_ACTIVITY_STATE_BYTES, } from "../clinkx-workflows/dist/dashboard/activity-contract.js";
+export { ACTIVITY_RESULT_FILENAME, ACTIVITY_STATE_FILENAME, ActivityIdSchema, ActivityKindSchema, ActivityOutcomeKindSchema, ActivityPhaseSchema, ActivityResultReferenceSchema, ActivityStateReadSchema, ActivityStateV1Schema, ActivityStateV2Schema, ActivityStateV3Schema, ActivityTerminalStatusSchema, DEFAULT_ACTIVITY_HEARTBEAT_INTERVAL_MS, DEFAULT_ACTIVITY_MAX_AGE_MS, DEFAULT_MAX_ACTIVITY_ENTRIES, DEFAULT_MAX_ACTIVITY_RESULT_BYTES, DEFAULT_MAX_ACTIVITY_TOTAL_BYTES, MAX_ACTIVITY_STATE_BYTES, } from "../clinkx-workflows/dist/dashboard/activity-contract.js";
 export const ACTIVITY_RETAIN_RESULT_ENV = "CLINKX_DASHBOARD_ACTIVITY_RETAIN_RESULT";
 const SESSION_LOG_GENERATION_FILE_BYTES = 44;
 const NOOP_OBSERVATION = Object.freeze({
     async transition() { },
+    async observe() { },
     async complete() { },
 });
-async function writeFileAtomic(filePath, content) {
-    const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
-    const handle = await open(temporaryPath, "wx", 0o600);
+class UnsafeActivityDirectoryError extends Error {
+}
+async function inspectActivityDirectory(activityDir, activityId) {
+    let linked;
+    try {
+        linked = await lstat(activityDir);
+    }
+    catch (error) {
+        if (isFileSystemError(error, "ENOENT"))
+            return undefined;
+        throw error;
+    }
+    if (linked.isSymbolicLink() || !linked.isDirectory()) {
+        throw new UnsafeActivityDirectoryError();
+    }
+    let handle;
     try {
-        await handle.writeFile(content);
-        await handle.sync();
-        await handle.close();
-        await rename(temporaryPath, filePath);
-        await chmod(filePath, 0o600);
+        handle = await open(activityDir, fsConstants.O_RDONLY |
+            (fsConstants.O_DIRECTORY ?? 0) |
+            (fsConstants.O_NOFOLLOW ?? 0));
+    }
+    catch {
+        throw new UnsafeActivityDirectoryError();
+    }
+    try {
+        const opened = await handle.stat({ bigint: true });
+        const canonicalPath = await resolveOpenedDescriptorPath(handle.fd, activityDir);
+        if (!opened.isDirectory() ||
+            opened.nlink === 0n ||
+            BigInt(linked.dev) !== opened.dev ||
+            BigInt(linked.ino) !== opened.ino ||
+            canonicalPath === undefined) {
+            throw new UnsafeActivityDirectoryError();
+        }
+        return {
+            activityId,
+            path: canonicalPath,
+            handle,
+            identity: { dev: opened.dev, ino: opened.ino },
+            localGeneration: deriveActivityGeneration(activityId, linked),
+        };
     }
     catch (error) {
         await handle.close().catch(() => undefined);
-        await rm(temporaryPath, { force: true }).catch(() => undefined);
         throw error;
     }
 }
+async function verifyActivityDirectory(path, admitted) {
+    const linked = await lstat(path).catch(() => undefined);
+    const opened = await admitted.handle.stat({ bigint: true }).catch(() => undefined);
+    if (linked === undefined ||
+        opened === undefined ||
+        linked.isSymbolicLink() ||
+        !linked.isDirectory() ||
+        !opened.isDirectory() ||
+        opened.nlink === 0n ||
+        BigInt(linked.dev) !== admitted.identity.dev ||
+        BigInt(linked.ino) !== admitted.identity.ino ||
+        opened.dev !== admitted.identity.dev ||
+        opened.ino !== admitted.identity.ino ||
+        deriveActivityGeneration(admitted.activityId, linked) !==
+            admitted.localGeneration ||
+        await resolveOpenedDescriptorPath(admitted.handle.fd, path) !== path) {
+        throw new UnsafeActivityDirectoryError();
+    }
+}
+function captureActivityDirectoryIncarnation(admitted) {
+    return Object.freeze({
+        activityId: admitted.activityId,
+        path: admitted.path,
+        identity: admitted.identity,
+        localGeneration: admitted.localGeneration,
+    });
+}
+async function reopenActivityDirectory(incarnation) {
+    const admitted = await inspectActivityDirectory(incarnation.path, incarnation.activityId);
+    if (admitted === undefined)
+        return undefined;
+    if (admitted.path !== incarnation.path ||
+        admitted.identity.dev !== incarnation.identity.dev ||
+        admitted.identity.ino !== incarnation.identity.ino ||
+        admitted.localGeneration !== incarnation.localGeneration) {
+        await admitted.handle.close().catch(() => undefined);
+        throw new UnsafeActivityDirectoryError();
+    }
+    return admitted;
+}
+async function writeActivityFileAtomic(directory, filename, content) {
+    const admitted = await reopenActivityDirectory(directory);
+    if (admitted === undefined)
+        throw new UnsafeActivityDirectoryError();
+    try {
+        const filePath = join(admitted.path, filename);
+        const temporaryPath = `${filePath}.${randomUUID()}.tmp`;
+        const handle = await open(temporaryPath, "wx", 0o600);
+        try {
+            await verifyActivityDirectory(admitted.path, admitted);
+            await handle.writeFile(content);
+            await handle.sync();
+            await handle.chmod(0o600);
+            // Bind the commit, not merely the temp creation, to the short-lived
+            // descriptor re-admitted for this exact incarnation.
+            await verifyActivityDirectory(admitted.path, admitted);
+            await rename(temporaryPath, filePath);
+        }
+        catch (error) {
+            await rm(temporaryPath, { force: true }).catch(() => undefined);
+            throw error;
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+        }
+    }
+    finally {
+        await admitted.handle.close().catch(() => undefined);
+    }
+}
+function isFileSystemError(error, code) {
+    return typeof error === "object" && error !== null &&
+        "code" in error && error.code === code;
+}
 function serializedState(state) {
-    const serialized = `${JSON.stringify(ActivityStateV1Schema.parse(state), null, 2)}\n`;
+    const parsed = state.schemaVersion === "clinkx-dashboard-activity-v3"
+        ? ActivityStateV3Schema.parse(state)
+        : state.schemaVersion === "clinkx-dashboard-activity-v2"
+            ? ActivityStateV2Schema.parse(state)
+            : ActivityStateV1Schema.parse(state);
+    const serialized = `${JSON.stringify(parsed, null, 2)}\n`;
     if (Buffer.byteLength(serialized, "utf8") > MAX_ACTIVITY_STATE_BYTES) {
         throw new Error("activity state exceeds the producer byte cap");
     }
     return serialized;
 }
-async function pruneActivities(rootDir, sessionLogRootDir, activityIdentityReader, now, maxAgeMs, maxEntries, maxTotalBytes, reservedBytes) {
+async function pruneActivities(rootDir, sessionLogRootDir, now, maxAgeMs, maxEntries, maxTotalBytes, reservedBytes, testHooks) {
     const entries = await readdir(rootDir, { withFileTypes: true });
     await Promise.all(entries.map(async (entry) => {
         if (!entry.isDirectory() || !ActivityIdSchema.safeParse(entry.name).success) {
             return;
         }
         const activityDir = join(rootDir, entry.name);
+        let admitted;
         try {
-            const parsed = ActivityStateV1Schema.safeParse(JSON.parse(await readFile(join(activityDir, ACTIVITY_STATE_FILENAME), "utf8")));
+            admitted = await inspectActivityDirectory(activityDir, entry.name);
+            if (admitted === undefined)
+                return;
+            const incarnation = captureActivityDirectoryIncarnation(admitted);
+            const parsed = ActivityStateReadSchema.safeParse(JSON.parse(await readFile(join(admitted.path, ACTIVITY_STATE_FILENAME), "utf8")));
+            await verifyActivityDirectory(admitted.path, admitted);
             if (!parsed.success ||
                 parsed.data.phase !== "terminal" ||
                 parsed.data.completedAt === undefined) {
@@ -52,11 +173,10 @@ async function pruneActivities(rootDir, sessionLogRootDir, activityIdentityReade
             }
             if (now.getTime() - Date.parse(parsed.data.completedAt) > maxAgeMs) {
                 await pruneActivityDirectory({
-                    rootDir,
                     sessionLogRootDir,
                     activityId: entry.name,
-                    activityDir,
-                    activityIdentityReader,
+                    incarnation,
+                    testHooks,
                 });
             }
         }
@@ -68,6 +188,9 @@ async function pruneActivities(rootDir, sessionLogRootDir, activityIdentityReade
                 }, "activity journal could not inspect a retention candidate");
             }
         }
+        finally {
+            await admitted?.handle.close().catch(() => undefined);
+        }
     }));
     const survivors = await readdir(rootDir, { withFileTypes: true });
     const terminal = [];
@@ -76,35 +199,69 @@ async function pruneActivities(rootDir, sessionLogRootDir, activityIdentityReade
         if (!entry.isDirectory())
             continue;
         const activityDir = join(rootDir, entry.name);
+        let admitted;
         let activityBytes = 0;
+        let bytesBoundToIncarnation = false;
+        if (!ActivityIdSchema.safeParse(entry.name).success) {
+            try {
+                for (const child of await readdir(activityDir, { withFileTypes: true })) {
+                    if (!child.isFile())
+                        continue;
+                    activityBytes += (await stat(join(activityDir, child.name))).size;
+                }
+            }
+            catch {
+                // An unreadable non-activity directory still occupies entry capacity.
+            }
+            totalBytes += activityBytes;
+            continue;
+        }
         try {
-            for (const child of await readdir(activityDir, { withFileTypes: true })) {
+            admitted = await inspectActivityDirectory(activityDir, entry.name);
+            if (admitted === undefined)
+                continue;
+            const incarnation = captureActivityDirectoryIncarnation(admitted);
+            for (const child of await readdir(admitted.path, { withFileTypes: true })) {
                 if (!child.isFile())
                     continue;
-                activityBytes += (await stat(join(activityDir, child.name))).size;
+                activityBytes += (await stat(join(admitted.path, child.name))).size;
             }
-        }
-        catch {
-            // A concurrent terminal update is reconciled at the next admission.
-        }
-        totalBytes += activityBytes;
-        if (!ActivityIdSchema.safeParse(entry.name).success)
-            continue;
-        try {
-            const parsed = ActivityStateV1Schema.safeParse(JSON.parse(await readFile(join(activityDir, ACTIVITY_STATE_FILENAME), "utf8")));
+            await verifyActivityDirectory(admitted.path, admitted);
+            totalBytes += activityBytes;
+            bytesBoundToIncarnation = true;
+            const parsed = ActivityStateReadSchema.safeParse(JSON.parse(await readFile(join(admitted.path, ACTIVITY_STATE_FILENAME), "utf8")));
+            await verifyActivityDirectory(admitted.path, admitted);
             if (parsed.success &&
                 parsed.data.phase === "terminal" &&
                 parsed.data.completedAt !== undefined) {
                 terminal.push({
                     activityId: entry.name,
-                    path: activityDir,
                     completedAtMs: Date.parse(parsed.data.completedAt),
                     bytes: activityBytes,
+                    incarnation,
                 });
             }
         }
         catch {
-            // Unreadable entries are not producer-owned retention candidates.
+            // Unreadable entries are not producer-owned retention candidates. If
+            // identity churn prevented a bound scan, account the current path only.
+            if (!bytesBoundToIncarnation) {
+                activityBytes = 0;
+                try {
+                    for (const child of await readdir(activityDir, { withFileTypes: true })) {
+                        if (!child.isFile())
+                            continue;
+                        activityBytes += (await stat(join(activityDir, child.name))).size;
+                    }
+                }
+                catch {
+                    // Entry capacity still prevents unsafe admission at the count cap.
+                }
+                totalBytes += activityBytes;
+            }
+        }
+        finally {
+            await admitted?.handle.close().catch(() => undefined);
         }
     }
     terminal.sort((left, right) => left.completedAtMs - right.completedAtMs);
@@ -112,11 +269,10 @@ async function pruneActivities(rootDir, sessionLogRootDir, activityIdentityReade
     while (entryCount >= maxEntries && terminal.length > 0) {
         const victim = terminal.shift();
         if (await pruneActivityDirectory({
-            rootDir,
             sessionLogRootDir,
             activityId: victim.activityId,
-            activityDir: victim.path,
-            activityIdentityReader,
+            incarnation: victim.incarnation,
+            testHooks,
         })) {
             entryCount -= 1;
             totalBytes -= victim.bytes;
@@ -126,34 +282,99 @@ async function pruneActivities(rootDir, sessionLogRootDir, activityIdentityReade
         terminal.length > 0) {
         const victim = terminal.shift();
         if (await pruneActivityDirectory({
-            rootDir,
             sessionLogRootDir,
             activityId: victim.activityId,
-            activityDir: victim.path,
-            activityIdentityReader,
+            incarnation: victim.incarnation,
+            testHooks,
         })) {
             entryCount -= 1;
             totalBytes -= victim.bytes;
         }
     }
-    return entryCount < maxEntries && totalBytes + reservedBytes <= maxTotalBytes;
+    return entryCount < maxEntries &&
+        totalBytes + reservedBytes <= maxTotalBytes;
 }
 async function pruneActivityDirectory(input) {
-    const identity = await input.activityIdentityReader.resolveCurrent(input.rootDir, input.activityId);
-    if (identity.kind !== "resolved") {
-        logger.debug({ activity_id: input.activityId }, "activity retention skipped because exact generation was unavailable");
+    const removed = await removeActivityDirectoryIncarnation({
+        activityId: input.activityId,
+        incarnation: input.incarnation,
+        reason: "retention",
+        testHooks: input.testHooks,
+    });
+    if (removed.kind !== "removed") {
+        logger.debug({ activity_id: input.activityId, removal: removed.kind }, "activity retention skipped because exact generation was unavailable");
         return false;
     }
-    const sessionLogIdentity = await readSessionLogGeneration(input.activityDir);
-    const sessionLogGeneration = sessionLogIdentity.kind === "available"
-        ? sessionLogIdentity.sessionLogGeneration
-        : sessionLogIdentity.kind === "legacy"
-            ? identity.activityGeneration
+    await cleanupActivitySessionLog({
+        sessionLogRootDir: input.sessionLogRootDir,
+        activityId: input.activityId,
+        localGeneration: input.incarnation.localGeneration,
+        sessionLogIdentity: removed.sessionLogIdentity,
+    });
+    return true;
+}
+async function removeActivityDirectoryIncarnation(input) {
+    let admitted;
+    try {
+        admitted = await reopenActivityDirectory(input.incarnation);
+        if (admitted === undefined)
+            return { kind: "missing" };
+        const activityDir = admitted.path;
+        const quarantinePath = join(dirname(activityDir), `.retired-${input.activityId}-${randomUUID()}`);
+        await verifyActivityDirectory(activityDir, admitted);
+        await input.testHooks.beforeActivityDirectoryQuarantine?.(input.activityId, input.reason);
+        try {
+            await rename(activityDir, quarantinePath);
+        }
+        catch (error) {
+            return isFileSystemError(error, "ENOENT")
+                ? { kind: "missing" }
+                : { kind: "unavailable" };
+        }
+        try {
+            await verifyActivityDirectory(quarantinePath, admitted);
+        }
+        catch (error) {
+            // A same-ID replacement was moved instead of the admitted incarnation.
+            // Restore it only while the public name remains free; never delete it.
+            if (await lstat(activityDir).catch(() => undefined) === undefined) {
+                await rename(quarantinePath, activityDir).catch(() => undefined);
+            }
+            throw error;
+        }
+        const sessionLogIdentity = await readSessionLogGeneration(quarantinePath);
+        await verifyActivityDirectory(quarantinePath, admitted);
+        try {
+            await rm(quarantinePath, { recursive: true, force: false });
+        }
+        catch (error) {
+            if (await lstat(activityDir).catch(() => undefined) === undefined) {
+                await rename(quarantinePath, activityDir).catch(() => undefined);
+            }
+            return isFileSystemError(error, "ENOENT")
+                ? { kind: "unsafe" }
+                : { kind: "unavailable" };
+        }
+        return { kind: "removed", sessionLogIdentity };
+    }
+    catch (error) {
+        return error instanceof UnsafeActivityDirectoryError
+            ? { kind: "unsafe" }
+            : { kind: "unavailable" };
+    }
+    finally {
+        await admitted?.handle.close().catch(() => undefined);
+    }
+}
+async function cleanupActivitySessionLog(input) {
+    const sessionLogGeneration = input.sessionLogIdentity.kind === "available"
+        ? input.sessionLogIdentity.sessionLogGeneration
+        : input.sessionLogIdentity.kind === "legacy"
+            ? input.localGeneration
             : undefined;
-    await rm(input.activityDir, { recursive: true, force: true });
     if (sessionLogGeneration === undefined) {
         logger.warn({ activity_id: input.activityId }, "activity parent pruned but portable session-log identity was unsafe");
-        return true;
+        return;
     }
     try {
         const cleanup = await removeSessionLogGeneration({
@@ -168,7 +389,6 @@ async function pruneActivityDirectory(input) {
     catch {
         logger.warn({ activity_id: input.activityId }, "activity parent pruned but exact session-log cleanup failed");
     }
-    return true;
 }
 function truncateUtf8(text, maxBytes) {
     const source = Buffer.from(text, "utf8");
@@ -190,15 +410,15 @@ function truncateUtf8(text, maxBytes) {
     return { bytes: Buffer.alloc(0), truncated: true };
 }
 class FileActivityObservation {
-    activityDir;
+    activityDirectory;
     options;
     identity;
     state;
     writeChain = Promise.resolve();
     terminal = false;
     heartbeat;
-    constructor(activityDir, options, initialState, identity) {
-        this.activityDir = activityDir;
+    constructor(activityDirectory, options, initialState, identity) {
+        this.activityDirectory = activityDirectory;
         this.options = options;
         this.identity = identity;
         this.state = initialState;
@@ -233,6 +453,27 @@ class FileActivityObservation {
             await this.persistState();
         });
     }
+    async observe(observed) {
+        await this.enqueue(async () => {
+            if (this.terminal)
+                return;
+            if (!observedInvocationPersistenceEnabled())
+                return;
+            // The first observation is sticky; later conflicting ones are ignored.
+            if (this.observedInvocationRecorded())
+                return;
+            try {
+                this.state = this.withObservedInvocation(this.state, observed);
+                await this.persistState();
+            }
+            catch (error) {
+                logger.warn({
+                    activity_id: this.state.activityId,
+                    err: error instanceof Error ? error.message : String(error),
+                }, "activity observed-invocation persistence failed; clink execution remains authoritative");
+            }
+        });
+    }
     async complete(completion) {
         await this.enqueue(async () => {
             if (this.terminal)
@@ -253,7 +494,7 @@ class FileActivityObservation {
                 }, "activity result persistence failed; committing terminal metadata without content");
             }
             const timestamp = this.options.now().toISOString();
-            this.state = {
+            let nextState = {
                 ...this.state,
                 phase: "terminal",
                 status: completion.status,
@@ -262,9 +503,39 @@ class FileActivityObservation {
                 outcome: { kind: completion.outcomeKind },
                 ...(result === undefined ? {} : { result }),
             };
+            if (completion.observedInvocation !== undefined &&
+                observedInvocationPersistenceEnabled() &&
+                !this.observedInvocationRecorded()) {
+                try {
+                    nextState = this.withObservedInvocation(nextState, completion.observedInvocation);
+                }
+                catch (error) {
+                    logger.warn({
+                        activity_id: this.state.activityId,
+                        err: error instanceof Error ? error.message : String(error),
+                    }, "activity observed-invocation persistence failed; committing terminal metadata without it");
+                }
+            }
+            this.state = nextState;
             await this.persistState();
         });
     }
+    observedInvocationRecorded() {
+        return this.state.schemaVersion === "clinkx-dashboard-activity-v3" &&
+            this.state.observedInvocation !== undefined;
+    }
+    /**
+     * Best-effort V3 upgrade carrying any existing pre-dispatch audit (a V2
+     * begin) plus the runtime observation; a V1 begin upgrades with the
+     * observation alone.
+     */
+    withObservedInvocation(state, observed) {
+        return ActivityStateV3Schema.parse({
+            ...state,
+            schemaVersion: "clinkx-dashboard-activity-v3",
+            observedInvocation: observed,
+        });
+    }
     async enqueue(task) {
         const next = this.writeChain.then(task, task).catch((error) => {
             logger.warn({
@@ -279,7 +550,7 @@ class FileActivityObservation {
         if (!this.options.retainResult || resultText === undefined)
             return undefined;
         const { bytes, truncated } = truncateUtf8(resultText, this.options.maxResultBytes);
-        await writeFileAtomic(join(this.activityDir, ACTIVITY_RESULT_FILENAME), bytes);
+        await writeActivityFileAtomic(this.activityDirectory, ACTIVITY_RESULT_FILENAME, bytes);
         return {
             path: ACTIVITY_RESULT_FILENAME,
             bytes: bytes.byteLength,
@@ -288,7 +559,7 @@ class FileActivityObservation {
         };
     }
     async persistState() {
-        await writeFileAtomic(join(this.activityDir, ACTIVITY_STATE_FILENAME), serializedState(this.state));
+        await writeActivityFileAtomic(this.activityDirectory, ACTIVITY_STATE_FILENAME, serializedState(this.state));
     }
 }
 export function createActivityJournal(options) {
@@ -296,6 +567,8 @@ export function createActivityJournal(options) {
     const sessionLogRootDir = options.sessionLogRootDir ??
         join(options.rootDir, "..", "session-logs");
     const now = options.now ?? (() => new Date());
+    const persistInvocationAuditV2 = invocationAuditV2PersistenceEnabled();
+    const testHooks = options.testHooks ?? {};
     const maxResultBytes = Number.isSafeInteger(options.maxResultBytes) &&
         (options.maxResultBytes ?? 0) > 0
         ? Math.min(options.maxResultBytes, DEFAULT_MAX_ACTIVITY_RESULT_BYTES)
@@ -314,12 +587,43 @@ export function createActivityJournal(options) {
         (normalized.retainResult ? normalized.maxResultBytes : 0);
     let admissionChain = Promise.resolve();
     async function beginOne(input) {
+        let claimedDirectory;
         try {
             const parsed = ActivityIdSchema.parse(input.activityId);
+            const admissionTime = now();
+            const timestamp = admissionTime.toISOString();
+            const commonState = {
+                activityId: parsed,
+                kind: input.kind,
+                phase: "resolving",
+                status: "running",
+                adapter: input.adapter,
+                role: input.role,
+                startedAt: timestamp,
+                stateUpdatedAt: timestamp,
+                leaseUpdatedAt: timestamp,
+                ...(input.projectFolders === undefined || input.projectFolders.length === 0
+                    ? {}
+                    : { projectFolders: [...input.projectFolders] }),
+            };
+            const initialState = !persistInvocationAuditV2 || input.invocation === undefined
+                ? ActivityStateV1Schema.parse({
+                    schemaVersion: "clinkx-dashboard-activity-v1",
+                    ...commonState,
+                })
+                : ActivityStateV2Schema.parse({
+                    schemaVersion: "clinkx-dashboard-activity-v2",
+                    ...commonState,
+                    invocation: input.invocation,
+                });
+            // Admission is transactional from this point forward: validate both the
+            // complete schema and the producer byte cap before mkdir or retention can
+            // mutate observable state.
+            const initialStateBytes = serializedState(initialState);
             await mkdir(options.rootDir, { recursive: true, mode: 0o700 });
             await chmod(options.rootDir, 0o700);
             try {
-                const admitted = await pruneActivities(options.rootDir, sessionLogRootDir, activityIdentityReader, now(), maxAgeMs, maxEntries, maxTotalBytes, reservedBytes);
+                const admitted = await pruneActivities(options.rootDir, sessionLogRootDir, admissionTime, maxAgeMs, maxEntries, maxTotalBytes, reservedBytes, testHooks);
                 if (!admitted) {
                     logger.warn({ activity_id: input.activityId }, "activity journal capacity is occupied by live or unreadable records; observation disabled");
                     return NOOP_OBSERVATION;
@@ -334,35 +638,56 @@ export function createActivityJournal(options) {
             }
             const activityDir = join(options.rootDir, parsed);
             await mkdir(activityDir, { mode: 0o700 });
-            await chmod(activityDir, 0o700);
-            const sessionLogGeneration = await createSessionLogGeneration(activityDir);
-            const timestamp = now().toISOString();
-            const initialState = ActivityStateV1Schema.parse({
-                schemaVersion: "clinkx-dashboard-activity-v1",
-                activityId: parsed,
-                kind: input.kind,
-                phase: "resolving",
-                status: "running",
-                adapter: input.adapter,
-                role: input.role,
-                startedAt: timestamp,
-                stateUpdatedAt: timestamp,
-                leaseUpdatedAt: timestamp,
-                ...(input.projectFolders === undefined || input.projectFolders.length === 0
-                    ? {}
-                    : { projectFolders: [...input.projectFolders] }),
-            });
-            await writeFileAtomic(join(activityDir, ACTIVITY_STATE_FILENAME), serializedState(initialState));
+            const admittedDirectory = await inspectActivityDirectory(activityDir, parsed);
+            if (admittedDirectory === undefined) {
+                throw new Error("activity journal directory identity unavailable");
+            }
+            claimedDirectory = captureActivityDirectoryIncarnation(admittedDirectory);
+            const createdSessionLogGeneration = await (async () => {
+                try {
+                    await admittedDirectory.handle.chmod(0o700);
+                    await verifyActivityDirectory(admittedDirectory.path, admittedDirectory);
+                    const generation = await createSessionLogGeneration(admittedDirectory.path);
+                    await verifyActivityDirectory(admittedDirectory.path, admittedDirectory);
+                    return generation;
+                }
+                finally {
+                    await admittedDirectory.handle.close().catch(() => undefined);
+                }
+            })();
+            await writeActivityFileAtomic(claimedDirectory, ACTIVITY_STATE_FILENAME, initialStateBytes);
             const identity = await activityIdentityReader.resolveCurrent(options.rootDir, parsed);
-            if (identity.kind !== "resolved") {
+            if (identity.kind !== "resolved" ||
+                identity.activityGeneration !== claimedDirectory.localGeneration) {
                 throw new Error("activity journal directory identity unavailable");
             }
-            return new FileActivityObservation(activityDir, normalized, initialState, Object.freeze({
+            return new FileActivityObservation(claimedDirectory, normalized, initialState, Object.freeze({
                 activityId: parsed,
-                activityGeneration: sessionLogGeneration,
+                activityGeneration: createdSessionLogGeneration,
             }));
         }
         catch (error) {
+            if (claimedDirectory !== undefined) {
+                try {
+                    const removed = await removeActivityDirectoryIncarnation({
+                        activityId: claimedDirectory.activityId,
+                        incarnation: claimedDirectory,
+                        reason: "admission_cleanup",
+                        testHooks,
+                    });
+                    if (removed.kind === "removed") {
+                        await cleanupActivitySessionLog({
+                            sessionLogRootDir,
+                            activityId: claimedDirectory.activityId,
+                            localGeneration: claimedDirectory.localGeneration,
+                            sessionLogIdentity: removed.sessionLogIdentity,
+                        });
+                    }
+                }
+                catch {
+                    // Cleanup is best-effort, but never widens beyond the exact incarnation.
+                }
+            }
             logger.warn({
                 activity_id: input.activityId,
                 err: error instanceof Error ? error.message : String(error),