@kontourai/flow-agents 3.7.0 → 3.9.0

package/build/src/continuation-driver.js

@@ -0,0 +1,444 @@
+import * as fs from "node:fs";
+import { constants as fsConstants } from "node:fs";
+import { randomUUID } from "node:crypto";
+import * as path from "node:path";
+import { inspectBuilderFlowSession, syncBuilderFlowSession } from "./builder-flow-runtime.js";
+import { atomicWriteJson, ensureSafeDirectory } from "./lib/fs.js";
+export async function runContinuationDriver(input) {
+    assertMaxTurns(input.maxTurns);
+    const now = input.now ?? (() => new Date());
+    const waitForBarrier = input.waitForBarrier ?? (async () => "pending");
+    const authorizeTurn = input.authorizeTurn ?? (async () => { });
+    const adapterCommandIdentity = input.adapterCommandIdentity ?? null;
+    let snapshot = validateSnapshot(await input.runtime.inspect());
+    let state = loadOrCreateState(input.store, snapshot, input.maxTurns, adapterCommandIdentity, now);
+    if (state.max_turns !== input.maxTurns)
+        throw new Error(`continuation maxTurns ${input.maxTurns} does not match the persisted mission budget ${state.max_turns}`);
+    if (state.adapter_command_identity !== adapterCommandIdentity)
+        throw new Error("continuation adapter command identity does not match the persisted mission adapter");
+    const inspectedOutcome = canonicalOutcome(snapshot);
+    if (inspectedOutcome === "done")
+        return finishDone(input.store, state, snapshot, now);
+    if (inspectedOutcome === "failed")
+        return finishFailed(input.store, state, snapshot, now);
+    if (state.pending_barrier) {
+        const barrier = state.pending_barrier;
+        const readiness = await waitForBarrier(barrier);
+        if (readiness === "pending") {
+            state = saveState(input.store, state, { status: "waiting" }, now);
+            return { outcome: "waiting", turns_started: state.turns_started, snapshot, barrier };
+        }
+        state = saveState(input.store, state, { status: "active", pending_barrier: null }, now);
+        appendEvent(input.store, state, snapshot, "resumed", now, { barrier });
+    }
+    snapshot = validateSnapshot(await input.runtime.synchronize());
+    assertMissionIdentity(state, snapshot);
+    const initialOutcome = canonicalOutcome(snapshot);
+    if (initialOutcome === "done")
+        return finishDone(input.store, state, snapshot, now);
+    if (initialOutcome === "failed")
+        return finishFailed(input.store, state, snapshot, now);
+    if (initialOutcome === "waiting") {
+        state = saveState(input.store, state, { status: "waiting" }, now);
+        return { outcome: "waiting", turns_started: state.turns_started, snapshot };
+    }
+    while (state.turns_started < input.maxTurns) {
+        await authorizeTurn();
+        const iteration = state.turns_started + 1;
+        state = saveState(input.store, state, { status: "active", turns_started: iteration }, now);
+        appendEvent(input.store, state, snapshot, "turn_started", now);
+        let result;
+        try {
+            result = validateTurnResult(await input.runtime.execute(Object.freeze({
+                schema_version: "1.0",
+                run_id: snapshot.run_id,
+                definition_id: snapshot.definition_id,
+                current_step: snapshot.current_step,
+                iteration,
+                max_turns: input.maxTurns,
+                next_action: snapshot.next_action ? structuredClone(snapshot.next_action) : null,
+            })));
+        }
+        catch (error) {
+            appendEvent(input.store, state, snapshot, "turn_failed", now, { summary: boundedErrorMessage(error) });
+            snapshot = validateSnapshot(await input.runtime.synchronize());
+            assertMissionIdentity(state, snapshot);
+            const outcome = canonicalOutcome(snapshot);
+            if (outcome === "done")
+                return finishDone(input.store, state, snapshot, now);
+            if (outcome === "failed")
+                return finishFailed(input.store, state, snapshot, now);
+            if (outcome === "waiting") {
+                state = saveState(input.store, state, { status: "waiting" }, now);
+                return { outcome: "waiting", turns_started: state.turns_started, snapshot };
+            }
+            continue;
+        }
+        appendEvent(input.store, state, snapshot, "turn_completed", now, { summary: result.summary });
+        if (result.status === "wait") {
+            state = saveState(input.store, state, { status: "waiting", pending_barrier: result.barrier }, now);
+            appendEvent(input.store, state, snapshot, "parked", now, { barrier: result.barrier, summary: result.summary });
+            const readiness = await waitForBarrier(result.barrier);
+            if (readiness === "pending") {
+                return { outcome: "waiting", turns_started: state.turns_started, snapshot, barrier: result.barrier };
+            }
+            state = saveState(input.store, state, { status: "active", pending_barrier: null }, now);
+            appendEvent(input.store, state, snapshot, "resumed", now, { barrier: result.barrier });
+        }
+        snapshot = validateSnapshot(await input.runtime.synchronize());
+        assertMissionIdentity(state, snapshot);
+        const outcome = canonicalOutcome(snapshot);
+        if (outcome === "done")
+            return finishDone(input.store, state, snapshot, now);
+        if (outcome === "failed")
+            return finishFailed(input.store, state, snapshot, now);
+        if (outcome === "waiting") {
+            state = saveState(input.store, state, { status: "waiting" }, now);
+            return { outcome: "waiting", turns_started: state.turns_started, snapshot };
+        }
+    }
+    state = saveState(input.store, state, { status: "budget_exhausted" }, now);
+    appendEvent(input.store, state, snapshot, "budget_exhausted", now);
+    return { outcome: "budget_exhausted", turns_started: state.turns_started, snapshot };
+}
+export async function driveBuilderFlowSession(input) {
+    const sessionDir = path.resolve(input.sessionDir);
+    const runtime = {
+        inspect: async () => builderSessionSnapshot(await inspectBuilderFlowSession({ sessionDir })),
+        synchronize: async () => builderSessionSnapshot(await syncBuilderFlowSession({ sessionDir })),
+        execute: input.execute,
+    };
+    return runContinuationDriver({
+        maxTurns: input.maxTurns,
+        ...(input.adapterCommandIdentity ? { adapterCommandIdentity: input.adapterCommandIdentity } : {}),
+        runtime,
+        store: createFileContinuationStore(sessionDir),
+        ...(input.waitForBarrier ? { waitForBarrier: input.waitForBarrier } : {}),
+        ...(input.authorizeTurn ? { authorizeTurn: input.authorizeTurn } : {}),
+        ...(input.now ? { now: input.now } : {}),
+    });
+}
+export async function withContinuationDriverLock(sessionDirInput, body) {
+    const sessionDir = path.resolve(sessionDirInput);
+    const driverDir = path.join(sessionDir, "continuation-driver");
+    const locksDir = path.join(driverDir, "locks");
+    ensureSafeDirectory(sessionDir, locksDir);
+    const token = randomUUID();
+    const lockFile = path.join(locksDir, `${process.pid}-${token}.lock`);
+    const owner = { schema_version: "1.0", pid: process.pid, token, created_at: new Date().toISOString() };
+    acquireDriverLock(locksDir, lockFile, owner);
+    try {
+        return await body();
+    }
+    finally {
+        releaseDriverLock(lockFile, token);
+    }
+}
+export function createFileContinuationStore(sessionDirInput) {
+    const sessionDir = path.resolve(sessionDirInput);
+    const driverDir = path.join(sessionDir, "continuation-driver");
+    const stateFile = path.join(driverDir, "state.json");
+    const eventsFile = path.join(driverDir, "events.jsonl");
+    ensureSafeDirectory(sessionDir, driverDir);
+    return {
+        load() {
+            if (!fs.existsSync(stateFile)) {
+                if (fs.existsSync(eventsFile) && fs.statSync(eventsFile).size > 0)
+                    throw new Error("continuation driver state is missing while mission events exist");
+                return null;
+            }
+            const state = JSON.parse(readRegularFileNoFollow(stateFile, "continuation driver state"));
+            reconcileStateWithEvents(state, eventsFile);
+            return state;
+        },
+        save(state) {
+            atomicWriteJson(sessionDir, stateFile, state);
+        },
+        append(event) {
+            appendJsonLineNoFollow(sessionDir, eventsFile, event);
+        },
+    };
+}
+function builderSessionSnapshot(result) {
+    const nextAction = result.projection.next_action;
+    return validateSnapshot({
+        run_id: result.run.runId,
+        definition_id: result.run.definitionId,
+        status: result.run.state.status,
+        disposition: builderContinuationDisposition(result.projection.next_action),
+        current_step: result.run.state.current_step,
+        next_action: nextAction && typeof nextAction === "object" && !Array.isArray(nextAction)
+            ? structuredClone(nextAction)
+            : null,
+    });
+}
+function appendJsonLineNoFollow(root, file, value) {
+    ensureSafeDirectory(root, path.dirname(file));
+    if (fs.existsSync(file))
+        assertRegularFile(file, "continuation driver event log");
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const fd = fs.openSync(file, fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT | noFollow, 0o600);
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify(value)}\n`, "utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function assertRegularFile(file, label) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile())
+        throw new Error(`${label} must be a regular file`);
+}
+function readRegularFileNoFollow(file, label) {
+    assertRegularFile(file, label);
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const fd = fs.openSync(file, fsConstants.O_RDONLY | noFollow);
+    try {
+        if (!fs.fstatSync(fd).isFile())
+            throw new Error(`${label} must be a regular file`);
+        return fs.readFileSync(fd, "utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+function acquireDriverLock(locksDir, lockFile, owner) {
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    const fd = fs.openSync(lockFile, fsConstants.O_WRONLY | fsConstants.O_CREAT | fsConstants.O_EXCL | noFollow, 0o600);
+    try {
+        fs.writeFileSync(fd, `${JSON.stringify(owner)}\n`, "utf8");
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+    try {
+        for (const name of fs.readdirSync(locksDir).sort()) {
+            const candidate = path.join(locksDir, name);
+            if (candidate === lockFile)
+                continue;
+            let existing;
+            try {
+                existing = JSON.parse(readRegularFileNoFollow(candidate, "continuation driver lock"));
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    continue;
+                throw error;
+            }
+            if (existing.schema_version !== "1.0" || typeof existing.pid !== "number" || !Number.isSafeInteger(existing.pid) || existing.pid <= 0 || typeof existing.token !== "string") {
+                throw new Error("continuation driver lock is invalid");
+            }
+            if (processAlive(existing.pid))
+                throw new Error(`continuation driver is already running under pid ${existing.pid}`);
+            try {
+                fs.unlinkSync(candidate);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+    }
+    catch (error) {
+        try {
+            fs.unlinkSync(lockFile);
+        }
+        catch { }
+        throw error;
+    }
+}
+function releaseDriverLock(lockFile, token) {
+    try {
+        const owner = JSON.parse(readRegularFileNoFollow(lockFile, "continuation driver lock"));
+        if (owner.token === token)
+            fs.unlinkSync(lockFile);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function loadOrCreateState(store, snapshot, maxTurns, adapterCommandIdentity, now) {
+    const existing = store.load();
+    if (existing) {
+        validateState(existing);
+        assertMissionIdentity(existing, snapshot);
+        return existing;
+    }
+    const state = {
+        schema_version: "1.0",
+        run_id: snapshot.run_id,
+        definition_id: snapshot.definition_id,
+        max_turns: maxTurns,
+        adapter_command_identity: adapterCommandIdentity,
+        status: "active",
+        turns_started: 0,
+        pending_barrier: null,
+        updated_at: now().toISOString(),
+    };
+    store.save(state);
+    appendEvent(store, state, snapshot, "started", now);
+    return state;
+}
+function canonicalOutcome(snapshot) {
+    return snapshot.disposition;
+}
+function finishDone(store, state, snapshot, now) {
+    const done = saveState(store, state, { status: "done", pending_barrier: null }, now);
+    appendEvent(store, done, snapshot, "done", now);
+    return { outcome: "done", turns_started: done.turns_started, snapshot };
+}
+function finishFailed(store, state, snapshot, now) {
+    const failed = saveState(store, state, { status: "failed", pending_barrier: null }, now);
+    return { outcome: "failed", turns_started: failed.turns_started, snapshot };
+}
+function saveState(store, current, patch, now) {
+    const next = { ...current, ...patch, updated_at: now().toISOString() };
+    store.save(next);
+    return next;
+}
+function appendEvent(store, state, snapshot, type, now, extra = {}) {
+    store.append({
+        schema_version: "1.0",
+        type,
+        run_id: state.run_id,
+        definition_id: state.definition_id,
+        current_step: snapshot.current_step,
+        turns_started: state.turns_started,
+        at: now().toISOString(),
+        ...(extra.barrier ? { barrier: extra.barrier } : {}),
+        ...(extra.summary ? { summary: extra.summary } : {}),
+    });
+}
+function validateSnapshot(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("continuation runtime returned an invalid canonical snapshot");
+    for (const field of ["run_id", "definition_id", "status", "current_step"]) {
+        if (typeof value[field] !== "string" || value[field].length === 0)
+            throw new Error(`continuation snapshot ${field} must be a non-empty string`);
+    }
+    if (!new Set(["continue", "waiting", "done", "failed"]).has(value.disposition))
+        throw new Error("continuation snapshot disposition is invalid");
+    if (value.next_action !== null && (typeof value.next_action !== "object" || Array.isArray(value.next_action))) {
+        throw new Error("continuation snapshot next_action must be an object or null");
+    }
+    return structuredClone(value);
+}
+function validateTurnResult(value) {
+    if (!value || typeof value !== "object" || (value.status !== "completed" && value.status !== "wait")) {
+        throw new Error("continuation adapter must return status completed or wait");
+    }
+    if (value.status === "wait")
+        validateBarrier(value.barrier);
+    if (value.summary !== undefined && typeof value.summary !== "string")
+        throw new Error("continuation adapter summary must be a string");
+    const copy = structuredClone(value);
+    if (copy.summary && copy.summary.length > 2_000)
+        copy.summary = `${copy.summary.slice(0, 1_997)}...`;
+    return copy;
+}
+function validateBarrier(barrier) {
+    if (!barrier || typeof barrier !== "object")
+        throw new Error("continuation wait result requires a barrier");
+    if (barrier.kind === "pid") {
+        if (!Number.isSafeInteger(barrier.pid) || barrier.pid <= 0)
+            throw new Error("continuation pid barrier requires a positive integer pid");
+        return;
+    }
+    if (barrier.kind === "deadline") {
+        if (typeof barrier.at !== "string" || !Number.isFinite(Date.parse(barrier.at)))
+            throw new Error("continuation deadline barrier requires an ISO date-time");
+        return;
+    }
+    throw new Error("continuation barrier kind must be pid or deadline");
+}
+function validateState(state) {
+    if (state.schema_version !== "1.0")
+        throw new Error("continuation driver state schema_version must be 1.0");
+    assertMaxTurns(state.max_turns);
+    if (state.adapter_command_identity !== null && (typeof state.adapter_command_identity !== "string" || state.adapter_command_identity.length === 0)) {
+        throw new Error("continuation driver adapter_command_identity must be a non-empty string or null");
+    }
+    if (!Number.isSafeInteger(state.turns_started) || state.turns_started < 0)
+        throw new Error("continuation driver turns_started must be a non-negative integer");
+    if (state.turns_started > state.max_turns)
+        throw new Error("continuation driver turns_started cannot exceed max_turns");
+    if (!new Set(["active", "waiting", "done", "failed", "budget_exhausted"]).has(state.status))
+        throw new Error("continuation driver state status is invalid");
+    if (state.status === "budget_exhausted" && state.turns_started !== state.max_turns) {
+        throw new Error("continuation driver budget_exhausted state must consume max_turns");
+    }
+    if (state.pending_barrier)
+        validateBarrier(state.pending_barrier);
+}
+function assertMissionIdentity(state, snapshot) {
+    if (state.run_id !== snapshot.run_id || state.definition_id !== snapshot.definition_id) {
+        throw new Error("continuation driver mission identity does not match the canonical Flow run");
+    }
+}
+function assertMaxTurns(value) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > 100)
+        throw new Error("continuation maxTurns must be an integer from 1 through 100");
+}
+function boundedErrorMessage(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.length <= 2_000 ? message : `${message.slice(0, 1_997)}...`;
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function reconcileStateWithEvents(state, eventsFile) {
+    if (!fs.existsSync(eventsFile)) {
+        if (state.turns_started > 0)
+            throw new Error("continuation driver event history is missing for a started mission");
+        return;
+    }
+    const lines = readRegularFileNoFollow(eventsFile, "continuation driver event log").split("\n").filter((line) => line.length > 0);
+    let highestStartedTurn = 0;
+    let eventBarrier = null;
+    for (const line of lines) {
+        const event = JSON.parse(line);
+        if (event.run_id !== state.run_id || event.definition_id !== state.definition_id)
+            throw new Error("continuation driver event history has a foreign mission identity");
+        if (event.type === "turn_started") {
+            if (!Number.isSafeInteger(event.turns_started) || event.turns_started < 1)
+                throw new Error("continuation driver event history has an invalid turn count");
+            highestStartedTurn = Math.max(highestStartedTurn, event.turns_started);
+        }
+        if (event.type === "parked") {
+            validateBarrier(event.barrier);
+            eventBarrier = structuredClone(event.barrier);
+        }
+        if (event.type === "resumed")
+            eventBarrier = null;
+    }
+    if (highestStartedTurn > state.turns_started)
+        throw new Error("continuation driver state rolled back behind its event history");
+    if (state.turns_started > highestStartedTurn + 1)
+        throw new Error("continuation driver state is ahead of its event history");
+    if (!state.pending_barrier && eventBarrier) {
+        state.pending_barrier = eventBarrier;
+        state.status = "waiting";
+    }
+}
+function builderContinuationDisposition(nextAction) {
+    if (!nextAction || typeof nextAction !== "object" || Array.isArray(nextAction))
+        throw new Error("Builder Flow projection is missing its canonical next action");
+    const status = nextAction.status;
+    if (status === "continue")
+        return "continue";
+    if (status === "blocked")
+        return "waiting";
+    if (status === "done")
+        return "done";
+    if (status === "failed")
+        return "failed";
+    throw new Error(`Builder Flow projection has unsupported next-action status: ${String(status)}`);
+}

package/build/src/index.d.ts

@@ -2,6 +2,8 @@ export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRu
 export type { BuilderBuildRunResult, BuilderBuildRunIdentityMismatch, BuilderBuildTrustBundleEvidenceInput, EvaluateBuilderBuildRunInput, LoadBuilderBuildRunInput, StartBuilderBuildRunInput, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
 export type { BuilderFlowAgentLifecycleInput, BuilderFlowAuthorizedLifecycleInput, BuilderFlowSessionInput, BuilderFlowSessionResult } from "./builder-flow-runtime.js";
+export { createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
+export type { ContinuationBarrier, ContinuationDriverEvent, ContinuationDriverOutcome, ContinuationDriverState, ContinuationRuntimePort, ContinuationSnapshot, ContinuationStateStore, ContinuationTurnRequest, ContinuationTurnResult, DriveBuilderFlowSessionInput, RunContinuationDriverInput, } from "./continuation-driver.js";
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 export type { BuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";
 export { defaultArtifactRootForRead, defaultCodexHome, defaultTelemetryDirForRead, defaultTelemetryDirsForRead, durableFlowAgentsRoot, durableInstallRecordPath, DURABLE_FLOW_AGENTS_DIR, FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_SUBDIR, firstExistingPath, flowAgentsArtifactRoot, KONTOURAI_DIR, legacyTelemetryDataDir, LEGACY_TELEMETRY_DIR, telemetryDataDir, } from "./lib/local-artifact-root.js";

package/build/src/index.js

@@ -15,6 +15,7 @@ import * as path from "node:path";
 import { loadJson as _loadJson, writeJson as _writeJson } from "./cli/workflow-sidecar.js";
 export { BUILDER_BUILD_FLOW_ID, BUILDER_BUILD_FLOW_RELATIVE_PATH, BuilderBuildRunInputError, BuilderBuildRunIdentityError, evaluateBuilderBuildRun, loadBuilderBuildRun, resolveBuilderBuildFlowDefinitionPath, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export { archiveBuilderFlowSession, cancelBuilderFlowSession, pauseBuilderFlowSession, recoverBuilderFlowSession, releaseBuilderFlowAssignment, resumeBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession, } from "./builder-flow-runtime.js";
+export { createFileContinuationStore, driveBuilderFlowSession, runContinuationDriver, withContinuationDriverLock, } from "./continuation-driver.js";
 // Pure serialization contract used by external lifecycle authorities when
 // signing requests. This does not load, create, or mutate a Flow run.
 export { builderLifecycleAuthorizationPayload, loadBuilderLifecycleAuthorization } from "./builder-lifecycle-authority.js";

package/build/src/tools/build-universal-bundles.js

@@ -137,6 +137,55 @@ function copyTree(src, dest, target, rootReplacement) {
         }
     }
 }
+const skillResourcePattern = /(?:^|[`("'\s])(context\/contracts\/[A-Za-z0-9._/-]+\.md)(?=$|[`),"'\s])/gm;
+/** Export a skill as a self-contained package. Shared instruction resources
+ * retain the relative paths used by SKILL.md so runtime resolution is local. */
+function exportSkillPackage(src, dest, target) {
+    const sourceDir = path.dirname(src);
+    copyTree(sourceDir, dest, target, "<bundle-root>");
+    const skillText = readText(src);
+    const resources = new Set();
+    for (const match of skillText.matchAll(skillResourcePattern))
+        resources.add(match[1]);
+    for (const rel of [...resources].sort()) {
+        if (path.isAbsolute(rel) || rel.split("/").includes("..")) {
+            throw new Error(`skill '${path.basename(sourceDir)}': unsafe local resource '${rel}'`);
+        }
+        const source = path.resolve(root, rel);
+        const output = path.resolve(dest, rel);
+        if (!source.startsWith(`${path.resolve(root)}${path.sep}`) || !output.startsWith(`${path.resolve(dest)}${path.sep}`)) {
+            throw new Error(`skill '${path.basename(sourceDir)}': local resource escapes package '${rel}'`);
+        }
+        if (!fs.existsSync(source) || !fs.statSync(source).isFile()) {
+            throw new Error(`skill '${path.basename(sourceDir)}': missing local resource '${rel}'`);
+        }
+        if (fs.existsSync(output)) {
+            const existing = fs.readFileSync(output);
+            const incoming = fs.readFileSync(source);
+            if (!existing.equals(incoming))
+                throw new Error(`skill '${path.basename(sourceDir)}': resource collision '${rel}'`);
+            continue;
+        }
+        writeText(output, sanitizeText(readText(source), target, "<bundle-root>"));
+    }
+}
+function validateExportedSkillPackages(skillsRoot) {
+    if (!fs.existsSync(skillsRoot))
+        return;
+    for (const skillName of fs.readdirSync(skillsRoot).sort()) {
+        const skillDir = path.join(skillsRoot, skillName);
+        const skillFile = path.join(skillDir, "SKILL.md");
+        if (!fs.existsSync(skillFile))
+            continue;
+        for (const match of readText(skillFile).matchAll(skillResourcePattern)) {
+            const rel = match[1];
+            const resolved = path.resolve(skillDir, rel);
+            if (!resolved.startsWith(`${path.resolve(skillDir)}${path.sep}`) || !fs.existsSync(resolved)) {
+                throw new Error(`skill '${skillName}': unresolved exported resource '${rel}'`);
+            }
+        }
+    }
+}
 function resolveSourcePath(pathText) {
     let normalized = pathText;
     for (const alias of manifest.source_root_aliases)
@@ -473,9 +522,10 @@ function buildCodex(agents) {
     writeText(path.join(bundle, ".codex/hooks.json"), exportCodexHooks());
     for (const spec of targetAgents)
         writeText(path.join(bundle, ".codex/agents", `${spec.name}.toml`), exportCodexAgent(spec));
-    for (const { name, src } of collectAllSkills()) {
-        writeText(path.join(bundle, ".codex/skills", name, "SKILL.md"), sanitizeText(readText(src), "codex", "<bundle-root>"));
-    }
+    const skillsRoot = path.join(bundle, ".agents/skills");
+    for (const { name, src } of collectAllSkills())
+        exportSkillPackage(src, path.join(skillsRoot, name), "codex");
+    validateExportedSkillPackages(skillsRoot);
     writeText(path.join(bundle, "AGENTS.md"), exportRootAgentsMd("Codex", targetAgents, manifest.codex.task_dir));
     writeText(path.join(bundle, "README.md"), exportTargetReadme("Codex", "bash install.sh /path/to/workspace", CODEX_LIVE_HOOKS_README));
     writeText(path.join(bundle, "install.sh"), installScript("Codex", "/path/to/workspace", undefined, undefined, { configRelPath: ".codex/hooks.json", managedConfigRelPath: ".codex/hooks.json", runtime: "codex", version: pkgVersion }));

package/docs/getting-started.md

@@ -30,7 +30,15 @@ For a normal Codex global install, target the Codex home instead of a project wo
 npx @kontourai/flow-agents init --runtime codex --global --activate-kits --yes
 ```
 
-That installs into `CODEX_HOME` when it is set, otherwise `~/.codex`. Use `--dest /path/to/codex-home` only when you need an explicit override for an isolated install, CI fixture, or test.
+That splits installation by ownership: Codex-only runtime assets go into `CODEX_HOME` when set (otherwise `~/.codex`), while portable skills go into Codex's documented user catalog at `$HOME/.agents/skills`. A repository bundle install similarly exposes skills at `<repo>/.agents/skills`.
+
+Pass a positional runtime destination and `--skills-dir PATH` when both roots must be isolated, or set `FLOW_AGENTS_SKILLS_DIR` for headless environments:
+
+```bash
+bash scripts/install-codex-home.sh /tmp/codex-home --skills-dir /tmp/agents/skills
+```
+
+Installer output reports both destinations. Reinstall preserves unknown user skills and migrates only unchanged Flow Agents-owned files from the former `CODEX_HOME/skills` layout; modified legacy content is retained. Flow Agents intentionally does not create a compatibility symlink because the Codex runtime home must not own or mask a universal user catalog, and the installer refuses to write through symlinked destinations.
 
 Keep generated Codex base config lean. Put profile-specific model, provider, and approval settings in separate `<profile>.config.toml` files and select them with `codex --profile <name>`.
 

package/docs/public-workflow-cli.md

@@ -113,6 +113,60 @@ flow_agents workflow archive --authorization-file archive.json
 state, and the canonical Flow run without rewriting either store. Its `next_action` is freshly
 derived from the canonical run, so a stale sidecar projection cannot misdirect recovery.
 
+## Bounded Continuation Driver
+
+`workflow drive` lets the active implementation assignment run multiple Flow steps without a
+human continuation prompt. Flow remains authoritative: the runtime adapter receives the current
+projected action, but its `completed` result means only that one model turn ended. The driver
+returns `done` only after the canonical Flow run is terminal.
+
+The adapter command is an explicit JSON argv file whose executable must be an absolute path. Flow
+Agents invokes it directly without a shell, writes one versioned continuation-turn request to stdin, and requires exactly one
+JSON result on stdout:
+
+```json
+{ "argv": ["/absolute/path/to/runtime-adapter", "--profile", "builder"] }
+```
+
+```json
+{ "status": "completed", "summary": "Turn ended; synchronize canonical evidence." }
+```
+
+An adapter may instead park on a process or deadline. A pending barrier is persisted and does not
+consume another turn when `workflow drive` is invoked again:
+
+```json
+{ "status": "wait", "barrier": { "kind": "pid", "pid": 12345 }, "summary": "Waiting for the verification process." }
+```
+
+```bash
+flow_agents workflow drive \
+  --session-dir .kontourai/flow-agents/example \
+  --adapter-command-file .kontourai/flow-agents/runtime-adapter.json \
+  --max-turns 6 \
+  --turn-timeout-ms 900000 \
+  --barrier-wait-ms 300000 \
+  --json
+```
+
+Driver state and its append-only event stream live under
+`.kontourai/flow-agents/<slug>/continuation-driver/`. The mission turn count survives reinvocation;
+subsequent invocations must use the same `--max-turns` value. The request contains the
+canonical run id, definition id, current step, projected `next_action`, iteration, and budget. It
+does not mutate or replace the runtime system prompt. Adapter errors are recorded as failed turns
+and fail open to canonical resynchronization and the next bounded turn; they cannot bypass the
+persisted mission budget. The Builder Flow projection supplies the canonical continue/wait/done/failed
+disposition, so the generic driver does not duplicate Flow lifecycle semantics. Human-decision and
+paused Flow states park, while remediable blocked and accepted-exception states continue; failed Flow
+runs stop as failed. Assignment ownership is revalidated before every adapter
+turn. A session-scoped process lock rejects concurrent drivers and safely removes unique lock files
+left by exited owners. The adapter argv plus the content digests of its executable and absolute
+regular-file arguments are bound to the mission on first invocation and rechecked before every turn.
+Adapter process groups are terminated after every non-wait result. In addition,
+state rollback or deletion is rejected when its append-only event history proves turns already
+started. These local coordination records detect accidental or in-process rollback; they are not a
+cryptographic boundary against a process that can rewrite the entire artifact directory.
+
 ## Compatibility Doctor
 
 Run doctor through the exact isolated package helper defined above:

package/docs/spec/builder-flow-runtime.md

@@ -63,8 +63,36 @@ does not create a Flow run.
 
 After a gate producer writes `trust.bundle`, the public evidence path
 synchronizes the existing run while holding the assignment subject lock.
-Synchronization is digest-idempotent: the same trust bundle is not attached
-twice.
+Synchronization selects only live claims: producer-superseded claims and claims
+carrying `metadata.superseded_by` remain auditable history but never determine
+the current outcome. Passing evidence is published atomically only when every
+required expectation for the gate is present; this prevents sequential critique
+writes from attaching an intermediate partial snapshot and consuming a
+route-back attempt. Failed evidence may still synchronize immediately when it
+carries a route reason declared by the gate; a disputed report-only critique is
+not itself a routed gate decision and remains pending.
+
+Attachments carry the exact expectation ids selected from the current bundle.
+Digest idempotence applies only while an unsuperseded attachment for that gate
+and expectation set remains live. After route-back, claims must be current for
+the new gate visit before synchronization, and claim/evidence identities used
+by any earlier attachment to that gate can never satisfy the later visit.
+Gate claims, verified criteria, and critiques carry producer-recorded version
+timestamps plus `identity_version: 2` in their identity derivation so legitimate
+re-verification creates new identities. Unmarked pre-upgrade records retain the
+legacy identity formula during rebuild; installing new code alone can never
+manufacture a fresh identity. Because those identities are embedded in TrustBundle bytes, a
+genuinely new identity necessarily changes the bundle SHA-256; byte-identical
+replay remains pending rather than consuming another attempt.
+
+Every gate visit has a canonical boundary: the latest Flow transition into the
+step, or the run's initial timestamp for its entry step. Claim creation and
+observation timestamps must fall within that visit and may not be more than 30
+seconds ahead of synchronization. The sole pre-boundary allowance is the
+30-second acquisition window for the assignment-backed `selected-work` claim,
+which is intentionally produced immediately before the canonical run starts.
+Previously attached claim and evidence identities are excluded from every later
+visit to the same gate regardless of timestamp skew.
 
 ## Public Status And Recovery
 
@@ -119,6 +147,12 @@ Workflow steering surfaces these fields on session start and prompt submission.
 Stop hook treats an unfinished canonical Flow run as active even during pickup or
 planning, blocks a premature stop in block mode, and does not release its liveness
 claim. A run is complete only when Flow reaches its terminal step.
+
+Projection is always derived from the canonical run's `current_step`, including
+composed steps that have no legacy sidecar phase (`merge-ready-ci` and `learn`).
+Both the legacy `current.json` pointer and every matching per-actor pointer are
+updated from that canonical step; `phase_map` is presentation metadata, not the
+authority for pointer navigation.
 # Builder Lifecycle Authority
 
 The canonical Flow run owns pause, resume, and cancellation. The current assignment actor may