@xfey/tutti 0.1.94 → 0.1.96

package/dist/control-plane/scratchpad-refresh.js

@@ -1,5 +1,5 @@
-import { createMainChatAgentMessage, markScratchpadRefreshSucceeded, markScratchpadSourceDirty, upsertScratchpadProjection, } from "../collaboration-state/index.js";
-import { mainChatInvalidates, scratchpadRefreshInvalidates, } from "./invalidations.js";
+import { createMainChatAgentMessage, markScratchpadRefreshSucceeded, upsertScratchpadProjection, } from "../collaboration-state/index.js";
+import { mainChatInvalidates, scratchpadRefreshInvalidates } from "./invalidations.js";
 export function applyScratchpadRefreshOutput(input) {
     if (input.output.decision === "needs_human") {
         const message = createMainChatAgentMessage(input.store.db, {
@@ -7,7 +7,7 @@ export function applyScratchpadRefreshOutput(input) {
             refs: {
                 workflow_ref: input.workflowRef,
                 activity_ref: input.activityRef,
-                scratchpad_source: "include",
+                scratchpad_source: "exclude",
             },
             now: input.now,
         });
@@ -20,7 +20,6 @@ export function applyScratchpadRefreshOutput(input) {
             ...input.cursorUpdate,
             now: input.now,
         });
-        markScratchpadSourceDirty(input.store.db, { now: input.now });
         return {
             kind: "needs_human",
             summary: input.output.request_payload.summary,

package/dist/control-plane/types.d.ts

@@ -85,6 +85,18 @@ export type RunContinuationContext = {
     };
 };
 export type RunCorrectionContext = {
+    previous_provider_result: {
+        decision: "completed" | "completed_no_repo_changes";
+        summary: string;
+        user_note_candidate?: string;
+    } | {
+        decision: "needs_human";
+        summary: string;
+        clarification_request_payload: ClarificationRequestPayload;
+    } | {
+        decision: "failed";
+        summary: string;
+    };
     summary: string;
     reason_code: string;
     guidance: string;

package/dist/control-plane/workflows/openai.d.ts

@@ -19,6 +19,7 @@ export type OpenAiProcedureWorkflowRunnerOptions = {
         turnTimeoutMs?: number;
         baseEnv?: NodeJS.ProcessEnv;
         tuttiHome?: string;
+        projectId?: ProjectId;
         userSkillsRoot?: string;
         builtInSkillsRoot?: string;
         agentContext?: CodexAppServerAgentContextRuntime;

package/dist/control-plane/workflows/openai.js

@@ -7,7 +7,9 @@ import { createOpenAiStructuredOutputClient, runOpenAiStructuredOutput, } from "
 import { readOpenAiApiKeyCredential } from "../../providers/openai/credential-store.js";
 import { resolveOpenAiProviderConfig, } from "../../providers/openai/provider-config.js";
 import { SCRATCHPAD_REFRESH_OUTPUT_SCHEMA, TASK_COMPILE_OUTPUT_SCHEMA, PROJECT_CONTEXT_BOOTSTRAP_OUTPUT_SCHEMA, CONTEXT_SYNC_OUTPUT_SCHEMA, PROJECT_BRIEF_REFRESH_OUTPUT_SCHEMA, FOLLOW_UP_CHECK_OUTPUT_SCHEMA, REFERENCE_FILE_SUMMARY_OUTPUT_SCHEMA, isContextSyncWorkflowOutput, isFollowUpCheckStructuredOutput, isProjectBriefRefreshWorkflowOutput, isProjectContextBootstrapWorkflowOutput, isReferenceFileSummaryStructuredOutput, isScratchpadRefreshStructuredOutput, isTaskCompileStructuredOutput, } from "./structured-output.js";
-import { runCodexAppServerReadOnlyProcedure } from "../../providers/openai/app-server/read-only-procedure.js";
+import { runCodexAppServerReadOnlyProcedure, } from "../../providers/openai/app-server/read-only-procedure.js";
+import { CODEX_APP_SERVER_VERSION } from "../../providers/openai/codex-app-server.js";
+import { acquireCodexTaskSessionLock, createProviderFingerprint, markCodexTaskSessionArchived, openCodexDurableSession, recordCodexSessionArchiveFailure, recordCodexTaskSessionThread, } from "../../providers/openai/app-server/session-store.js";
 import { getProjectUserSkillsRoot } from "../../skills/index.js";
 function readOnlyAppServerOptions(options, prompt, outputSchema, skillSelectionName) {
     if (options.readOnlyAppServer === undefined) {
@@ -70,6 +72,56 @@ function readOnlyRuntimeTelemetry(context, stageId) {
         },
     };
 }
+async function runDurableReadOnlyProcedure(input) {
+    const runtime = input.options.readOnlyAppServer;
+    if (runtime?.tuttiHome === undefined ||
+        runtime.projectId === undefined ||
+        input.context === undefined) {
+        return runCodexAppServerReadOnlyProcedure(input.invocation);
+    }
+    let session = openCodexDurableSession({
+        tuttiHome: runtime.tuttiHome,
+        projectId: runtime.projectId,
+        kind: input.kind,
+        ownerRef: input.context.workflow_ref,
+        compatibility: {
+            codexVersion: CODEX_APP_SERVER_VERSION,
+            model: input.options.config.default_model,
+            providerFingerprint: createProviderFingerprint({
+                providerKind: "openai",
+                ...(input.options.config.api_base_url === undefined
+                    ? {}
+                    : { apiBaseUrl: input.options.config.api_base_url }),
+            }),
+        },
+    });
+    const release = acquireCodexTaskSessionLock(session);
+    try {
+        return await runCodexAppServerReadOnlyProcedure({
+            ...input.invocation,
+            session: {
+                codexHome: session.codexHome,
+                ...(session.metadata.thread_id === undefined
+                    ? {}
+                    : { threadId: session.metadata.thread_id }),
+                ...(session.metadata.lifecycle === "archived" ? { unarchive: true } : {}),
+                onThreadReady: (threadId) => {
+                    session = recordCodexTaskSessionThread(session, threadId);
+                },
+                archiveAfterTurn: input.archiveAfterTurn,
+                onThreadArchived: () => {
+                    session = markCodexTaskSessionArchived(session);
+                },
+                onThreadArchiveFailure: () => {
+                    recordCodexSessionArchiveFailure(session);
+                },
+            },
+        });
+    }
+    finally {
+        release();
+    }
+}
 function referenceSummarySourcePath(options, input) {
     if (options.readOnlyAppServer === undefined) {
         throw new Error("Codex app-server read-only Procedure adapter is not configured");
@@ -284,12 +336,18 @@ export function createOpenAiProcedureWorkflowRunner(options) {
                     workflow_input_json: buildTaskCompilePromptInput(input),
                 },
             });
-            const result = await runCodexAppServerReadOnlyProcedure({
-                ...readOnlyAppServerOptions(options, instructions, TASK_COMPILE_OUTPUT_SCHEMA, "task_compile"),
-                ...readOnlyRuntimeTelemetry(context, "task_compile"),
-                validateOutput: isTaskCompileStructuredOutput,
-                networkAccess: false,
-                webSearchMode: "disabled",
+            const result = await runDurableReadOnlyProcedure({
+                options,
+                context,
+                kind: "task_compile",
+                archiveAfterTurn: (output) => "proposal" in output.result,
+                invocation: {
+                    ...readOnlyAppServerOptions(options, instructions, TASK_COMPILE_OUTPUT_SCHEMA, "task_compile"),
+                    ...readOnlyRuntimeTelemetry(context, "task_compile"),
+                    validateOutput: isTaskCompileStructuredOutput,
+                    networkAccess: false,
+                    webSearchMode: "disabled",
+                },
             });
             recordUsage(options, "task_compile", result, {
                 workflow_ref: context?.workflow_ref ?? input.workflow_ref,
@@ -333,10 +391,16 @@ export function createOpenAiProcedureWorkflowRunner(options) {
                     workflow_input_json: input,
                 },
             });
-            const result = await runCodexAppServerReadOnlyProcedure({
-                ...readOnlyAppServerOptions(options, instructions, PROJECT_CONTEXT_BOOTSTRAP_OUTPUT_SCHEMA, "project_context_bootstrap"),
-                ...readOnlyRuntimeTelemetry(context, "project_context_bootstrap"),
-                validateOutput: isProjectContextBootstrapWorkflowOutput,
+            const result = await runDurableReadOnlyProcedure({
+                options,
+                context,
+                kind: "project_context_bootstrap",
+                archiveAfterTurn: () => true,
+                invocation: {
+                    ...readOnlyAppServerOptions(options, instructions, PROJECT_CONTEXT_BOOTSTRAP_OUTPUT_SCHEMA, "project_context_bootstrap"),
+                    ...readOnlyRuntimeTelemetry(context, "project_context_bootstrap"),
+                    validateOutput: isProjectContextBootstrapWorkflowOutput,
+                },
             });
             recordUsage(options, "project_context_bootstrap", result, {
                 ...(context?.workflow_ref === undefined ? {} : { workflow_ref: context.workflow_ref }),
@@ -349,10 +413,16 @@ export function createOpenAiProcedureWorkflowRunner(options) {
                 templateKey: "procedures.context_sync",
                 ...(options.promptsRoot === undefined ? {} : { promptsRoot: options.promptsRoot }),
             });
-            const result = await runCodexAppServerReadOnlyProcedure({
-                ...readOnlyAppServerOptions(options, instructions, CONTEXT_SYNC_OUTPUT_SCHEMA, "context_sync"),
-                ...readOnlyRuntimeTelemetry(context, "context_sync"),
-                validateOutput: isContextSyncWorkflowOutput,
+            const result = await runDurableReadOnlyProcedure({
+                options,
+                context,
+                kind: "context_sync",
+                archiveAfterTurn: () => true,
+                invocation: {
+                    ...readOnlyAppServerOptions(options, instructions, CONTEXT_SYNC_OUTPUT_SCHEMA, "context_sync"),
+                    ...readOnlyRuntimeTelemetry(context, "context_sync"),
+                    validateOutput: isContextSyncWorkflowOutput,
+                },
             });
             recordUsage(options, "context_sync", result, {
                 workflow_ref: context?.workflow_ref ?? input.workflow_ref,
@@ -426,6 +496,7 @@ export function resolveProjectOpenAiProcedureWorkflowRunner(options) {
                 apiKey: credential.secret,
                 workspaceRoot: options.workspaceRoot,
                 tuttiHome: options.tuttiHome,
+                projectId: options.projectId,
                 userSkillsRoot: getProjectUserSkillsRoot(options.tuttiHome, options.projectId),
                 ...(options.agentContext === undefined ? {} : { agentContext: options.agentContext }),
                 ...(options.invocationCoordinator === undefined

package/dist/control-plane/worklist-terminal-feedback.js

@@ -272,6 +272,9 @@ export function emitTaskFailedResultMessage(input) {
             : { latest_run_result_id: item.latest_run_result_id }),
         ...(input.activityRef === undefined ? {} : { activity_ref: input.activityRef }),
         ...(errorCode === undefined ? {} : { error_code: errorCode }),
+        ...(entry.detail?.detail.result.retry_action === undefined
+            ? {}
+            : { retry_action: entry.detail.detail.result.retry_action }),
     };
     return publishTaskResultMessage(input, result);
 }

package/dist/prompt-templates/index.d.ts

@@ -1,4 +1,4 @@
-export type PromptTemplateKey = "procedures.project_context_bootstrap" | "procedures.context_sync" | "procedures.project_brief_refresh" | "procedures.scratchpad_refresh" | "procedures.task_compile" | "procedures.reference_file_summary" | "procedures.follow_up_check" | "runs.task_run" | "runs.task_continuation" | "runs.task_retry" | "artifacts.applicability" | "chat.assistant" | "codex.no_write_smoke";
+export type PromptTemplateKey = "procedures.project_context_bootstrap" | "procedures.context_sync" | "procedures.project_brief_refresh" | "procedures.scratchpad_refresh" | "procedures.task_compile" | "procedures.reference_file_summary" | "procedures.follow_up_check" | "runs.task_execute" | "runs.task_finalize" | "runs.task_recovery" | "runs.task_result_contract" | "artifacts.applicability" | "chat.assistant" | "codex.no_write_smoke";
 export type RenderPromptTemplateOptions = {
     templateKey: PromptTemplateKey;
     variables?: Record<string, unknown>;

package/dist/prompt-templates/index.js

@@ -19,9 +19,10 @@ const TEMPLATE_REGISTRY = {
     "procedures.task_compile": "procedures/task-compile.md",
     "procedures.reference_file_summary": "procedures/reference-file-summary.md",
     "procedures.follow_up_check": "procedures/follow-up-check.md",
-    "runs.task_run": "runs/task-run.md",
-    "runs.task_continuation": "runs/task-continuation.md",
-    "runs.task_retry": "runs/task-retry.md",
+    "runs.task_execute": "runs/task-execute.md",
+    "runs.task_finalize": "runs/task-finalize.md",
+    "runs.task_recovery": "runs/task-recovery.md",
+    "runs.task_result_contract": "runs/task-result-contract.md",
     "artifacts.applicability": "artifacts/applicability.md",
     "chat.assistant": "chat-assistant.md",
     "codex.no_write_smoke": "codex/no-write-smoke.md",

package/dist/providers/openai/app-server/durable-session-smoke-cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=durable-session-smoke-cli.d.ts.map

package/dist/providers/openai/app-server/durable-session-smoke-cli.js

@@ -0,0 +1,229 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { existsSync, lstatSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import { createProjectId, createTaskId } from "@tutti/shared/ids";
+import { CODEX_APP_SERVER_VERSION } from "../codex-app-server.js";
+import { DEFAULT_OPENAI_MODEL } from "../model-config.js";
+import { runCodexAppServerReadOnlyProcedure } from "./read-only-procedure.js";
+import { resolveCodexAppServerSmokeProviderInput } from "./smoke-provider-input.js";
+import { acquireCodexTaskSessionLock, createProviderFingerprint, markCodexTaskSessionArchived, openCodexTaskSession, recordCodexTaskSessionThread, } from "./session-store.js";
+import { runCodexAppServerWorkspaceWriteRun } from "./workspace-write-run.js";
+const WRITE_SENTINEL = "TUTTI_DURABLE_WRITE";
+const RESULT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        sentinel: { type: "string", enum: [WRITE_SENTINEL] },
+        file_present: { type: "boolean" },
+    },
+    required: ["sentinel", "file_present"],
+};
+function isResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.sentinel === WRITE_SENTINEL &&
+        value.file_present === true);
+}
+function mode(path) {
+    return statSync(path).mode & 0o777;
+}
+function requireMode(path, expected) {
+    const actual = mode(path);
+    if (actual !== expected) {
+        throw new Error(`Durable session path has mode ${actual.toString(8)}; expected ${expected.toString(8)}.`);
+    }
+}
+function fingerprintPath(path) {
+    if (!existsSync(path)) {
+        return "missing";
+    }
+    const hash = createHash("sha256");
+    const visit = (current) => {
+        const entry = lstatSync(current);
+        hash.update(JSON.stringify({
+            path: relative(path, current),
+            mode: entry.mode & 0o777,
+            size: entry.size,
+            modified_ms: entry.mtimeMs,
+            type: entry.isDirectory() ? "directory" : entry.isSymbolicLink() ? "symlink" : "file",
+        }));
+        if (!entry.isDirectory()) {
+            return;
+        }
+        for (const child of readdirSync(current).sort()) {
+            visit(join(current, child));
+        }
+    };
+    visit(path);
+    return hash.digest("hex");
+}
+function userCodexConfigurationFingerprint() {
+    const root = join(homedir(), ".codex");
+    const hash = createHash("sha256");
+    for (const relativePath of ["auth.json", "config.toml", "plugins", "skills"]) {
+        hash.update(relativePath);
+        hash.update(fingerprintPath(join(root, relativePath)));
+    }
+    return hash.digest("hex");
+}
+async function withSessionLock(session, run) {
+    const release = acquireCodexTaskSessionLock(session);
+    try {
+        return await run();
+    }
+    finally {
+        release();
+    }
+}
+async function main() {
+    const provider = resolveCodexAppServerSmokeProviderInput();
+    const model = provider.defaultModel ?? DEFAULT_OPENAI_MODEL;
+    const smokeRoot = mkdtempSync(join(tmpdir(), "tutti-codex-durable-session-smoke-"));
+    const tuttiHome = join(smokeRoot, "tutti-home");
+    const workspaceRoot = join(smokeRoot, "repo");
+    const projectId = createProjectId();
+    const taskId = createTaskId();
+    const userCodexBefore = userCodexConfigurationFingerprint();
+    let session = openCodexTaskSession({
+        tuttiHome,
+        projectId,
+        taskId,
+        compatibility: {
+            codexVersion: CODEX_APP_SERVER_VERSION,
+            model,
+            providerFingerprint: createProviderFingerprint({
+                providerKind: "openai",
+                ...(provider.apiBaseUrl === undefined ? {} : { apiBaseUrl: provider.apiBaseUrl }),
+            }),
+        },
+    });
+    try {
+        execFileSync("git", ["init", workspaceRoot], { stdio: "ignore" });
+        execFileSync("git", [
+            "-C",
+            workspaceRoot,
+            "config",
+            "user.email",
+            "tutti-smoke@example.invalid",
+        ]);
+        execFileSync("git", ["-C", workspaceRoot, "config", "user.name", "Tutti Smoke"]);
+        const common = {
+            apiKey: provider.apiKey,
+            ...(provider.apiBaseUrl === undefined ? {} : { apiBaseUrl: provider.apiBaseUrl }),
+            defaultModel: model,
+            workspaceRoot,
+            networkAccess: false,
+            strictLeakCheck: true,
+        };
+        const execute = await withSessionLock(session, async () => await runCodexAppServerWorkspaceWriteRun({
+            ...common,
+            approvalPolicy: "never",
+            prompt: `Create durable-smoke.txt in the workspace root with exactly one line: ${WRITE_SENTINEL}. ` +
+                "Do not modify any other file. Then briefly report completion.",
+            session: {
+                codexHome: session.codexHome,
+                onThreadReady: (threadId) => {
+                    session = recordCodexTaskSessionThread(session, threadId);
+                },
+            },
+        }));
+        if (readFileSync(join(workspaceRoot, "durable-smoke.txt"), "utf8") !== `${WRITE_SENTINEL}\n`) {
+            throw new Error("Workspace-write turn did not create the exact durable smoke fixture.");
+        }
+        const threadId = session.metadata.thread_id;
+        if (threadId === undefined) {
+            throw new Error("Workspace-write turn did not persist a durable thread id.");
+        }
+        const finalize = await withSessionLock(session, async () => await runCodexAppServerReadOnlyProcedure({
+            ...common,
+            prompt: "Read durable-smoke.txt and return the supplied JSON shape. " +
+                `Use sentinel ${WRITE_SENTINEL} and set file_present to true.`,
+            outputSchema: RESULT_SCHEMA,
+            validateOutput: isResult,
+            session: {
+                codexHome: session.codexHome,
+                threadId,
+                archiveAfterTurn: () => true,
+                onThreadArchived: () => {
+                    session = markCodexTaskSessionArchived(session);
+                },
+            },
+        }));
+        if (session.metadata.lifecycle !== "archived") {
+            throw new Error("Durable smoke thread was not archived after the read-only turn.");
+        }
+        const recovery = await withSessionLock(session, async () => await runCodexAppServerReadOnlyProcedure({
+            ...common,
+            prompt: "After resuming this archived thread, read durable-smoke.txt and return the supplied " +
+                `JSON shape with sentinel ${WRITE_SENTINEL} and file_present true.`,
+            outputSchema: RESULT_SCHEMA,
+            validateOutput: isResult,
+            session: {
+                codexHome: session.codexHome,
+                threadId,
+                unarchive: true,
+                onThreadReady: (threadId) => {
+                    session = recordCodexTaskSessionThread(session, threadId);
+                },
+                archiveAfterTurn: () => true,
+                onThreadArchived: () => {
+                    session = markCodexTaskSessionArchived(session);
+                },
+            },
+        }));
+        const authPath = join(session.codexHome, "auth.json");
+        const sessionIndexPath = join(tuttiHome, "projects", projectId, "codex-sessions", "task-index", `${taskId}.json`);
+        requireMode(session.root, 0o700);
+        requireMode(session.codexHome, 0o700);
+        requireMode(session.metadataPath, 0o600);
+        requireMode(sessionIndexPath, 0o600);
+        requireMode(authPath, 0o600);
+        const codexHomeEntries = readdirSync(session.codexHome);
+        const repoSessionPaths = readdirSync(workspaceRoot).filter((entry) => entry === ".codex" || entry === "codex-sessions" || entry === "auth.json");
+        if (repoSessionPaths.length > 0) {
+            throw new Error("Durable session state was written into the target repository.");
+        }
+        if (userCodexConfigurationFingerprint() !== userCodexBefore) {
+            throw new Error("The durable smoke changed user-level Codex configuration.");
+        }
+        if (execute.thread_id !== finalize.thread_id || finalize.thread_id !== recovery.thread_id) {
+            throw new Error("Durable smoke turns did not resume the same app-server thread.");
+        }
+        console.log(JSON.stringify({
+            provider_source: provider.source,
+            status: "passed",
+            codex_version: CODEX_APP_SERVER_VERSION,
+            model,
+            same_thread_across_processes: true,
+            per_turn_output_schema: true,
+            workspace_write_then_read_only: true,
+            archive_then_unarchive: true,
+            final_lifecycle: session.metadata.lifecycle,
+            private_session_root_mode: mode(session.root).toString(8),
+            private_codex_home_mode: mode(session.codexHome).toString(8),
+            private_metadata_mode: mode(session.metadataPath).toString(8),
+            private_auth_json_mode: mode(authPath).toString(8),
+            auth_json_in_private_home: true,
+            plugin_cache_in_private_home: existsSync(join(session.codexHome, ".tmp", "plugins")),
+            state_store_in_private_home: codexHomeEntries.some((entry) => /^state_\d+\.sqlite$/u.test(entry)),
+            shell_snapshots_in_private_home: existsSync(join(session.codexHome, "shell_snapshots")),
+            user_codex_configuration_unchanged: true,
+            repo_session_files: 0,
+        }, null, 2));
+    }
+    finally {
+        rmSync(smokeRoot, { recursive: true, force: true });
+    }
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(JSON.stringify({
+        status: "failed",
+        message,
+    }, null, 2));
+    process.exitCode = 1;
+});
+//# sourceMappingURL=durable-session-smoke-cli.js.map

package/dist/providers/openai/app-server/read-only-procedure.d.ts

@@ -14,6 +14,15 @@ export type CodexAppServerReadOnlyProcedureInput<TOutput> = {
     prompt: string;
     outputSchema: unknown;
     validateOutput: (value: unknown) => value is TOutput;
+    session?: {
+        codexHome: string;
+        threadId?: string;
+        unarchive?: boolean;
+        onThreadReady?: (threadId: string) => void | Promise<void>;
+        archiveAfterTurn?: (output: TOutput) => boolean;
+        onThreadArchived?: () => void | Promise<void>;
+        onThreadArchiveFailure?: () => void | Promise<void>;
+    };
     networkAccess?: boolean;
     webSearchMode?: CodexAppServerWebSearchMode;
     skillSelectionName?: CodexAppServerSkillSelectionName;
@@ -34,6 +43,7 @@ export type CodexAppServerReadOnlyProcedureInput<TOutput> = {
 };
 export type CodexAppServerReadOnlyProcedureResult<TOutput> = {
     output: TOutput;
+    thread_id: string;
     model: string;
     turn_status: "completed";
     notification_count: number;

package/dist/providers/openai/app-server/read-only-procedure.js

@@ -128,7 +128,7 @@ export async function runCodexAppServerReadOnlyProcedure(options) {
     }
     const model = options.defaultModel ?? DEFAULT_OPENAI_MODEL;
     const tempRoot = mkdtempSync(join(tmpdir(), "tutti-codex-readonly-procedure-"));
-    const codexHome = join(tempRoot, "codex-home");
+    const codexHome = options.session?.codexHome ?? join(tempRoot, "codex-home");
     mkdirSync(codexHome, { recursive: true, mode: 0o700 });
     const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
     const turnTimeoutMs = options.turnTimeoutMs ?? DEFAULT_TURN_TIMEOUT_MS;
@@ -210,21 +210,40 @@ export async function runCodexAppServerReadOnlyProcedure(options) {
         if (!isApiKeyAccount(loginResponse)) {
             throw new CodexAppServerReadOnlyProcedureError("auth_failed", "Codex app-server did not accept API key auth.");
         }
-        const threadStartResponse = await client.request("thread/start", {
-            cwd: appServerCwd,
-            model,
-            modelProvider,
-            approvalPolicy: "never",
-            sandbox: "read-only",
-            config: buildReadOnlyThreadConfig(options),
-            ephemeral: true,
-            experimentalRawEvents: false,
-            persistExtendedHistory: false,
-        }, requestTimeoutMs);
-        const threadId = readThreadId(threadStartResponse);
+        let threadId;
+        if (options.session?.threadId === undefined) {
+            const threadStartResponse = await client.request("thread/start", {
+                cwd: appServerCwd,
+                model,
+                modelProvider,
+                approvalPolicy: "never",
+                sandbox: "read-only",
+                config: buildReadOnlyThreadConfig(options),
+                ephemeral: options.session === undefined,
+                experimentalRawEvents: false,
+                persistExtendedHistory: false,
+            }, requestTimeoutMs);
+            threadId = readThreadId(threadStartResponse);
+        }
+        else {
+            if (options.session.unarchive === true) {
+                await client.request("thread/unarchive", { threadId: options.session.threadId }, requestTimeoutMs);
+            }
+            const threadResumeResponse = await client.request("thread/resume", {
+                threadId: options.session.threadId,
+                cwd: appServerCwd,
+                model,
+                modelProvider,
+                approvalPolicy: "never",
+                sandbox: "read-only",
+                config: buildReadOnlyThreadConfig(options),
+            }, requestTimeoutMs);
+            threadId = readThreadId(threadResumeResponse) ?? options.session.threadId;
+        }
         if (threadId === null) {
             throw new CodexAppServerReadOnlyProcedureError("thread_start_failed", "Codex app-server did not return a thread id.");
         }
+        await options.session?.onThreadReady?.(threadId);
         await client.request("turn/start", {
             threadId,
             input: buildCodexAppServerTurnInput({
@@ -308,8 +327,18 @@ export async function runCodexAppServerReadOnlyProcedure(options) {
             throw new CodexAppServerReadOnlyProcedureError("secret_leak_detected", "Codex app-server output contained a sensitive runtime value.");
         }
         const usage = extractCodexAppServerTokenUsage(client.notifications);
+        if (options.session?.archiveAfterTurn?.(parsed) === true) {
+            try {
+                await client.request("thread/archive", { threadId }, requestTimeoutMs);
+                await options.session.onThreadArchived?.();
+            }
+            catch {
+                await options.session.onThreadArchiveFailure?.();
+            }
+        }
         procedureResult = {
             output: parsed,
+            thread_id: threadId,
             model,
             turn_status: "completed",
             notification_count: client.notifications.length,

package/dist/providers/openai/app-server/session-store.d.ts

@@ -0,0 +1,74 @@
+import type { ActivityRef, ProjectId, TaskId } from "@tutti/shared/ids";
+export type CodexSessionLifecycle = "active" | "archived" | "incompatible";
+export type CodexSessionKind = "formal_task_run" | "task_compile" | "project_context_bootstrap" | "context_sync";
+export type CodexSessionMetadata = {
+    version: 1;
+    session_ref: string;
+    kind: CodexSessionKind;
+    owner_ref: string;
+    thread_id?: string;
+    codex_version: string;
+    model: string;
+    provider_fingerprint: string;
+    lifecycle: CodexSessionLifecycle;
+    created_at: string;
+    last_used_at: string;
+};
+export type CodexDurableSession = {
+    root: string;
+    codexHome: string;
+    metadataPath: string;
+    metadata: CodexSessionMetadata;
+    disposition: "created" | "resumed" | "replaced_incompatible";
+};
+export type CodexTaskSession = CodexDurableSession;
+export type CodexTaskSessionCompatibility = {
+    codexVersion: string;
+    model: string;
+    providerFingerprint: string;
+};
+export declare function createProviderFingerprint(input: {
+    providerKind: "openai";
+    apiBaseUrl?: string;
+}): string;
+export declare function openCodexDurableSession(input: {
+    tuttiHome: string;
+    projectId: ProjectId;
+    kind: CodexSessionKind;
+    ownerRef: string;
+    compatibility: CodexTaskSessionCompatibility;
+    now?: Date;
+}): CodexDurableSession;
+export declare function openCodexTaskSession(input: {
+    tuttiHome: string;
+    projectId: ProjectId;
+    taskId: TaskId;
+    compatibility: CodexTaskSessionCompatibility;
+    now?: Date;
+}): CodexTaskSession;
+export type CodexSessionRecoveryEvidence = {
+    version: 1;
+    owner_activity_ref: ActivityRef;
+    updated_at: string;
+    truncated: boolean;
+    evidence: Record<string, unknown>;
+};
+export declare function writeCodexSessionRecoveryEvidence(input: {
+    session: CodexDurableSession;
+    ownerActivityRef: ActivityRef;
+    evidence: Record<string, unknown>;
+    now?: Date;
+}): CodexSessionRecoveryEvidence;
+export declare function readCodexSessionRecoveryEvidence(session: CodexDurableSession): CodexSessionRecoveryEvidence | null;
+export declare function updateCodexTaskSession(session: CodexDurableSession, update: (metadata: CodexSessionMetadata) => CodexSessionMetadata): CodexDurableSession;
+export declare function recordCodexTaskSessionThread(session: CodexDurableSession, threadId: string, now?: Date): CodexDurableSession;
+export declare function markCodexTaskSessionArchived(session: CodexDurableSession, now?: Date): CodexDurableSession;
+export type CodexSessionArchiveIncident = {
+    version: 1;
+    kind: "thread_archive_failed";
+    occurred_at: string;
+};
+export declare function recordCodexSessionArchiveFailure(session: CodexDurableSession, now?: Date): CodexSessionArchiveIncident;
+export declare function readCodexSessionArchiveIncident(session: CodexDurableSession): CodexSessionArchiveIncident | null;
+export declare function acquireCodexTaskSessionLock(session: CodexDurableSession): () => void;
+//# sourceMappingURL=session-store.d.ts.map