@xfey/tutti 0.1.96 → 0.1.98

package/dist/workspace-ops/index.js

@@ -1,10 +1,11 @@
-export { DEFAULT_VIEWER_MAX_BYTES, MAX_REFERENCE_UPLOAD_BYTES, MAX_VIEWER_MAX_BYTES, PROJECT_DOC_PATHS, REFERENCE_IMAGE_ASSET_CACHE_VERSION, REFERENCE_IMAGE_PREVIEW_MAX_EDGE_PX, REFERENCE_IMAGE_THUMBNAIL_MAX_EDGE_PX, REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, REFERENCE_TUTTI_DIRECTORY_PATH, VIEWER_ASSET_READ_LIMIT_BYTES, VIEWER_HARD_READ_LIMIT_BYTES, WORKSPACE_OPS_MAINLINE_BRANCH, } from "./constants.js";
+export { DEFAULT_VIEWER_MAX_BYTES, MAX_REFERENCE_UPLOAD_BYTES, MAX_VIEWER_MAX_BYTES, PROJECT_DOC_PATHS, REFERENCE_IMAGE_ASSET_CACHE_VERSION, REFERENCE_IMAGE_PREVIEW_MAX_EDGE_PX, REFERENCE_IMAGE_THUMBNAIL_MAX_EDGE_PX, REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, VIEWER_ASSET_READ_LIMIT_BYTES, VIEWER_HARD_READ_LIMIT_BYTES, WORKSPACE_OPS_MAINLINE_BRANCH, } from "./constants.js";
 export { WorkspaceOpsError } from "./errors.js";
 export { commitOwnedPaths, requireOwnedPathsWriteReady } from "./system-commits.js";
 export { collectProjectSourceDiff, createAcceptedCheckpoint, inspectProjectWorkspace, recoverAcceptedCheckpoint, } from "./project-workspace.js";
 export { initializeProjectDocs, readProjectDocsInitializationStatus, syncProjectDocs, } from "./project-docs.js";
 export { uploadReferenceFile } from "./reference-files.js";
-export { referenceFileCategoryForPath, referenceFileSourceForPath, referenceMediaTypeForPath, referenceTuttiGroupForPath, } from "./reference-metadata.js";
+export { isReferenceFilePath, referenceFileCategoryForPath, referenceFolderGroupForPath, referenceMediaTypeForPath, } from "./reference-metadata.js";
+export { readReferenceFileEntries } from "./reference-tree.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/project-doc-templates.js

@@ -129,7 +129,7 @@ ${asBulletList([
                 ...repoHints.directories.map((directory) => `Top-level directory: \`${directory}/\``),
                 ...repoHints.root_files.map((file) => `Root file: \`${file}\``),
             ], "Repository structure is pending context sync.")}
