@xfey/tutti 0.1.67 → 0.1.69

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

@@ -1,4 +1,5 @@
 import type { ExecutionRuntimeSnapshot, MessageProjection, RunResultProjection, TaskDetailProjection, WorklistProjection } from "@tutti/shared/schemas/api";
+import type { RecentReferenceContext } from "../reference-context-types.js";
 import type { ClarificationRequestPayload, TaskContractProjection } from "@tutti/shared/schemas/api";
 import type { ProjectDocKey } from "@tutti/shared/schemas/api";
 import type { ActivityRef, ClarificationRoundRef, ClarificationThreadRef, MessageId, TaskId, TaskModuleId, WorkflowInvocationRef } from "@tutti/shared/ids";
@@ -80,6 +81,7 @@ export type TaskCompileWorkflowInput = {
     workflow_ref: WorkflowInvocationRef;
     scratchpad: ScratchpadWorkflowSnapshot;
     worklist: WorklistProjection;
+    recent_references?: RecentReferenceContext[];
     clarification_rounds?: Array<{
         request_payload: ClarificationRequestPayload;
         answer_messages: TaskCompilePromptClarificationMessage[];
@@ -113,6 +115,7 @@ export type TaskCompilePromptInput = {
             }>;
         }>;
     };
+    recent_references?: RecentReferenceContext[];
     clarification_rounds?: Array<{
         request: {
             title?: string;

package/dist/providers/openai/app-server/json-rpc.js

@@ -1,5 +1,6 @@
 import { StringDecoder } from "node:string_decoder";
 import { redactText } from "@tutti/shared/utils";
+const PROCESS_EXIT_STDERR_EXCERPT_MAX_LENGTH = 500;
 export class CodexAppServerProtocolError extends Error {
     code;
     constructor(message, code) {
@@ -21,6 +22,16 @@ function normalizeProtocolError(method, error) {
     const message = typeof rawMessage === "string" ? redactText(rawMessage) : "protocol_error";
     return new CodexAppServerProtocolError(`Codex app-server request failed: ${method}: ${code}: ${message}`, "request_failed");
 }
+function processExitStderrExcerpt(value) {
+    const normalized = redactText(value).replace(/\s+/gu, " ").trim();
+    if (normalized.length === 0) {
+        return "";
+    }
+    if (normalized.length <= PROCESS_EXIT_STDERR_EXCERPT_MAX_LENGTH) {
+        return normalized;
+    }
+    return `${normalized.slice(0, PROCESS_EXIT_STDERR_EXCERPT_MAX_LENGTH)}...`;
+}
 export class CodexAppServerJsonRpcClient {
     child;
     options;
@@ -47,7 +58,8 @@ export class CodexAppServerJsonRpcClient {
         });
         child.on("exit", (code, signal) => {
             this.closed = true;
-            this.rejectAll(new CodexAppServerProtocolError(`Codex app-server exited before request completed: code=${code ?? "null"} signal=${signal ?? "null"}`, "process_exited"));
+            const stderrExcerpt = processExitStderrExcerpt(this.stderrText);
+            this.rejectAll(new CodexAppServerProtocolError(`Codex app-server exited before request completed: code=${code ?? "null"} signal=${signal ?? "null"}${stderrExcerpt === "" ? "" : ` stderr=${stderrExcerpt}`}`, "process_exited"));
         });
         child.on("error", (error) => {
             this.closed = true;

package/dist/providers/openai/app-server/linux-sandbox-readiness.js

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { CODEX_APP_SERVER_COMMAND } from "../codex-app-server.js";
+import { buildCodexCliProcessPlan } from "../codex-app-server.js";
 import { createCodexSpawnEnv } from "./runtime-helpers.js";
 const DEFAULT_PROBE_TIMEOUT_MS = 10_000;
 export const CODEX_LINUX_SANDBOX_GUIDANCE = "Install bubblewrap. On Ubuntu 24.04, also install apparmor-profiles and apparmor-utils and load the distribution bwrap-userns-restrict profile. Then run `tutti doctor` again.";
@@ -74,9 +74,12 @@ export function inspectCodexLinuxSandboxReadiness(options = {}) {
         const codexHome = join(tempRoot, "codex-home");
         mkdirSync(codexHome, { recursive: true, mode: 0o700 });
         const runProbe = options.runProbe ?? defaultProbeRunner;
-        return classifyProbeResult(runProbe({
-            command: options.codexCommand ?? CODEX_APP_SERVER_COMMAND,
+        const processPlan = buildCodexCliProcessPlan({
             args: ["sandbox", "--", "/bin/true"],
+            ...(options.codexCommand === undefined ? {} : { codexCommand: options.codexCommand }),
+        });
+        return classifyProbeResult(runProbe({
+            ...processPlan,
             cwd: tempRoot,
             env: createCodexSpawnEnv(codexHome, options.baseEnv ?? process.env),
             timeoutMs: options.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS,

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

@@ -120,9 +120,9 @@ export async function runCodexAppServerReadOnlyProcedure(options) {
     const processPlan = buildCodexAppServerProcessPlan({
         codexHome,
         configOverrides: buildCodexAppServerProviderConfigOverrides(options),
+        ...(options.codexCommand === undefined ? {} : { codexCommand: options.codexCommand }),
     });
-    const command = options.codexCommand ?? processPlan.command;
-    const child = spawn(command, processPlan.args, {
+    const child = spawn(processPlan.command, processPlan.args, {
         cwd: process.cwd(),
         env: createCodexSpawnEnv(codexHome, options.baseEnv ?? process.env),
         stdio: "pipe",

package/dist/providers/openai/app-server/smoke.js

@@ -25,9 +25,9 @@ export async function runCodexAppServerNoWriteSmoke(options) {
     const processPlan = buildCodexAppServerProcessPlan({
         codexHome,
         configOverrides: buildCodexAppServerProviderConfigOverrides(options),
+        ...(options.codexCommand === undefined ? {} : { codexCommand: options.codexCommand }),
     });
-    const command = options.codexCommand ?? processPlan.command;
-    const child = spawn(command, processPlan.args, {
+    const child = spawn(processPlan.command, processPlan.args, {
         cwd: process.cwd(),
         env: createCodexSpawnEnv(codexHome, options.baseEnv ?? process.env),
         stdio: "pipe",

package/dist/providers/openai/app-server/workspace-write-run.js

@@ -196,9 +196,9 @@ export async function runCodexAppServerWorkspaceWriteRun(options) {
     const processPlan = buildCodexAppServerProcessPlan({
         codexHome,
         configOverrides: buildCodexAppServerProviderConfigOverrides(options),
+        ...(options.codexCommand === undefined ? {} : { codexCommand: options.codexCommand }),
     });
-    const command = options.codexCommand ?? processPlan.command;
-    const child = spawn(command, processPlan.args, {
+    const child = spawn(processPlan.command, processPlan.args, {
         cwd: process.cwd(),
         env: createCodexSpawnEnv(codexHome, options.baseEnv ?? process.env),
         stdio: "pipe",

package/dist/providers/openai/codex-app-server.d.ts

@@ -1,3 +1,4 @@
+export declare const CODEX_APP_SERVER_ENTRYPOINT: string;
 export declare const CODEX_APP_SERVER_COMMAND: string;
 export declare const CODEX_APP_SERVER_LISTEN_URL: "stdio://";
 export declare const CODEX_APP_SERVER_CLIENT_NAME: "tutti_host";
@@ -73,8 +74,13 @@ export type CodexAppServerTurnStartTemplatePlan = {
 };
 export type BuildCodexAppServerProcessPlanOptions = {
     codexHome: string;
+    codexCommand?: string;
     configOverrides?: readonly CodexAppServerConfigOverride[];
 };
+export type CodexCliProcessPlan = {
+    command: string;
+    args: string[];
+};
 export type CodexAppServerNoWriteSmokePlan = {
     process: CodexAppServerProcessPlan;
     initialize: CodexAppServerRequestPlan<"initialize", CodexAppServerInitializeRequestParams>;
@@ -107,6 +113,10 @@ export declare const CODEX_NO_WRITE_SMOKE_OUTPUT_SCHEMA: {
 export declare function createCodexAppServerProcessEnv(options: {
     codexHome: string;
 }): Record<string, string>;
+export declare function buildCodexCliProcessPlan(options: {
+    args: readonly string[];
+    codexCommand?: string;
+}): CodexCliProcessPlan;
 export declare function buildCodexAppServerProcessPlan(options: BuildCodexAppServerProcessPlanOptions): CodexAppServerProcessPlan;
 export declare function createCodexAppServerNoWriteSmokePlan(options: CodexNoWriteSmokePlanOptions): CodexAppServerNoWriteSmokePlan;
 export declare class CodexAppServerJsonlParseError extends Error {

package/dist/providers/openai/codex-app-server.js

@@ -2,7 +2,8 @@ import { createRequire } from "node:module";
 import { dirname, isAbsolute, join } from "node:path";
 import { DEFAULT_OPENAI_MODEL } from "./model-config.js";
 const require = createRequire(import.meta.url);
-export const CODEX_APP_SERVER_COMMAND = join(dirname(require.resolve("@openai/codex/package.json")), "bin", "codex.js");
+export const CODEX_APP_SERVER_ENTRYPOINT = join(dirname(require.resolve("@openai/codex/package.json")), "bin", "codex.js");
+export const CODEX_APP_SERVER_COMMAND = process.execPath;
 export const CODEX_APP_SERVER_LISTEN_URL = "stdio://";
 export const CODEX_APP_SERVER_CLIENT_NAME = "tutti_host";
 export const CODEX_APP_SERVER_CLIENT_TITLE = "Tutti Host";
@@ -37,12 +38,28 @@ export function createCodexAppServerProcessEnv(options) {
         CODEX_HOME: options.codexHome,
     };
 }
-export function buildCodexAppServerProcessPlan(options) {
-    const args = ["app-server", "--listen", CODEX_APP_SERVER_LISTEN_URL];
-    pushConfigOverrides(args, options.configOverrides ?? []);
+export function buildCodexCliProcessPlan(options) {
+    if (options.codexCommand !== undefined) {
+        assertNonEmpty(options.codexCommand, "codexCommand");
+        return {
+            command: options.codexCommand,
+            args: [...options.args],
+        };
+    }
     return {
         command: CODEX_APP_SERVER_COMMAND,
-        args,
+        args: [CODEX_APP_SERVER_ENTRYPOINT, ...options.args],
+    };
+}
+export function buildCodexAppServerProcessPlan(options) {
+    const codexArgs = ["app-server", "--listen", CODEX_APP_SERVER_LISTEN_URL];
+    pushConfigOverrides(codexArgs, options.configOverrides ?? []);
+    const processPlan = buildCodexCliProcessPlan({
+        args: codexArgs,
+        ...(options.codexCommand === undefined ? {} : { codexCommand: options.codexCommand }),
+    });
+    return {
+        ...processPlan,
         env: createCodexAppServerProcessEnv({ codexHome: options.codexHome }),
         transport: {
             kind: "stdio",

package/dist/run-pipeline/task-run-invocation.js

@@ -6,6 +6,9 @@ function taskContractRunInput(input) {
         title: input.task.title,
         goal: input.task_detail.detail.contract.goal,
         scope: input.task_detail.detail.contract.scope,
+        ...(input.recent_references === undefined || input.recent_references.length === 0
+            ? {}
+            : { recent_references: input.recent_references }),
     };
 }
 function initialTaskRunInput(input) {

package/dist/server-shell/cli/host-server-runtime.js

@@ -283,7 +283,7 @@ export async function startForegroundHostServer(options) {
                 return await resolution.model.answer(input);
             },
         },
-        onScratchpadSourceChanged: () => controlPlane.notifyScratchpadSourceChanged(),
+        onScratchpadSourceChanged: (message) => controlPlane.notifyScratchpadSourceChanged(message),
         now,
     });
     let close = async () => { };

package/dist/server-shell/http/routes/project-api/messages-routes.js

@@ -71,7 +71,7 @@ export function registerMessagesRoutes(app, { options, workspaceEvents, }) {
                 },
                 invalidates: mainChatMessageInvalidates(),
             });
-            options.controlPlane?.notifyScratchpadSourceChanged();
+            options.controlPlane?.notifyScratchpadSourceChanged(execution.result.message);
             options.chatAssistant?.enqueue({ message: execution.result.message });
         }
         return response;

package/dist/server-shell/http/routes/project-api/reference-files-routes.js

@@ -137,7 +137,7 @@ export function registerReferenceFilesRoutes(app, { options, workspaceEvents, })
                     },
                     invalidates,
                 });
-                options.controlPlane?.notifyScratchpadSourceChanged();
+                options.controlPlane?.notifyScratchpadSourceChanged(execution.result.message);
                 options.controlPlane?.startReferenceSummaryRefresh({
                     paths: [execution.result.file.path],
                 });

package/dist/server-shell/local-console/invocation-context.d.ts

@@ -19,10 +19,12 @@ export declare function createDesktopLocalConsoleInvocationContext(options: {
 export declare function createLocalConsoleServiceEnvironment(options: {
     env: NodeJS.ProcessEnv;
     tuttiHome: string;
+    runtimeExecutablePath?: string;
 }): NodeJS.ProcessEnv;
 export declare function createLocalConsoleOperationEnvironment(options: {
     serviceEnvironment: NodeJS.ProcessEnv;
     invocationEnvironment: LocalConsoleInvocationEnvironment;
     tuttiHome: string;
+    runtimeExecutablePath?: string;
 }): NodeJS.ProcessEnv;
 //# sourceMappingURL=invocation-context.d.ts.map

package/dist/server-shell/local-console/invocation-context.js

@@ -1,4 +1,4 @@
-import { resolve } from "node:path";
+import { delimiter, dirname, resolve } from "node:path";
 export const LOCAL_CONSOLE_INVOCATION_ENV_KEYS = [
     "DBUS_SESSION_BUS_ADDRESS",
     "DISPLAY",
@@ -12,6 +12,12 @@ export const LOCAL_CONSOLE_INVOCATION_ENV_KEYS = [
     "WAYLAND_DISPLAY",
     "XDG_CURRENT_DESKTOP",
 ];
+function mergeExecutablePaths(values, runtimeExecutablePath) {
+    const entries = [dirname(runtimeExecutablePath), ...values.flatMap((value) => value?.split(delimiter) ?? [])]
+        .map((entry) => entry.trim())
+        .filter((entry) => entry !== "");
+    return [...new Set(entries)].join(delimiter);
+}
 export function collectLocalConsoleInvocationEnvironment(env) {
     const environment = {};
     for (const key of LOCAL_CONSOLE_INVOCATION_ENV_KEYS) {
@@ -52,12 +58,15 @@ export function createLocalConsoleServiceEnvironment(options) {
             environment[key] = value;
         }
     }
+    environment.PATH = mergeExecutablePaths([environment.PATH], options.runtimeExecutablePath ?? process.execPath);
     return environment;
 }
 export function createLocalConsoleOperationEnvironment(options) {
+    const executablePath = mergeExecutablePaths([options.invocationEnvironment.PATH, options.serviceEnvironment.PATH], options.runtimeExecutablePath ?? process.execPath);
     return {
         ...options.serviceEnvironment,
         ...options.invocationEnvironment,
+        PATH: executablePath,
         TUTTI_HOME: options.tuttiHome,
     };
 }

package/dist/workspace-ops/index.d.ts

@@ -5,7 +5,7 @@ export { collectProjectSourceDiff, createAcceptedCheckpoint, inspectProjectWorks
 export { initializeProjectDocs, readProjectDocsInitializationStatus, syncProjectDocs, } from "./project-docs.js";
 export { uploadReferenceFile } from "./reference-files.js";
 export { referenceFileCategoryForPath, referenceFileSourceForPath, referenceMediaTypeForPath, referenceTuttiGroupForPath, } from "./reference-metadata.js";
-export { readReferenceSummaryIndex, readReferenceSummaryTargets, referenceSummaryProjectionForEntry, updateReferenceSummaries, } from "./reference-summaries.js";
+export { readReferenceSummaryEntries, readReferenceSummaryIndex, readReferenceSummaryTargets, referenceSummaryProjectionForEntry, updateReferenceSummaries, } from "./reference-summaries.js";
 export { readViewerAsset, readViewerFile, readViewerSnapshot, readViewerTree } from "./viewer.js";
 export type { WorkspaceOpsErrorCode } from "./errors.js";
 export type { AcceptedCheckpointRecoveryResult, AcceptedCheckpointResult, CreateAcceptedCheckpointOptions, InitializeProjectDocsOptions, InitializeProjectDocsResult, ProjectDocsInitializationContext, ProjectDocsInitializationDocument, ProjectDocsInitializationStatus, ProjectWorkspaceInspection, ReadViewerAssetOptions, ReadViewerFileOptions, ReadViewerTreeOptions, ReferenceFileCategory, ReferenceSummaryProjection, ReferenceSummaryRecord, ReferenceSummaryStatus, ReferenceSummaryTarget, RunDiffSummary, SyncProjectDocsResult, SyncProjectDocsUpdate, UpdateReferenceSummariesOptions, UpdateReferenceSummariesResult, UploadReferenceFileOptions, UploadReferenceFileResult, ViewerAssetResult, ViewerAssetVariant, ViewerEntryKind, ViewerFileContent, ViewerFileResult, ViewerRepoSnapshot, ViewerTreeEntry, ViewerTreeResult, WorkspaceViewerOptions, } from "./types.js";

package/dist/workspace-ops/index.js

@@ -5,6 +5,6 @@ export { collectProjectSourceDiff, createAcceptedCheckpoint, inspectProjectWorks
 export { initializeProjectDocs, readProjectDocsInitializationStatus, syncProjectDocs, } from "./project-docs.js";
 export { uploadReferenceFile } from "./reference-files.js";
 export { referenceFileCategoryForPath, referenceFileSourceForPath, referenceMediaTypeForPath, referenceTuttiGroupForPath, } from "./reference-metadata.js";
-export { readReferenceSummaryIndex, readReferenceSummaryTargets, referenceSummaryProjectionForEntry, updateReferenceSummaries, } from "./reference-summaries.js";
+export { readReferenceSummaryEntries, readReferenceSummaryIndex, readReferenceSummaryTargets, referenceSummaryProjectionForEntry, updateReferenceSummaries, } from "./reference-summaries.js";
 export { readViewerAsset, readViewerFile, readViewerSnapshot, readViewerTree } from "./viewer.js";
 //# sourceMappingURL=index.js.map

package/dist/workspace-ops/reference-files.js

@@ -6,40 +6,102 @@ import { WorkspaceOpsError } from "./errors.js";
 import { classifyReferenceUpload } from "./reference-metadata.js";
 import { commitOwnedPaths, requireOwnedPathsWriteReady } from "./system-commits.js";
 import { readViewerFile } from "./viewer.js";
-function commandSuffix(commandId) {
-    return commandId.slice(-8).toLowerCase();
-}
-function sanitizeReferenceFileName(fileName, commandId) {
-    const raw = fileName.trim();
-    if (raw.length === 0) {
+const MAX_REFERENCE_FILE_NAME_BYTES = 240;
+const WINDOWS_RESERVED_FILE_STEMS = /^(?:con|prn|aux|nul|clock\$|com[1-9]|lpt[1-9])$/iu;
+const WINDOWS_INVALID_FILE_NAME_CHARACTERS = /[<>:"|?*]/u;
+function normalizeReferenceFileName(fileName) {
+    if (fileName.length === 0 || fileName.trim().length === 0) {
         throw new WorkspaceOpsError("validation_failed", "Reference file name cannot be empty");
     }
-    if (raw.includes("/") || raw.includes("\\")) {
+    if (fileName !== fileName.trim()) {
+        throw new WorkspaceOpsError("validation_failed", "Reference file name must not have leading or trailing whitespace");
+    }
+    const normalized = fileName.normalize("NFC");
+    if (normalized.includes("/") || normalized.includes("\\")) {
         throw new WorkspaceOpsError("validation_failed", "Reference file name must not include directories");
     }
-    const rawClassification = classifyViewerPath(raw);
+    if (WINDOWS_INVALID_FILE_NAME_CHARACTERS.test(normalized)) {
+        throw new WorkspaceOpsError("validation_failed", "Reference file name contains a platform-reserved character");
+    }
+    if (normalized.endsWith(".") || /^\.+$/u.test(normalized)) {
+        throw new WorkspaceOpsError("validation_failed", "Reference file name must not end with a dot or consist only of dots");
+    }
+    const reservedStem = normalized.split(".", 1)[0] ?? normalized;
+    if (WINDOWS_RESERVED_FILE_STEMS.test(reservedStem)) {
+        throw new WorkspaceOpsError("validation_failed", "Reference file name is reserved by the platform");
+    }
+    if (Buffer.byteLength(normalized, "utf8") > MAX_REFERENCE_FILE_NAME_BYTES) {
+        throw new WorkspaceOpsError("validation_failed", `Reference file name cannot exceed ${MAX_REFERENCE_FILE_NAME_BYTES} UTF-8 bytes`);
+    }
+    const rawClassification = classifyViewerPath(normalized);
     if (rawClassification.kind === "rejected") {
         throw new WorkspaceOpsError("validation_failed", `Reference file name is rejected: ${rawClassification.reason_code}`, { reason_code: rawClassification.reason_code });
     }
-    const extension = extname(raw)
-        .toLowerCase()
-        .replace(/[^.a-z0-9]/gu, "");
-    const rawStem = extension.length > 0 ? raw.slice(0, -extension.length) : raw;
-    const stem = rawStem
-        .replace(/[^A-Za-z0-9._-]+/gu, "-")
-        .replace(/-{2,}/gu, "-")
-        .replace(/^[.-]+/u, "")
-        .replace(/[.-]+$/u, "");
-    if (stem.length === 0) {
-        throw new WorkspaceOpsError("validation_failed", "Reference file name cannot be normalized");
-    }
-    const safeName = `${stem}-${commandSuffix(commandId)}${extension}`;
-    const path = `${REFERENCE_DIRECTORY_PATH}/${safeName}`;
+    return normalized;
+}
+function truncateUtf8(value, maxBytes) {
+    let result = "";
+    let bytes = 0;
+    for (const character of value) {
+        const characterBytes = Buffer.byteLength(character, "utf8");
+        if (bytes + characterBytes > maxBytes) {
+            break;
+        }
+        result += character;
+        bytes += characterBytes;
+    }
+    return result;
+}
+function conflictFileName(fileName, suffix) {
+    const extension = extname(fileName);
+    const stem = extension.length === 0 ? fileName : fileName.slice(0, -extension.length);
+    const marker = `-${suffix}`;
+    const maxStemBytes = MAX_REFERENCE_FILE_NAME_BYTES -
+        Buffer.byteLength(marker, "utf8") -
+        Buffer.byteLength(extension, "utf8");
+    if (maxStemBytes <= 0) {
+        throw new WorkspaceOpsError("validation_failed", "Reference file name is too long to resolve a path conflict");
+    }
+    const boundedStem = truncateUtf8(stem, maxStemBytes).replace(/[.\s]+$/u, "");
+    if (boundedStem.length === 0) {
+        throw new WorkspaceOpsError("validation_failed", "Reference file name cannot be disambiguated safely");
+    }
+    return `${boundedStem}${marker}${extension}`;
+}
+function commandSuffixes(commandId) {
+    const normalized = commandId.toLowerCase().replace(/[^a-z0-9]/gu, "");
+    const lengths = [8, 12, 16, 24];
+    return [...new Set(lengths.map((length) => normalized.slice(-length)).filter(Boolean))];
+}
+function sameFileContent(path, content) {
+    return existsSync(path) && readFileSync(path).equals(content);
+}
+function resolveReferenceFileName(options) {
+    const originalPath = join(options.workspaceRoot, ...options.directoryPath.split("/"), options.fileName);
+    if (!existsSync(originalPath) || sameFileContent(originalPath, options.content)) {
+        return options.fileName;
+    }
+    for (const suffix of commandSuffixes(options.commandId)) {
+        const candidate = conflictFileName(options.fileName, suffix);
+        const candidatePath = join(options.workspaceRoot, ...options.directoryPath.split("/"), candidate);
+        if (!existsSync(candidatePath) || sameFileContent(candidatePath, options.content)) {
+            return candidate;
+        }
+    }
+    throw new WorkspaceOpsError("conflict", "Reference file name conflicts with an existing upload");
+}
+function requireSafeReferencePath(directoryPath, fileName) {
+    const path = `${directoryPath}/${fileName}`;
     const classification = classifyViewerPath(path);
     if (classification.kind === "rejected") {
         throw new WorkspaceOpsError("validation_failed", `Reference file path is rejected: ${classification.reason_code}`, { reason_code: classification.reason_code });
     }
-    return safeName;
+}
+function markdownLinkLabel(value) {
+    return value.replaceAll("[", "\\[").replaceAll("]", "\\]");
+}
+function markdownLinkPath(value) {
+    return value.split("/").map(encodeURIComponent).join("/");
 }
 function appendReferenceIndexEntry(options) {
     const indexPath = join(options.workspaceRoot, "docs", "reference", "README.md");
@@ -63,10 +125,10 @@ function appendReferenceIndexEntry(options) {
         content = `${content.trimEnd()}\n\n## Images\n\n`;
     }
     const relativePath = posix.relative(REFERENCE_DIRECTORY_PATH, options.repoPath);
-    const link = `./${relativePath}`;
+    const link = `./${markdownLinkPath(relativePath)}`;
     const note = options.note?.trim();
     const description = note === undefined || note.length === 0 ? "" : ` - ${note}`;
-    const line = `- [${options.fileName}](${link})${description}\n`;
+    const line = `- [${markdownLinkLabel(options.fileName)}](${link})${description}\n`;
     if (content.includes(`](${link})`)) {
         writeFileSync(indexPath, content, "utf8");
         return;
@@ -89,24 +151,26 @@ export function uploadReferenceFile(options) {
     if (options.content.byteLength > MAX_REFERENCE_UPLOAD_BYTES) {
         throw new WorkspaceOpsError("validation_failed", `Reference file content cannot exceed ${MAX_REFERENCE_UPLOAD_BYTES} bytes`);
     }
-    const safeName = sanitizeReferenceFileName(options.fileName, options.commandId);
+    const normalizedName = normalizeReferenceFileName(options.fileName);
     const classification = classifyReferenceUpload({
-        fileName: options.fileName,
+        fileName: normalizedName,
         content: options.content,
         ...(options.mediaType === undefined ? {} : { mediaType: options.mediaType }),
     });
+    const safeName = resolveReferenceFileName({
+        workspaceRoot: options.workspaceRoot,
+        directoryPath: classification.directoryPath,
+        fileName: normalizedName,
+        commandId: options.commandId,
+        content: options.content,
+    });
+    requireSafeReferencePath(classification.directoryPath, safeName);
     const referenceDirectory = join(options.workspaceRoot, ...classification.directoryPath.split("/"));
     const repoPath = `${classification.directoryPath}/${safeName}`;
     const filesystemPath = join(referenceDirectory, safeName);
     requireOwnedPathsWriteReady(options.workspaceRoot, [REFERENCE_INDEX_PATH, repoPath]);
     mkdirSync(referenceDirectory, { recursive: true });
-    if (existsSync(filesystemPath)) {
-        const existing = readFileSync(filesystemPath);
-        if (!existing.equals(options.content)) {
-            throw new WorkspaceOpsError("conflict", "Reference file path already exists with different content");
-        }
-    }
-    else {
+    if (!existsSync(filesystemPath)) {
         writeFileSync(filesystemPath, options.content);
     }
     appendReferenceIndexEntry({

package/dist/workspace-ops/reference-summaries.d.ts

@@ -7,6 +7,11 @@ export declare function referenceSummaryProjectionForEntry(options: {
     entry: ViewerTreeEntry;
     summaries: ReferenceSummaryIndex;
 }): ReferenceSummaryProjection;
+export declare function readReferenceSummaryEntries(options: {
+    workspaceRoot: string;
+    paths?: string[];
+    now?: () => Date;
+}): ReferenceSummaryTarget[];
 export declare function readReferenceSummaryTargets(options: {
     workspaceRoot: string;
     paths?: string[];

package/dist/workspace-ops/reference-summaries.js

@@ -138,8 +138,7 @@ export function referenceSummaryProjectionForEntry(options) {
         ...(record.source_blob_oid === undefined ? {} : { source_blob_oid: record.source_blob_oid }),
         ...(record.read_paths === undefined ? {} : { read_paths: record.read_paths }),
     };
-    if (record.source_blob_oid !== undefined &&
-        options.entry.blob_oid !== undefined &&
+    if (options.entry.blob_oid !== undefined &&
         record.source_blob_oid !== options.entry.blob_oid) {
         return {
             status: "stale",
@@ -179,7 +178,7 @@ function readReferenceFileEntries(options) {
         .filter((entry) => entry.blob_oid !== undefined && entry.size_bytes !== undefined)
         .sort((left, right) => left.path.localeCompare(right.path, "en", { sensitivity: "base" }));
 }
-export function readReferenceSummaryTargets(options) {
+export function readReferenceSummaryEntries(options) {
     const summaries = readReferenceSummaryIndex({ workspaceRoot: options.workspaceRoot });
     const requested = options.paths === undefined ? undefined : new Set(options.paths);
     return readReferenceFileEntries(options)
@@ -198,8 +197,10 @@ export function readReferenceSummaryTargets(options) {
                 : { media_type: referenceMediaTypeForPath(entry.path) }),
             summary,
         };
-    })
-        .filter((target) => target.summary.status !== "available");
+    });
+}
+export function readReferenceSummaryTargets(options) {
+    return readReferenceSummaryEntries(options).filter((target) => target.summary.status !== "available");
 }
 function removeSummarySection(content) {
     const headingPattern = /(^|\n)## Summaries\n/u;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfey/tutti",
-  "version": "0.1.67",
+  "version": "0.1.69",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -29,7 +29,7 @@
     "@fastify/cors": "^11.2.0",
     "@fastify/static": "^9.1.3",
     "@fastify/websocket": "^11.2.0",
-    "@openai/codex": "^0.142.5",
+    "@openai/codex": "^0.147.0",
     "@sinclair/typebox": "^0.34.49",
     "@tutti/relay-client": "0.0.0",
     "@tutti/shared": "0.0.0",

package/prompts/README.md

@@ -15,7 +15,7 @@ Prompt / skill 改造后的 live 实验计划与记录见 [prompt-flow-experimen
 
 - `procedures/`：`scratchpad_refresh`、`project_brief_refresh`、`task_compile`、`project_context_bootstrap`、`context_sync`、`reference_summary_refresh`、`follow_up_check` 等 Procedure / workflow prompt。
 - `artifacts/`：候选实现完成后的 transient Artifact applicability 判断；只接收 bounded task / diff / repo evidence，不写回 Task contract 或 repo。
-- `runs/`：正式 task `Run`、task-bound continuation 与 pipeline self-correction retry 等 Run pipeline prompt；provider transient retry 不新增 prompt，而是复用失败 attempt 的同一 prompt family。所有 Run prompt都以持久 project workspace为 cwd contract，不设计 promotion reconcile prompt。
+- `runs/`：正式 task `Run`、task-bound continuation 与 pipeline self-correction retry 等 Run pipeline prompt；task contract 可附带 receipt-derived compact `recent_references`，两类 retry 都保留它。provider transient retry 不新增 prompt，而是复用失败 attempt 的同一 prompt family。所有 Run prompt都以持久 project workspace为 cwd contract，不设计 promotion reconcile prompt。
 - `codex/`：Codex app-server smoke 等 adapter / spike prompt。
 - `skills/`：Tutti packaged built-in Codex skills；由 server-side app-server skill selection 选择，不在 Web Skills 页面展示，也不保存 user skills。
 - `chat-assistant.md`：主群聊与 clarification round 内 `@tutti` 只读项目问答 prompt；它不是 Procedure / Run prompt。

package/prompts/procedures/README.md

@@ -14,7 +14,7 @@
 
 `project_context_bootstrap` 的 provider path 只让 Codex app-server read-only adapter 生成缺失文档内容；如果该计划不可用，Control Plane 会回退到本地保守模板。
 `project_context_bootstrap` 的 read-only 输入只包含项目名、非空时的 `missing_docs` 与刷新后的 Scratchpad；prompt 会要求 app-server 只读探索仓库，并可通过 `read-project-docs` / `read-references` skill 按需读取现有文档和参考文件。输出只包含 `documents[].doc_key/content`，固定 path 由 Control Plane 后处理生成。
-`task_compile` 的 read-only 输入只包含 durable context 固定的五字段 Scratchpad、当前 Worklist 和可选完整有序 `clarification_rounds`；workflow ref、activity ref、Scratchpad / Worklist 审计字段、排序字段、时间戳和完整 message projection 不进入 prompt。每次 continuation 仍读取同一 pinned Scratchpad，不读取并行变化的 Current Scratchpad；later round 可以纠正 earlier round，明确撤回时允许空 proposal 正常结束。prompt 暴露 `read-project-docs` / `read-worklist` / `read-references` skills 供 app-server 必要时读取项目上下文文件、既有任务 contract / latest result 或相关 reference 正文；Scratchpad 和 Worklist 紧凑视图仍以直接输入为准，不通过 skill 重读 Scratchpad。provider raw output 使用 `{ result: ... }` 互斥分支；proposal 分支用 `module_ref` 指向新模块或既有模块，task 只输出 `title / goal / scope`，runner adapter 再映射为 Control Plane 内部 proposal：`goal` 同时作为内部 task summary 和 contract goal，`scope` 作为内部 contract scope。
+`task_compile` 的 read-only 输入只包含 durable context 固定的五字段 Scratchpad、当前 Worklist、可选 compact `recent_references` 和可选完整有序 `clarification_rounds`；reference 项只含 path、最终 name 与 available/unavailable summary，不含 blob/message/workflow audit fields。每次 continuation 仍读取同一 pinned Scratchpad 与 source set，不读取并行变化的 Current Scratchpad或 boundary 后的新上传；later round 可以纠正 earlier round，明确撤回时允许空 proposal 正常结束。prompt 暴露 `read-project-docs` / `read-worklist` / `read-references` skills 供 app-server 必要时读取项目上下文文件、既有任务 contract / latest result 或相关 reference 正文；Scratchpad 和 Worklist 紧凑视图仍以直接输入为准，不通过 skill 重读 Scratchpad。provider raw output 使用 `{ result: ... }` 互斥分支；proposal 分支用 `module_ref` 指向新模块或既有模块，task 只输出 `title / goal / scope`，runner adapter 再映射为 Control Plane 内部 proposal：`goal` 同时作为内部 task summary 和 contract goal，`scope` 作为内部 contract scope。
 `context_sync` 没有 provider-facing direct input；workflow ref、activity ref、触发原因、安全元数据、checked paths、skipped paths 和 open questions 都不进入 prompt，只用于运行时追踪、调度或审计。prompt 说明通用文档同步目标、目标项目文档落点和 canonical docs 职责，由 app-server 主动探索 repo，并通过 `read-project-docs` / `read-worklist` / `read-references` skill 按需读取现有文档、正式任务上下文和参考文件。Worklist / task result 只作为阶段性完成背景和稳定结果线索，不写成长文档里的逐任务流水。
 `context_sync` prompt 只返回 `summary` 与 `updates[].path/content`；空 `updates` 表示无需同步，非空 `updates` 由 Control Plane 调用 `workspace-ops` 做 path policy、mainline clean 检查、文件写入和 Git commit。
 `project_brief_refresh` 只走 OpenAI SDK structured output，不使用 Codex app-server，不读取 repo 或 skills。它接收四个 baseline Project Docs 的 bounded source 内容与状态，输出 `product_summary / tech_summary / structure_summary / principles_summary`，由 Control Plane 写入 host-local `project_brief` projection；Project Docs 创建、同步、被成功 Run promotion 修改，或 provider setup 后需要 backfill 时可以触发。provider 不可用、source 不可用、brief 已经 fresh 或刷新失败都不影响 Project Docs 写入结果。

package/prompts/procedures/task-compile.md

@@ -20,13 +20,14 @@ You compile Tutti's Scratchpad into an append-only Worklist proposal for post-ba
 
 - `scratchpad` is the immutable five-field snapshot pinned when this task_compile workflow was submitted. It has already removed message ids, timestamps, activity refs, and refresh state.
 - `worklist.modules[]` is the current formal Worklist. Module `id` values are the only valid existing module keys. Module names and task titles are historical anchors for resolving short references in the current Scratchpad.
+- `recent_references`, when present, identifies human-uploaded files from the same pinned Scratchpad cycle and provides a terminal summary status for each source.
 - `clarification_rounds`, when present, contains every sealed workflow-bound clarification round for this same pinned Scratchpad, ordered from earliest to latest. Each round keeps its request separate from its ordered submitted answer messages.
 - Later clarification rounds may add to or correct earlier rounds. Interpret them chronologically without discarding the earlier context.
 - Concurrent main-chat discussion and the mutable Current Scratchpad are intentionally absent. Never assume that a short clarification answer applies to a newer chat direction, and never use skills to find concurrent chat to complete this workflow.
 - Treat the provided Scratchpad and Worklist as authoritative. Do not use skills to reread them.
 - Use `read-worklist` only when an existing task's contract or latest result would clarify the current task's subject, boundary, or delivery relationship. Do not duplicate tasks already covered by the Worklist.
 - Use `read-project-docs` or `read-references` only when task scope, acceptance, product intent, technical stack, repo structure, agent working rules, or reference contents matter and are not clear from direct input.
-- Reference upload events, file names, paths, and media types do not prove file contents. Read the relevant reference when its contents affect the task contract.
+- Use recent references when they materially inform the proposed work, and read the source when its summary is insufficient to freeze the task contract.
 - Preserve user-provided non-secret details when they are needed to execute or accept the task. Do not generalize them into vague labels.
 - Do not use web search, credentials, provider internals, raw logs, or Tutti runtime/internal paths.