clinkx 0.3.0 → 1.1.0

package/dist/activity-journal.js

@@ -0,0 +1,706 @@
+import { createHash, randomUUID } from "node:crypto";
+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, 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() { },
+});
+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 {
+        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);
+        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 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, 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 {
+            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) {
+                return;
+            }
+            if (now.getTime() - Date.parse(parsed.data.completedAt) > maxAgeMs) {
+                await pruneActivityDirectory({
+                    sessionLogRootDir,
+                    activityId: entry.name,
+                    incarnation,
+                    testHooks,
+                });
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                logger.debug({
+                    activity_id: entry.name,
+                    err: error instanceof Error ? error.message : String(error),
+                }, "activity journal could not inspect a retention candidate");
+            }
+        }
+        finally {
+            await admitted?.handle.close().catch(() => undefined);
+        }
+    }));
+    const survivors = await readdir(rootDir, { withFileTypes: true });
+    const terminal = [];
+    let totalBytes = 0;
+    for (const entry of survivors) {
+        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 {
+            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(admitted.path, child.name))).size;
+            }
+            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,
+                    completedAtMs: Date.parse(parsed.data.completedAt),
+                    bytes: activityBytes,
+                    incarnation,
+                });
+            }
+        }
+        catch {
+            // 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);
+    let entryCount = survivors.filter((entry) => entry.isDirectory()).length;
+    while (entryCount >= maxEntries && terminal.length > 0) {
+        const victim = terminal.shift();
+        if (await pruneActivityDirectory({
+            sessionLogRootDir,
+            activityId: victim.activityId,
+            incarnation: victim.incarnation,
+            testHooks,
+        })) {
+            entryCount -= 1;
+            totalBytes -= victim.bytes;
+        }
+    }
+    while (totalBytes + reservedBytes > maxTotalBytes &&
+        terminal.length > 0) {
+        const victim = terminal.shift();
+        if (await pruneActivityDirectory({
+            sessionLogRootDir,
+            activityId: victim.activityId,
+            incarnation: victim.incarnation,
+            testHooks,
+        })) {
+            entryCount -= 1;
+            totalBytes -= victim.bytes;
+        }
+    }
+    return entryCount < maxEntries &&
+        totalBytes + reservedBytes <= maxTotalBytes;
+}
+async function pruneActivityDirectory(input) {
+    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;
+    }
+    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;
+    if (sessionLogGeneration === undefined) {
+        logger.warn({ activity_id: input.activityId }, "activity parent pruned but portable session-log identity was unsafe");
+        return;
+    }
+    try {
+        const cleanup = await removeSessionLogGeneration({
+            rootDir: input.sessionLogRootDir,
+            family: "activity",
+            generation: sessionLogGeneration,
+        });
+        if (cleanup.kind === "unsafe" || cleanup.kind === "unavailable") {
+            logger.warn({ activity_id: input.activityId, cleanup: cleanup.kind }, "activity parent pruned but exact session-log cleanup was unavailable");
+        }
+    }
+    catch {
+        logger.warn({ activity_id: input.activityId }, "activity parent pruned but exact session-log cleanup failed");
+    }
+}
+function truncateUtf8(text, maxBytes) {
+    const source = Buffer.from(text, "utf8");
+    if (source.byteLength <= maxBytes) {
+        return { bytes: source, truncated: false };
+    }
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    let end = maxBytes;
+    while (end > 0) {
+        const candidate = source.subarray(0, end);
+        try {
+            decoder.decode(candidate);
+            return { bytes: candidate, truncated: true };
+        }
+        catch {
+            end -= 1;
+        }
+    }
+    return { bytes: Buffer.alloc(0), truncated: true };
+}
+class FileActivityObservation {
+    activityDirectory;
+    options;
+    identity;
+    state;
+    writeChain = Promise.resolve();
+    terminal = false;
+    heartbeat;
+    constructor(activityDirectory, options, initialState, identity) {
+        this.activityDirectory = activityDirectory;
+        this.options = options;
+        this.identity = identity;
+        this.state = initialState;
+        if (options.heartbeatIntervalMs > 0) {
+            this.heartbeat = setInterval(() => {
+                void this.enqueue(async () => {
+                    if (this.terminal)
+                        return;
+                    const timestamp = this.options.now().toISOString();
+                    this.state = {
+                        ...this.state,
+                        stateUpdatedAt: timestamp,
+                        leaseUpdatedAt: timestamp,
+                    };
+                    await this.persistState();
+                });
+            }, options.heartbeatIntervalMs);
+            this.heartbeat.unref();
+        }
+    }
+    async transition(phase) {
+        await this.enqueue(async () => {
+            if (this.terminal)
+                return;
+            const timestamp = this.options.now().toISOString();
+            this.state = {
+                ...this.state,
+                phase,
+                stateUpdatedAt: timestamp,
+                leaseUpdatedAt: timestamp,
+            };
+            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)
+                return;
+            this.terminal = true;
+            if (this.heartbeat !== undefined) {
+                clearInterval(this.heartbeat);
+                this.heartbeat = undefined;
+            }
+            let result;
+            try {
+                result = await this.persistResult(completion.resultText);
+            }
+            catch (error) {
+                logger.warn({
+                    activity_id: this.state.activityId,
+                    err: error instanceof Error ? error.message : String(error),
+                }, "activity result persistence failed; committing terminal metadata without content");
+            }
+            const timestamp = this.options.now().toISOString();
+            let nextState = {
+                ...this.state,
+                phase: "terminal",
+                status: completion.status,
+                stateUpdatedAt: timestamp,
+                completedAt: timestamp,
+                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({
+                activity_id: this.state.activityId,
+                err: error instanceof Error ? error.message : String(error),
+            }, "activity journal write failed; clink execution remains authoritative");
+        });
+        this.writeChain = next;
+        await next;
+    }
+    async persistResult(resultText) {
+        if (!this.options.retainResult || resultText === undefined)
+            return undefined;
+        const { bytes, truncated } = truncateUtf8(resultText, this.options.maxResultBytes);
+        await writeActivityFileAtomic(this.activityDirectory, ACTIVITY_RESULT_FILENAME, bytes);
+        return {
+            path: ACTIVITY_RESULT_FILENAME,
+            bytes: bytes.byteLength,
+            sha256: createHash("sha256").update(bytes).digest("hex"),
+            truncated,
+        };
+    }
+    async persistState() {
+        await writeActivityFileAtomic(this.activityDirectory, ACTIVITY_STATE_FILENAME, serializedState(this.state));
+    }
+}
+export function createActivityJournal(options) {
+    const activityIdentityReader = createDashboardActivityReader();
+    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)
+        : DEFAULT_MAX_ACTIVITY_RESULT_BYTES;
+    const normalized = {
+        retainResult: options.retainResult ?? false,
+        maxResultBytes,
+        heartbeatIntervalMs: options.heartbeatIntervalMs ?? DEFAULT_ACTIVITY_HEARTBEAT_INTERVAL_MS,
+        now,
+    };
+    const maxAgeMs = options.maxAgeMs ?? DEFAULT_ACTIVITY_MAX_AGE_MS;
+    const maxEntries = options.maxEntries ?? DEFAULT_MAX_ACTIVITY_ENTRIES;
+    const maxTotalBytes = options.maxTotalBytes ?? DEFAULT_MAX_ACTIVITY_TOTAL_BYTES;
+    const reservedBytes = MAX_ACTIVITY_STATE_BYTES +
+        SESSION_LOG_GENERATION_FILE_BYTES +
+        (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, 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;
+                }
+            }
+            catch (error) {
+                logger.warn({
+                    activity_id: input.activityId,
+                    err: error instanceof Error ? error.message : String(error),
+                }, "activity journal pruning failed; observation disabled");
+                return NOOP_OBSERVATION;
+            }
+            const activityDir = join(options.rootDir, parsed);
+            await mkdir(activityDir, { mode: 0o700 });
+            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" ||
+                identity.activityGeneration !== claimedDirectory.localGeneration) {
+                throw new Error("activity journal directory identity unavailable");
+            }
+            return new FileActivityObservation(claimedDirectory, normalized, initialState, Object.freeze({
+                activityId: parsed,
+                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),
+            }, "activity journal start failed; clink execution remains authoritative");
+            return NOOP_OBSERVATION;
+        }
+    }
+    return {
+        begin(input) {
+            const next = admissionChain.then(() => beginOne(input), () => beginOne(input));
+            admissionChain = next.then(() => undefined, () => undefined);
+            return next;
+        },
+    };
+}
+//# sourceMappingURL=activity-journal.js.map