-- Human-uploaded reference materials, when present, live under \`docs/reference/\`.
+- Shared reference materials maintained by project members and Tutti, when present, live under \`docs/reference/\`.
 
 ## Naming Conventions
 

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

@@ -110,7 +110,7 @@ function appendReferenceIndexEntry(options) {
         ? [
             "# Reference Files",
             "",
-            "Human-uploaded project reference files.",
+            "Shared project reference files maintained by project members and Tutti.",
             "",
             "## Files",
             "",
@@ -185,7 +185,8 @@ export function uploadReferenceFile(options) {
         paths: [REFERENCE_INDEX_PATH, repoPath],
         message: `Add reference file: ${safeName}`,
     });
-    const resolvedCommitOid = commitOid ?? readViewerFile({ workspaceRoot: options.workspaceRoot, path: repoPath }).snapshot.head.oid;
+    const resolvedCommitOid = commitOid ??
+        readViewerFile({ workspaceRoot: options.workspaceRoot, path: repoPath }).snapshot.head.oid;
     const file = readViewerFile({
         workspaceRoot: options.workspaceRoot,
         path: repoPath,

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

@@ -9,7 +9,7 @@ export declare function classifyReferenceUpload(options: {
     directoryPath: string;
 };
 export declare function referenceFileCategoryForPath(path: string): ReferenceFileCategory | undefined;
-export declare function referenceFileSourceForPath(path: string): "human_upload" | "tutti_output" | undefined;
-export declare function referenceTuttiGroupForPath(path: string): string | undefined;
+export declare function isReferenceFilePath(path: string): boolean;
+export declare function referenceFolderGroupForPath(path: string): string | undefined;
 export declare function referenceMediaTypeForPath(path: string): string | undefined;
 //# sourceMappingURL=reference-metadata.d.ts.map

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

@@ -1,5 +1,5 @@
-import { extname, posix } from "node:path";
-import { REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, REFERENCE_TUTTI_DIRECTORY_PATH, } from "./constants.js";
+import { extname } from "node:path";
+import { REFERENCE_DIRECTORY_PATH, REFERENCE_FILES_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, } from "./constants.js";
 const REFERENCE_IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp", ".gif"]);
 const REFERENCE_IMAGE_MEDIA_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
 function normalizeMediaType(mediaType) {
@@ -54,33 +54,19 @@ export function referenceFileCategoryForPath(path) {
     if (path.startsWith(`${REFERENCE_IMAGES_DIRECTORY_PATH}/`)) {
         return "image";
     }
-    if (path.startsWith(`${REFERENCE_FILES_DIRECTORY_PATH}/`)) {
-        return "file";
-    }
-    if (path.startsWith(`${REFERENCE_TUTTI_DIRECTORY_PATH}/`)) {
-        return "file";
-    }
-    if (posix.dirname(path) === REFERENCE_DIRECTORY_PATH && path !== REFERENCE_INDEX_PATH) {
+    if (isReferenceFilePath(path)) {
         return "file";
     }
     return undefined;
 }
-export function referenceFileSourceForPath(path) {
-    if (path.startsWith(`${REFERENCE_TUTTI_DIRECTORY_PATH}/`)) {
-        return "tutti_output";
-    }
-    if (path.startsWith(`${REFERENCE_FILES_DIRECTORY_PATH}/`) ||
-        path.startsWith(`${REFERENCE_IMAGES_DIRECTORY_PATH}/`) ||
-        (posix.dirname(path) === REFERENCE_DIRECTORY_PATH && path !== REFERENCE_INDEX_PATH)) {
-        return "human_upload";
-    }
-    return undefined;
+export function isReferenceFilePath(path) {
+    return path !== REFERENCE_INDEX_PATH && path.startsWith(`${REFERENCE_DIRECTORY_PATH}/`);
 }
-export function referenceTuttiGroupForPath(path) {
-    if (!path.startsWith(`${REFERENCE_TUTTI_DIRECTORY_PATH}/`)) {
+export function referenceFolderGroupForPath(path) {
+    if (!isReferenceFilePath(path)) {
         return undefined;
     }
-    const rest = path.slice(REFERENCE_TUTTI_DIRECTORY_PATH.length + 1);
+    const rest = path.slice(REFERENCE_DIRECTORY_PATH.length + 1);
     const [first, second] = rest.split("/");
     if (first === undefined || first.length === 0 || second === undefined) {
         return undefined;

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

@@ -1,10 +1,10 @@
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { redactText } from "@tutti/shared/utils";
-import { REFERENCE_DIRECTORY_PATH, REFERENCE_INDEX_PATH, } from "./constants.js";
+import { REFERENCE_INDEX_PATH } from "./constants.js";
 import { referenceFileCategoryForPath, referenceMediaTypeForPath } from "./reference-metadata.js";
+import { readReferenceFileEntries } from "./reference-tree.js";
 import { commitOwnedPaths, requireOwnedPathsWriteReady } from "./system-commits.js";
-import { readViewerTree } from "./viewer.js";
 const SUMMARY_SECTION_HEADING = "## Summaries";
 const SUMMARY_BLOCK_START = "<!-- tutti-reference-summaries:v1";
 const SUMMARY_BLOCK_END = "-->";
@@ -115,7 +115,7 @@ function readReferenceIndexContent(workspaceRoot) {
         return [
             "# Reference Files",
             "",
-            "Human-uploaded project reference files.",
+            "Shared project reference files maintained by project members and Tutti.",
             "",
             "## Files",
             "",
@@ -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 (options.entry.blob_oid !== undefined &&
-        record.source_blob_oid !== options.entry.blob_oid) {
+    if (options.entry.blob_oid !== undefined && record.source_blob_oid !== options.entry.blob_oid) {
         return {
             status: "stale",
             ...base,
@@ -165,14 +164,8 @@ export function referenceSummaryProjectionForEntry(options) {
         ...(record.summary === undefined ? {} : { text: record.summary }),
     };
 }
-function readReferenceFileEntries(options) {
-    const tree = readViewerTree({
-        workspaceRoot: options.workspaceRoot,
-        path: REFERENCE_DIRECTORY_PATH,
-        depth: 2,
-        ...(options.now === undefined ? {} : { now: options.now }),
-    });
-    return tree.items
+function readSummaryFileEntries(options) {
+    return readReferenceFileEntries({ workspaceRoot: options.workspaceRoot })
         .filter((entry) => entry.kind === "file")
         .filter((entry) => referenceFileCategoryForPath(entry.path) !== undefined)
         .filter((entry) => entry.blob_oid !== undefined && entry.size_bytes !== undefined)
@@ -181,7 +174,7 @@ function readReferenceFileEntries(options) {
 export function readReferenceSummaryEntries(options) {
     const summaries = readReferenceSummaryIndex({ workspaceRoot: options.workspaceRoot });
     const requested = options.paths === undefined ? undefined : new Set(options.paths);
-    return readReferenceFileEntries(options)
+    return readSummaryFileEntries(options)
         .filter((entry) => requested === undefined || requested.has(entry.path))
         .map((entry) => {
         const category = referenceFileCategoryForPath(entry.path) ?? "file";
@@ -239,7 +232,9 @@ function renderSummaryRecord(record) {
     return rendered;
 }
 function renderSummariesSection(records) {
-    const items = records.map(renderSummaryRecord).sort((left, right) => left.path.localeCompare(right.path, "en", { sensitivity: "base" }));
+    const items = records
+        .map(renderSummaryRecord)
+        .sort((left, right) => left.path.localeCompare(right.path, "en", { sensitivity: "base" }));
     const json = JSON.stringify({ items }, null, 2);
     const lines = [
         SUMMARY_SECTION_HEADING,
@@ -277,9 +272,8 @@ export function updateReferenceSummaries(options) {
         }
         existing.set(summary.path, rendered);
     }
-    const currentPaths = new Set(readReferenceFileEntries({
+    const currentPaths = new Set(readSummaryFileEntries({
         workspaceRoot: options.workspaceRoot,
-        ...(options.now === undefined ? {} : { now: options.now }),
     }).map((entry) => entry.path));
     const records = [...existing.values()].filter((record) => currentPaths.has(record.path));
     const nextContent = `${removeSummarySection(existingContent)}\n\n${renderSummariesSection(records)}\n`;

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

@@ -0,0 +1,11 @@
+import type { ViewerTreeEntry } from "./types.js";
+/**
+ * Enumerate every committed regular file in the shared Reference directory.
+ * The generic Repo Viewer intentionally keeps its bounded depth contract; this
+ * Reference-specific reader is the single recursive source for the API,
+ * summaries, and agent context.
+ */
+export declare function readReferenceFileEntries(options: {
+    workspaceRoot: string;
+}): ViewerTreeEntry[];
+//# sourceMappingURL=reference-tree.d.ts.map

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

@@ -0,0 +1,34 @@
+import { posix } from "node:path";
+import { REFERENCE_DIRECTORY_PATH } from "./constants.js";
+import { WorkspaceOpsError } from "./errors.js";
+import { entryKind, lsPath, lsTreeRecursive } from "./viewer-git.js";
+import { isPathAllowedForProjection } from "./viewer-paths.js";
+import { createViewerTreeEntry } from "./viewer-tree.js";
+/**
+ * Enumerate every committed regular file in the shared Reference directory.
+ * The generic Repo Viewer intentionally keeps its bounded depth contract; this
+ * Reference-specific reader is the single recursive source for the API,
+ * summaries, and agent context.
+ */
+export function readReferenceFileEntries(options) {
+    const root = lsPath(options.workspaceRoot, REFERENCE_DIRECTORY_PATH);
+    if (root === null) {
+        throw new WorkspaceOpsError("not_found", "Reference directory was not found");
+    }
+    if (entryKind(root) !== "directory") {
+        throw new WorkspaceOpsError("validation_failed", "Reference path is not a directory");
+    }
+    return lsTreeRecursive(options.workspaceRoot, REFERENCE_DIRECTORY_PATH)
+        .filter((entry) => entryKind(entry) === "file")
+        .filter((entry) => isPathAllowedForProjection(entry.path))
+        .map((entry) => {
+        const relativePath = entry.path.slice(REFERENCE_DIRECTORY_PATH.length + 1);
+        return createViewerTreeEntry(entry, {
+            path: entry.path,
+            parentPath: posix.dirname(entry.path),
+            depth: relativePath.split("/").length,
+        });
+    })
+        .sort((left, right) => left.path.localeCompare(right.path, "en", { sensitivity: "base" }));
+}
+//# sourceMappingURL=reference-tree.js.map

package/dist/workspace-ops/viewer-git.d.ts

@@ -9,6 +9,7 @@ export type RawTreeEntry = {
 export declare function readViewerSnapshot(options: WorkspaceViewerOptions): ViewerRepoSnapshot;
 export declare function lsPath(workspaceRoot: string, normalizedPath: string): RawTreeEntry | null;
 export declare function lsDirectoryChildren(workspaceRoot: string, normalizedPath: string): RawTreeEntry[];
+export declare function lsTreeRecursive(workspaceRoot: string, normalizedPath: string): RawTreeEntry[];
 export declare function entryKind(entry: RawTreeEntry): ViewerEntryKind;
 export declare function requireFileEntry(options: {
     workspaceRoot: string;

package/dist/workspace-ops/viewer-git.js

@@ -76,6 +76,17 @@ export function lsDirectoryChildren(workspaceRoot, normalizedPath) {
         : `${WORKSPACE_OPS_MAINLINE_BRANCH}:${normalizedPath}`;
     return lsTree(workspaceRoot, ["ls-tree", "-z", "-l", treeish]);
 }
+export function lsTreeRecursive(workspaceRoot, normalizedPath) {
+    return lsTree(workspaceRoot, [
+        "ls-tree",
+        "-r",
+        "-z",
+        "-l",
+        WORKSPACE_OPS_MAINLINE_BRANCH,
+        "--",
+        normalizedPath,
+    ]);
+}
 export function entryKind(entry) {
     if (entry.mode === "040000" || entry.type === "tree") {
         return "directory";

package/migrations/0015_control_plane_intents.sql

@@ -0,0 +1,115 @@
+CREATE TABLE control_plane_intents (
+  intent_id TEXT PRIMARY KEY CHECK (
+    intent_id GLOB 'intent_[0-7][0-9A-HJKMNP-TV-Z][0-9A-HJKMNP-TV-Z][0-9A-HJKMNP-TV-Z]*'
+    AND length(intent_id) = 33
+  ),
+  kind TEXT NOT NULL CHECK (
+    kind IN (
+      'task_compile_start',
+      'task_compile_continuation',
+      'task_bound_follow_up',
+      'scratchpad_refresh',
+      'reference_summary_refresh',
+      'run_dispatch'
+    )
+  ),
+  owner_kind TEXT NOT NULL CHECK (
+    owner_kind IN (
+      'task_compile',
+      'clarification_round',
+      'scratchpad',
+      'reference_summary',
+      'task_run'
+    )
+  ),
+  owner_ref TEXT NOT NULL CHECK (length(owner_ref) BETWEEN 1 AND 512),
+  dedupe_key TEXT NOT NULL UNIQUE CHECK (length(dedupe_key) BETWEEN 1 AND 512),
+  lane TEXT NOT NULL CHECK (lane IN ('foreground', 'scratchpad_background', 'run')),
+  priority INTEGER NOT NULL DEFAULT 100 CHECK (priority >= 0),
+  state TEXT NOT NULL DEFAULT 'pending' CHECK (
+    state IN ('pending', 'claimed', 'running', 'completed', 'failed', 'cancelled')
+  ),
+  available_at TEXT NOT NULL,
+  claim_token TEXT CHECK (claim_token IS NULL OR length(claim_token) BETWEEN 1 AND 256),
+  lease_expires_at TEXT,
+  attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+  last_error_code TEXT CHECK (
+    last_error_code IS NULL OR length(last_error_code) BETWEEN 1 AND 128
+  ),
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  completed_at TEXT,
+  CHECK (
+    (
+      state = 'pending'
+      AND claim_token IS NULL
+      AND lease_expires_at IS NULL
+      AND completed_at IS NULL
+    )
+    OR (
+      state IN ('claimed', 'running')
+      AND claim_token IS NOT NULL
+      AND lease_expires_at IS NOT NULL
+      AND completed_at IS NULL
+    )
+    OR (
+      state IN ('completed', 'failed', 'cancelled')
+      AND claim_token IS NULL
+      AND lease_expires_at IS NULL
+      AND completed_at IS NOT NULL
+    )
+  )
+);
+
+CREATE INDEX idx_control_plane_intents_dispatch
+  ON control_plane_intents (state, available_at ASC, priority ASC, created_at ASC, intent_id ASC);
+
+CREATE INDEX idx_control_plane_intents_expired_claim
+  ON control_plane_intents (state, lease_expires_at ASC)
+  WHERE state IN ('claimed', 'running');
+
+CREATE INDEX idx_control_plane_intents_owner
+  ON control_plane_intents (owner_kind, owner_ref, created_at ASC);
+
+CREATE TABLE pending_task_compile_submissions (
+  id TEXT PRIMARY KEY CHECK (id = 'current'),
+  workflow_ref TEXT NOT NULL UNIQUE,
+  accepted_activity_ref TEXT NOT NULL,
+  requested_at TEXT NOT NULL,
+  source_window_after_created_at TEXT,
+  source_window_after_message_id TEXT,
+  source_window_through_created_at TEXT,
+  source_window_through_message_id TEXT,
+  CHECK (
+    (source_window_after_created_at IS NULL AND source_window_after_message_id IS NULL)
+    OR (
+      source_window_after_created_at IS NOT NULL
+      AND source_window_after_message_id IS NOT NULL
+    )
+  ),
+  CHECK (
+    (source_window_through_created_at IS NULL AND source_window_through_message_id IS NULL)
+    OR (
+      source_window_through_created_at IS NOT NULL
+      AND source_window_through_message_id IS NOT NULL
+    )
+  ),
+  CHECK (
+    source_window_after_created_at IS NULL
+    OR source_window_through_created_at IS NULL
+    OR source_window_through_created_at > source_window_after_created_at
+    OR (
+      source_window_through_created_at = source_window_after_created_at
+      AND source_window_through_message_id >= source_window_after_message_id
+    )
+  )
+);
+
+CREATE TRIGGER pending_task_compile_submissions_immutable
+BEFORE UPDATE ON pending_task_compile_submissions
+BEGIN
+  SELECT RAISE(ABORT, 'pending Task Compile submission is immutable');
+END;
+
+ALTER TABLE scratchpad_source_state
+  ADD COLUMN in_flight_intent_id TEXT REFERENCES control_plane_intents(intent_id);

package/migrations/README.md

@@ -27,10 +27,11 @@
 - `0012_scratchpad_receipts.sql`：为当前 Scratchpad 增加 `submitted` 状态字段，并新增已提交 Scratchpad 小票历史表。
 - `0013_scratchpad_receipt_sources.sql`：新增当前 Scratchpad snapshot 与 submitted receipt 的 source message id 引用表，供 Timeline Task Accepted 追溯原始聊天依据。
 - `0014_scratchpad_task_compile_context.sql`：把 Scratchpad source state 收敛为纯主群聊周期 cursor，新增 durable active Task Compile Context 与完整 source refs，并把 Current Scratchpad / receipt sources 限定为主群聊。该开发阶段 migration 不迁移旧调试数据，已有本地开发数据库需要 reset / recreate。
+- `0015_control_plane_intents.sql`：新增 Control Plane durable dispatch intent，保存 bounded kind / owner / dedupe / lane、pending-to-running claim lease 与 terminal 状态，为 Clarification、Task Compile、Scratchpad、Reference Summary 和 Run 提供可恢复的 runtime handoff；同时用 immutable pending Task Compile submission row 固化 context capture 前的 workflow / main-chat cursor boundary，不保存 prompt、消息正文、provider output、secret 或 host path。
 
 ## 当前实现状态
 
-- `0001_init.sql` 至 `0014_scratchpad_task_compile_context.sql` 已存在，代表当前 host project SQLite schema contract。`0014` 明确采用开发数据库重建策略，不提供旧 Scratchpad source/cursor 数据兼容。
+- `0001_init.sql` 至 `0015_control_plane_intents.sql` 已存在，代表当前 host project SQLite schema contract。`0014` 明确采用开发数据库重建策略，不提供旧 Scratchpad source/cursor 数据兼容。
 - SQLite adapter、migration runner、checksum 校验、store metadata 初始化、transaction helper 与 command recovery scan helper 已实现。
 - 协作 repository 与 Control Plane 已实现第一批业务读写；Phase 7 首批已复用 `0001_init.sql` 中的 `tasks.latest_run_result_id`、`task_details.result_json` 与 `run_results` 表完成 Run result / checks / promotion 摘要持久化。Control Plane recovery resolver 与 task-bound continuation / retry 复用现有 schema；新 Run 的 accepted checkpoint 业务 truth 继续写入最终 Run result / task detail result，Git tag / commit trailer 承担 crash recovery evidence。Timeline 默认从 `tasks`、`run_results` 与历史主群聊 `refs.worklist_feedback` 投影任务级审计节点，当前 task terminal Chat feedback 写入 `refs.task_result` 消息；`project_timeline_events` 只保留缺少稳定 record 的轻量可观测性事件和历史 reconcile 兼容记录。project workspace、working diff 与 ignored runtime state 都不进入 SQLite truth。`provider_usage_events` 只保存 token 计数、调用来源、模型名、记录时间和可空 anchor，不保存 provider secret、prompt 或 raw response。store 基础设施本身已经可以创建并迁移 `tutti.sqlite`。
 

package/node_modules/@tutti/shared/dist/ids/index.d.ts

@@ -25,6 +25,7 @@ export declare const ID_PREFIXES: {
     readonly hostConnection: "host_connection_";
     readonly joinToken: "join_token_";
     readonly notice: "notice_";
+    readonly controlPlaneIntent: "intent_";
 };
 export type IdPrefix = (typeof ID_PREFIXES)[keyof typeof ID_PREFIXES];
 export type PrefixedId<TPrefix extends string> = `${TPrefix}${string}`;
@@ -53,6 +54,7 @@ export type RelayDesktopEntryContinuationRef = PrefixedId<typeof ID_PREFIXES.rel
 export type HostConnectionRef = PrefixedId<typeof ID_PREFIXES.hostConnection>;
 export type JoinTokenRef = PrefixedId<typeof ID_PREFIXES.joinToken>;
 export type NoticeId = PrefixedId<typeof ID_PREFIXES.notice>;
+export type ControlPlaneIntentId = PrefixedId<typeof ID_PREFIXES.controlPlaneIntent>;
 export declare function createPrefixedId<const TPrefix extends IdPrefix>(prefix: TPrefix): PrefixedId<TPrefix>;
 export declare function isUlidBody(value: string): boolean;
 export declare function getPrefixedIdBody(value: string, prefix: IdPrefix): string | null;
@@ -85,4 +87,5 @@ export declare const createRelayDesktopEntryContinuationRef: () => RelayDesktopE
 export declare const createHostConnectionRef: () => HostConnectionRef;
 export declare const createJoinTokenRef: () => JoinTokenRef;
 export declare const createNoticeId: () => NoticeId;
+export declare const createControlPlaneIntentId: () => ControlPlaneIntentId;
 //# sourceMappingURL=index.d.ts.map

package/node_modules/@tutti/shared/dist/ids/index.js

@@ -27,6 +27,7 @@ export const ID_PREFIXES = {
     hostConnection: "host_connection_",
     joinToken: "join_token_",
     notice: "notice_",
+    controlPlaneIntent: "intent_",
 };
 export function createPrefixedId(prefix) {
     return `${prefix}${ulid()}`;
@@ -87,4 +88,5 @@ export const createRelayDesktopEntryContinuationRef = () => createPrefixedId(ID_
 export const createHostConnectionRef = () => createPrefixedId(ID_PREFIXES.hostConnection);
 export const createJoinTokenRef = () => createPrefixedId(ID_PREFIXES.joinToken);
 export const createNoticeId = () => createPrefixedId(ID_PREFIXES.notice);
+export const createControlPlaneIntentId = () => createPrefixedId(ID_PREFIXES.controlPlaneIntent);
 //# sourceMappingURL=index.js.map

package/node_modules/@tutti/shared/dist/schemas/api/viewer-reference.d.ts

@@ -250,7 +250,6 @@ export declare const ReferenceDirectoryProjectionSchema: import("@sinclair/typeb
     index_path: import("@sinclair/typebox").TLiteral<"docs/reference/README.md">;
     files_path: import("@sinclair/typebox").TLiteral<"docs/reference/files">;
     images_path: import("@sinclair/typebox").TLiteral<"docs/reference/images">;
-    tutti_path: import("@sinclair/typebox").TLiteral<"docs/reference/tutti">;
     index_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"available">, import("@sinclair/typebox").TLiteral<"missing">, import("@sinclair/typebox").TLiteral<"unreadable">]>;
     index_unreadable_reason: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"restricted_path">, import("@sinclair/typebox").TLiteral<"secret_like">, import("@sinclair/typebox").TLiteral<"binary">, import("@sinclair/typebox").TLiteral<"unsupported_encoding">, import("@sinclair/typebox").TLiteral<"too_large">]>>;
 }>;
@@ -266,7 +265,6 @@ export declare const ReferenceSummaryProjectionSchema: import("@sinclair/typebox
 export declare const ReferenceFileProjectionSchema: import("@sinclair/typebox").TObject<{
     path: import("@sinclair/typebox").TString;
     name: import("@sinclair/typebox").TString;
-    source: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"human_upload">, import("@sinclair/typebox").TLiteral<"tutti_output">]>;
     category: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"file">, import("@sinclair/typebox").TLiteral<"image">]>;
     size_bytes: import("@sinclair/typebox").TInteger;
     media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -308,14 +306,12 @@ export declare const GetReferenceFilesResponseSchema: import("@sinclair/typebox"
         index_path: import("@sinclair/typebox").TLiteral<"docs/reference/README.md">;
         files_path: import("@sinclair/typebox").TLiteral<"docs/reference/files">;
         images_path: import("@sinclair/typebox").TLiteral<"docs/reference/images">;
-        tutti_path: import("@sinclair/typebox").TLiteral<"docs/reference/tutti">;
         index_status: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"available">, import("@sinclair/typebox").TLiteral<"missing">, import("@sinclair/typebox").TLiteral<"unreadable">]>;
         index_unreadable_reason: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"restricted_path">, import("@sinclair/typebox").TLiteral<"secret_like">, import("@sinclair/typebox").TLiteral<"binary">, import("@sinclair/typebox").TLiteral<"unsupported_encoding">, import("@sinclair/typebox").TLiteral<"too_large">]>>;
     }>;
     items: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
         path: import("@sinclair/typebox").TString;
         name: import("@sinclair/typebox").TString;
-        source: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"human_upload">, import("@sinclair/typebox").TLiteral<"tutti_output">]>;
         category: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"file">, import("@sinclair/typebox").TLiteral<"image">]>;
         size_bytes: import("@sinclair/typebox").TInteger;
         media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -359,7 +355,6 @@ export declare const UploadReferenceFileResultSchema: import("@sinclair/typebox"
     file: import("@sinclair/typebox").TObject<{
         path: import("@sinclair/typebox").TString;
         name: import("@sinclair/typebox").TString;
-        source: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"human_upload">, import("@sinclair/typebox").TLiteral<"tutti_output">]>;
         category: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"file">, import("@sinclair/typebox").TLiteral<"image">]>;
         size_bytes: import("@sinclair/typebox").TInteger;
         media_type: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;

package/node_modules/@tutti/shared/dist/schemas/api/viewer-reference.js

@@ -164,7 +164,6 @@ export const ReferenceDirectoryProjectionSchema = Type.Object({
     index_path: Type.Literal("docs/reference/README.md"),
     files_path: Type.Literal("docs/reference/files"),
     images_path: Type.Literal("docs/reference/images"),
-    tutti_path: Type.Literal("docs/reference/tutti"),
     index_status: Type.Union([
         Type.Literal("available"),
         Type.Literal("missing"),
@@ -196,7 +195,6 @@ export const ReferenceSummaryProjectionSchema = Type.Object({
 export const ReferenceFileProjectionSchema = Type.Object({
     path: ViewerPathSchema,
     name: NonEmptyStringSchema,
-    source: Type.Union([Type.Literal("human_upload"), Type.Literal("tutti_output")]),
     category: ReferenceFileCategorySchema,
     size_bytes: Type.Integer({ minimum: 0 }),
     media_type: Type.Optional(NonEmptyStringSchema),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfey/tutti",
-  "version": "0.1.96",
+  "version": "0.1.98",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/prompts/procedures/context-sync.md

@@ -16,9 +16,9 @@ Use repository inspection and attached skills only when useful:
 
 - Use `read-project-docs` for existing project documents and availability.
 - Use `read-worklist` when repo state or completed formal tasks can explain the current implementation stage. Do not turn task results into a changelog.
-- Use `read-references` only when a human-uploaded reference file's actual content matters.
+- Use `read-references` only when a file in the shared project Reference space actually matters.
 
-Reference upload events, file names, media types, and paths do not prove file contents. Read the relevant file before relying on it.
+Reference creation events, file names, media types, paths, and summaries do not prove file contents. Read the relevant file before relying on it.
 
 # Documentation Scope
 
@@ -62,5 +62,5 @@ Return only JSON matching this schema:
 If no concrete documentation update is needed, return an empty `updates` array:
 
 ```json
-{"summary":"Checked current docs against repository facts; no updates needed.","updates":[]}
+{ "summary": "Checked current docs against repository facts; no updates needed.", "updates": [] }
 ```

package/prompts/procedures/reference-file-summary.md

@@ -6,7 +6,7 @@ model_path: codex.app_server.read_only
 
 # Role
 
-You summarize one human-uploaded Tutti reference file.
+You summarize one file from Tutti's shared project Reference space.
 
 # Runtime
 

package/prompts/procedures/task-compile.md

@@ -36,9 +36,9 @@ You compile Tutti's Scratchpad into an append-only Worklist proposal for post-ba
 Tutti can expose direct user-viewable outputs through two repo-backed surfaces when a task result is meant for project members to inspect:
 
 - a single active visual artifact, declared by `tutti.artifact.json`, for previewable pages, apps, dashboards, or similar interactive outputs;
-- generated files under `docs/reference/tutti/**`, for reviewable files such as reports, notes, specs, exports, or similar outputs.
+- generated files in the shared `docs/reference/**` space, directly at the root or under a meaningful semantic subfolder, for reviewable files such as reports, notes, specs, exports, or similar outputs.
 
-Treat these as delivery surfaces, not as task subjects by themselves. Human-uploaded references still live under `docs/reference/files/` or `docs/reference/images/`, and stable project facts still belong in the relevant project docs or README-style files.
+Treat these as delivery surfaces, not as task subjects by themselves. Browser uploads continue to enter the Host-managed `docs/reference/files/` or `docs/reference/images/` partitions, `docs/reference/README.md` remains Host-owned, and stable project facts still belong in the relevant project docs or README-style files.
 
 When the Scratchpad clearly asks for one of these direct deliverables, include a concise task `scope` item naming the expected surface. If a completion card should call out the result or generated file name, the scope may also mention `user_note_candidate`. Do not add artifact or generated-reference outputs solely to create feedback for ordinary implementation tasks.
 

package/prompts/prompt-flow-map.md

@@ -377,7 +377,7 @@ Provider raw 输出：根对象只包含 `result`；`result` 内二选一输出
 - Reference Files 不通过 built-in skill 暴露；若任务契约或 Project Docs 指向 `docs/reference/` 中资料，Codex 可直接读取相关 repo 文件正文。
 - `goal / scope` 决定本次执行边界；`source_messages` 与 compile `clarification_rounds` 只提供该边界引用的精确材料，不自动扩展任务目标。
 
-输出：根对象只包含 `result`；`result` 内四选一输出 `completed.{summary,user_note_candidate}`、`completed_no_repo_changes.{summary,user_note_candidate}`、`needs_human.{title,summary,request}` 或 `failed.summary`。`user_note_candidate` 是可选最终反馈候选，字段必填但可为 `null`；生成给用户直接查看的文件应写入 `docs/reference/tutti/`。`completed_no_repo_changes` 只用于任务契约不要求 repository file changes 的情况。`needs_human` payload 必须能直接作为 task-bound clarification request 使用：解释为什么 frozen contract 下无法安全继续，并提出一个具体、可回答、非 secret 的问题。
+输出：根对象只包含 `result`；`result` 内四选一输出 `completed.{summary,user_note_candidate}`、`completed_no_repo_changes.{summary,user_note_candidate}`、`needs_human.{title,summary,request}` 或 `failed.summary`。`user_note_candidate` 是可选最终反馈候选，字段必填但可为 `null`；生成给用户直接查看的文件应写入共享 `docs/reference/` 根目录或有意义的语义子目录，同时避开 Host-owned `README.md` 和通常由浏览器上传使用的 `files/`、`images/` 分区。`completed_no_repo_changes` 只用于任务契约不要求 repository file changes 的情况。`needs_human` payload 必须能直接作为 task-bound clarification request 使用：解释为什么 frozen contract 下无法安全继续，并提出一个具体、可回答、非 secret 的问题。
 
 下游：Run pipeline 收集真实 Git diff 作为 `changed_paths`；`needs_human` 时 Control Plane 记录 `Run.needs_human`、打开 task-bound clarification 并把 task 迁回 `pending`；有 repo candidate 的 `completed` 结果先执行 Artifact candidate gate 与 checks，再在当前 `tutti/mainline` 创建 accepted commit + immutable activity tag；空 diff 的 `completed_no_repo_changes` 结果跳过 Artifact gate、checks 与 accepted checkpoint，记录 `promotion.status = not_attempted`。
 

package/prompts/runs/task-execute.md

@@ -33,9 +33,9 @@ For a continuation, the same task is already present in this conversation. The i
 
 Use attached skills only when they help the task. `read-worklist` may clarify related formal work without expanding this task. `read-project-docs` may clarify architecture, setup, and maintenance rules. User skills may guide implementation but do not override the task, command policy, workspace policy, checks, or redaction rules.
 
-Human-uploaded references are under `docs/reference/`. Read a relevant source file before relying on it; do not infer its contents from a name, path, media type, upload message, or summary.
+Project members and Tutti share `docs/reference/**` as the member-viewable Reference space. Read a relevant source file before relying on it; do not infer its contents from a name, path, media type, upload message, or summary.
 
-`docs/reference/tutti/**` is reserved for generated files that project members should inspect in the References UI. Use it for explicit reviewable deliverables, not temporary output, logs, internal notes, or canonical project documentation. Use a meaningful subfolder when it helps explain a group of files.
+When this task needs to create an explicit reviewable deliverable, write it directly under `docs/reference/` or use a meaningful semantic subfolder such as `docs/reference/reports/`. Do not put temporary output, logs, internal notes, or canonical project documentation there. Do not overwrite unrelated existing References. `docs/reference/files/` and `docs/reference/images/` are normally reserved for Host-managed browser uploads, and `docs/reference/README.md` is Host-owned; do not modify them unless the task explicitly requires that exact existing file.
 
 # Documentation
 

package/prompts/skills/read-references/SKILL.md

@@ -5,7 +5,7 @@ description: List and read bounded Tutti reference files when the turn has refer
 
 # Read References
 
-Use this skill when a Tutti app-server turn needs user-uploaded reference material.
+Use this skill when a Tutti app-server turn needs material from the shared project Reference space. Files may have been uploaded by a project member or created by Tutti in an earlier Run.
 
 When a Tutti context API runtime hint is present and includes `references:list`, list available references through:
 
@@ -19,7 +19,7 @@ When a listed text file is relevant and the hint includes `references:read`, rea
 
 Read responses may include the same `summary` object alongside text or unavailable metadata.
 
-Read only reference files that are relevant to the current task or question. Do not infer file contents from upload messages, names, media types, or paths alone. If a file is unavailable, restricted, binary, too large, or unsupported, use the returned disposition instead of guessing.
+Read only reference files that are relevant to the current task or question. Do not infer file contents from creation events, names, media types, paths, or summaries alone. If a file is unavailable, restricted, binary, too large, or unsupported, use the returned disposition instead of guessing.
 
 This skill is read-only. Do not attempt to create, update, refresh, or write reference summaries from this skill.