pi-ui-extend 1.0.40 → 1.0.42

package/dist/schemas/pi-tools-suite-schema.js

@@ -39,7 +39,7 @@ const TerminalBellConfig = Type.Object({
 // ---------------------------------------------------------------------------
 const DcpManualModeConfig = Type.Object({
     enabled: Type.Optional(Type.Boolean({ description: "Enable manual DCP mode." })),
-    automaticStrategies: Type.Optional(Type.Boolean({ description: "Run dedup/purge even in manual mode." })),
+    automaticStrategies: Type.Optional(Type.Never({ description: "Removed legacy key. Manual mode now has only the explicit enabled flag." })),
 }, { description: "Manual mode configuration." });
 const DcpAutoCandidatesConfig = Type.Object({
     enabled: Type.Optional(Type.Boolean({ description: "Enable auto candidate selection for compression." })),
@@ -56,11 +56,17 @@ const DcpMessageModeConfig = Type.Object({
     highTokens: Type.Optional(Type.Number({ description: "Token threshold for high-quality summary.", minimum: 0 })),
     maxSuggestions: Type.Optional(Type.Number({ description: "Maximum compression suggestions.", minimum: 0 })),
 }, { description: "Message-mode compression configuration." });
+const DcpAutoCompressConfig = Type.Object({
+    enabled: Type.Optional(Type.Boolean({ description: "Allow autonomous compression after pressure/opportunity gates. Explicit compress calls can still use summarizerModel when summary is omitted." })),
+    patience: Type.Optional(Type.Number({ description: "Completed actionable opportunities allowed before automatic compression.", minimum: 0 })),
+    summarizerModel: Type.Optional(Type.Array(Type.String(), { description: "Ordered model refs used by auto-compress and explicit compress when summary is omitted; empty uses the deterministic extractive summary." })),
+    timeoutMs: Type.Optional(Type.Number({ description: "Per-summarizer deadline in milliseconds for automatic and explicit generated summaries.", minimum: 1 })),
+}, { description: "Bounded automatic compression fallback." });
 const DcpCompressConfig = Type.Object({
     maxContextPercent: Type.Optional(Type.Union([Type.Number(), Type.String()], { description: "Maximum context percent (0–1 or '80%') before compression triggers." })),
     minContextPercent: Type.Optional(Type.Union([Type.Number(), Type.String()], { description: "Target context percent after compression." })),
-    modelMaxContextPercent: Type.Optional(Type.Record(Type.String(), Type.Number(), { description: "Per-model max context percent overrides." })),
-    modelMinContextPercent: Type.Optional(Type.Record(Type.String(), Type.Number(), { description: "Per-model min context percent overrides." })),
+    modelMaxContextPercent: Type.Optional(Type.Record(Type.String(), Type.Union([Type.Number(), Type.String()]), { description: "Per-model max context overrides using the same fraction/token/percent formats." })),
+    modelMinContextPercent: Type.Optional(Type.Record(Type.String(), Type.Union([Type.Number(), Type.String()]), { description: "Per-model min context overrides using the same fraction/token/percent formats." })),
     maxContextLimit: Type.Optional(Type.Union([Type.Number(), Type.String()], { description: "Absolute max context tokens or '200k'." })),
     minContextLimit: Type.Optional(Type.Union([Type.Number(), Type.String()], { description: "Absolute min context tokens." })),
     modelMaxContextLimits: Type.Optional(Type.Record(Type.String(), Type.Union([Type.Number(), Type.String()]), { description: "Per-model max context limit overrides." })),
@@ -74,29 +80,37 @@ const DcpCompressConfig = Type.Object({
     protectUserMessages: Type.Optional(Type.Boolean({ description: "Protect user messages from pruning." })),
     autoCandidates: Type.Optional(DcpAutoCandidatesConfig),
     messageMode: Type.Optional(DcpMessageModeConfig),
+    autoCompress: Type.Optional(DcpAutoCompressConfig),
 }, { description: "Compression trigger and behavior configuration." });
-const DcpDeduplicationConfig = Type.Object({
-    enabled: Type.Optional(Type.Boolean({ description: "Enable duplicate content deduplication." })),
-    protectedTools: Type.Optional(Type.Array(Type.String(), { description: "Tool outputs protected from dedup." })),
-}, { description: "Deduplication strategy configuration." });
-const DcpPurgeErrorsConfig = Type.Object({
-    enabled: Type.Optional(Type.Boolean({ description: "Enable error input purging." })),
-    turns: Type.Optional(Type.Number({ description: "Prune error inputs after N user turns.", minimum: 1 })),
-    protectedTools: Type.Optional(Type.Array(Type.String(), { description: "Tool outputs protected from error purge." })),
-}, { description: "Error purging strategy configuration." });
-const DcpAutoToolPruningConfig = Type.Object({
-    enabled: Type.Optional(Type.Boolean({ description: "Enable automatic tool output pruning." })),
-    maxOutputTokens: Type.Optional(Type.Number({ description: "Maximum output tokens before truncation.", minimum: 0 })),
-    keepRecentTurns: Type.Optional(Type.Number({ description: "Recent turns to keep.", minimum: 0 })),
-    readLikeTools: Type.Optional(Type.Array(Type.String(), { description: "Tools treated as read-like (aggressively pruned)." })),
-    readLikeTurns: Type.Optional(Type.Number({ description: "Turns threshold for read-like tool pruning.", minimum: 0 })),
-    protectedTools: Type.Optional(Type.Array(Type.String(), { description: "Tool outputs protected from auto-pruning." })),
-}, { description: "Auto tool pruning strategy configuration." });
+const DcpEmergencyCurrentTurnPruningConfig = Type.Object({
+    enabled: Type.Optional(Type.Boolean({ description: "Enable bounded same-turn emergency planning and last-resort output pruning." })),
+    hardContextPercent: Type.Optional(Type.Number({ description: "Context fraction that activates hard emergency pressure.", minimum: 0, maximum: 1 })),
+    targetContextPercent: Type.Optional(Type.Number({ description: "Context fraction the emergency path attempts to recover toward.", minimum: 0, maximum: 1 })),
+    patience: Type.Optional(Type.Number({ description: "Completed emergency opportunities allowed before last-resort pruning.", minimum: 0 })),
+    keepRecentToolPairs: Type.Optional(Type.Number({ description: "Newest complete tool-call/result pairs never selected by emergency cleanup.", minimum: 0 })),
+    minOutputTokens: Type.Optional(Type.Number({ description: "Minimum tool-result size eligible for emergency pruning.", minimum: 0 })),
+    maxSuggestions: Type.Optional(Type.Number({ description: "Maximum emergency message candidates shown in a reminder.", minimum: 0 })),
+    protectedTools: Type.Optional(Type.Array(Type.String(), { description: "Additional tools protected from emergency pruning and manual sweep." })),
+}, { description: "Single bounded emergency cleanup strategy." });
 const DcpStrategiesConfig = Type.Object({
-    deduplication: Type.Optional(DcpDeduplicationConfig),
-    purgeErrors: Type.Optional(DcpPurgeErrorsConfig),
-    autoToolPruning: Type.Optional(DcpAutoToolPruningConfig),
-}, { description: "DCP pruning strategies." });
+    emergencyCurrentTurnPruning: Type.Optional(DcpEmergencyCurrentTurnPruningConfig),
+    deduplication: Type.Optional(Type.Never({ description: "Removed legacy key; no automatic replacement policy maps to it." })),
+    purgeErrors: Type.Optional(Type.Never({ description: "Removed legacy key; no automatic replacement policy maps to it." })),
+    autoToolPruning: Type.Optional(Type.Never({ description: "Removed legacy key. Use explicit /dcp sweep or DCP compression/emergency policies instead." })),
+}, { description: "Bounded DCP emergency strategy." });
+const DcpConfigOverride = Type.Object({
+    enabled: Type.Optional(Type.Boolean()),
+    debug: Type.Optional(Type.Boolean()),
+    debugLog: Type.Optional(Type.Object({
+        maxBytes: Type.Optional(Type.Number({ minimum: 1024 })),
+        maxBackups: Type.Optional(Type.Number({ minimum: 1 })),
+    })),
+    manualMode: Type.Optional(DcpManualModeConfig),
+    compress: Type.Optional(DcpCompressConfig),
+    strategies: Type.Optional(DcpStrategiesConfig),
+    protectedFilePatterns: Type.Optional(Type.Array(Type.String())),
+    pruneNotification: Type.Optional(Type.Never({ description: "Removed legacy key; pruning notifications are no longer configurable." })),
+}, { description: "Partial DCP override applied to a matching provider/model or bare-model key. Keys support * and ? wildcards." });
 const DcpConfig = Type.Object({
     enabled: Type.Optional(Type.Boolean({ description: "Enable DCP (Dynamic Context Pruning)." })),
     debug: Type.Optional(Type.Boolean({ description: "Enable DCP debug logging." })),
@@ -108,71 +122,10 @@ const DcpConfig = Type.Object({
     compress: Type.Optional(DcpCompressConfig),
     strategies: Type.Optional(DcpStrategiesConfig),
     protectedFilePatterns: Type.Optional(Type.Array(Type.String(), { description: "File path glob patterns whose content is protected from pruning." })),
-    pruneNotification: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("minimal"), Type.Literal("detailed")], { description: "Notification level when pruning occurs." })),
+    modelOverrides: Type.Optional(Type.Record(Type.String(), DcpConfigOverride, { description: "Per-model partial DCP overrides. Exact keys take precedence over matching wildcards." })),
+    pruneNotification: Type.Optional(Type.Never({ description: "Removed legacy key; pruning notifications are no longer configurable." })),
 }, { description: "DCP (Dynamic Context Pruning) configuration." });
 // ---------------------------------------------------------------------------
-// Async subagents
-// ---------------------------------------------------------------------------
-const RetryConfig = Type.Object({
-    maxRetries: Type.Optional(Type.Number({ description: "Maximum retry attempts.", minimum: 0 })),
-    backoffMs: Type.Optional(Type.Number({ description: "Base delay in ms before first retry.", minimum: 0 })),
-    retryableExitCodes: Type.Optional(Type.Array(Type.Number(), { description: "Exit codes eligible for retry. Empty array disables retry." })),
-}, { description: "Retry configuration for sub-agents." });
-const SubagentRoutingConfig = Type.Object({
-    enabled: Type.Optional(Type.Boolean({ description: "Enable LLM-based automatic role routing." })),
-    model: Type.Optional(Type.String({ description: "Router model in provider/model form." })),
-    fallbackModels: Type.Optional(Type.Array(Type.String(), { uniqueItems: true, description: "Ordered router model fallbacks tried when the primary routing model is unavailable or fails. The current parent model is always tried last." })),
-    maxTaskChars: Type.Optional(Type.Number({ description: "Max task/scope characters sent to router.", minimum: 100 })),
-    maxTokens: Type.Optional(Type.Number({ description: "Max router response tokens.", minimum: 8 })),
-    maxRetries: Type.Optional(Type.Number({ description: "Router request retries.", minimum: 0 })),
-    timeoutMs: Type.Optional(Type.Number({ description: "Router request timeout in ms.", minimum: 1000 })),
-    debug: Type.Optional(Type.Boolean({ description: "Show routing debug warnings." })),
-}, { description: "LLM-based role routing configuration." });
-const SubagentVisionConfig = Type.Object({
-    blindModelPatterns: Type.Optional(Type.Array(Type.String(), { description: "Glob-like model refs treated as unable to inspect images." })),
-}, { description: "Vision capability overrides." });
-const SubagentPresetTypeOverride = Type.Object({
-    model: Type.Optional(Type.String({ description: "Model override for this type within the preset." })),
-    fallbackModels: Type.Optional(Type.Array(Type.String(), { description: "Per-role fallback models." })),
-    thinking: Type.Optional(Type.String({ description: "Thinking level override." })),
-    extraArgs: Type.Optional(Type.Array(Type.String(), { description: "Extra CLI arguments." })),
-    timeoutMs: Type.Optional(Type.Number({ description: "Per-agent wall-clock timeout in ms.", minimum: 1 })),
-}, { description: "Per-type override within a preset." });
-const SubagentPreset = Type.Object({
-    description: Type.Optional(Type.String({ description: "Preset description." })),
-    model: Type.Optional(Type.String({ description: "Default model for this preset." })),
-    fallbackModels: Type.Optional(Type.Array(Type.String(), { description: "Global fallback models for this preset." })),
-    thinking: Type.Optional(Type.String({ description: "Default thinking level." })),
-    extraArgs: Type.Optional(Type.Array(Type.String(), { description: "Extra CLI arguments." })),
-    timeoutMs: Type.Optional(Type.Number({ description: "Per-agent wall-clock timeout in ms.", minimum: 1 })),
-    types: Type.Optional(Type.Record(Type.String(), SubagentPresetTypeOverride, { description: "Per-type overrides." })),
-}, { description: "Named spawn preset." });
-const SubagentTypeConfig = Type.Object({
-    description: Type.Optional(Type.String({ description: "Role description for routing." })),
-    model: Type.Optional(Type.String({ description: "Model for this sub-agent type." })),
-    fallbackModels: Type.Optional(Type.Array(Type.String(), { description: "Ordered model fallbacks." })),
-    thinking: Type.Optional(Type.String({ description: "Thinking level." })),
-    tools: Type.Optional(Type.Array(Type.String(), { description: "Enabled tools for this type." })),
-    isolatedSkills: Type.Optional(Type.Array(Type.String(), { description: "Explicit skill files loaded after disabling normal skill discovery for this type." })),
-    extraArgs: Type.Optional(Type.Array(Type.String(), { description: "Extra CLI arguments." })),
-    promptAppend: Type.Optional(Type.String({ description: "Extra prompt text appended after generated prompt." })),
-    promptOverride: Type.Optional(Type.String({ description: "Full prompt replacement." })),
-    retry: Type.Optional(RetryConfig),
-    maxResultBytes: Type.Optional(Type.Number({ description: "Max bytes in result summary.", minimum: 0 })),
-    timeoutMs: Type.Optional(Type.Number({ description: "Per-agent wall-clock timeout in ms.", minimum: 1 })),
-}, { description: "Configuration for a sub-agent type/role." });
-const AsyncSubagentsConfig = Type.Object({
-    defaultType: Type.Optional(Type.String({ description: "Default sub-agent type when not specified." })),
-    routing: Type.Optional(SubagentRoutingConfig),
-    vision: Type.Optional(SubagentVisionConfig),
-    presets: Type.Optional(Type.Record(Type.String(), SubagentPreset, { description: "Named spawn presets." })),
-    types: Type.Optional(Type.Record(Type.String(), SubagentTypeConfig, { description: "Sub-agent type definitions." })),
-    maxConcurrent: Type.Optional(Type.Number({ description: "Max concurrent agents per spawn batch (0 = unlimited).", minimum: 0 })),
-    retry: Type.Optional(RetryConfig),
-    maxResultBytes: Type.Optional(Type.Number({ description: "Global max bytes in result summary.", minimum: 0 })),
-    timeoutMs: Type.Optional(Type.Number({ description: "Global per-agent wall-clock timeout in ms.", minimum: 1 })),
-}, { description: "Async sub-agent configuration." });
-// ---------------------------------------------------------------------------
 // Prompt commands
 // ---------------------------------------------------------------------------
 const PromptCommand = Type.Object({
@@ -186,6 +139,29 @@ const SecretFirewallConfig = Type.Object({
     sessionHygiene: Type.Optional(Type.Boolean({ description: "Redact detected secret material from tool results and completed messages before it remains in session history." })),
     notify: Type.Optional(Type.Boolean({ description: "Show a warning when one or more secrets are redacted. Secret values are never included in notifications." })),
 }, { description: "Settings for the opt-in credential-firewall module." });
+const CommentCheckerConfig = Type.Object({
+    enabled: Type.Optional(Type.Boolean({ description: "Enable or disable comment-checker without disabling the whole module." })),
+    strictness: Type.Optional(Type.Union([Type.Literal("conservative"), Type.Literal("balanced"), Type.Literal("aggressive")], { description: "Comment classification strictness. Defaults to balanced." })),
+}, { description: "Settings for the comment-checker module." });
+const ContextGatewayBudgetsConfig = Type.Object({
+    maxInlineBytes: Type.Optional(Type.Integer({ minimum: 1, maximum: 67108864, description: "Maximum inline size for a proven compact representation. Default 8192." })),
+    maxResultBytes: Type.Optional(Type.Integer({ minimum: 1, maximum: 67108864, description: "Budget for shell/other result classes. Selective enforce currently compacts only recognised complete simple test/build output. Default 8192." })),
+    maxExactReadBytes: Type.Optional(Type.Integer({ minimum: 1, maximum: 67108864, description: "Read-class observation budget. Reads remain passthrough because snapshot-safe recovery is not available. Default 32768." })),
+    maxSearchBytes: Type.Optional(Type.Integer({ minimum: 1, maximum: 67108864, description: "Repo-search/AST/structure observation budget. Gateway does not post-hoc truncate producer output. Default 8192." })),
+    maxSearchMatches: Type.Optional(Type.Integer({ minimum: 1, maximum: 1000, description: "Reserved search-match policy budget. Default 12." })),
+}, { description: "Context Gateway class-specific observation and selective-enforcement budgets." });
+const ContextGatewayConfig = Type.Object({
+    mode: Type.Optional(Type.Union([Type.Literal("off"), Type.Literal("observe"), Type.Literal("enforce")], { description: "Context Gateway mode. observe is passive; enforce only compacts proven complete simple test/build output and otherwise passes results through." })),
+    budgets: Type.Optional(ContextGatewayBudgetsConfig),
+}, { description: "Context Gateway configuration. Default mode is off." });
+const RepoDiscoveryConfig = Type.Object({
+    profile: Type.Optional(Type.Union([Type.Literal("baseline"), Type.Literal("native-compact")], { description: "repo_* runtime profile. baseline preserves historical argv/defaults; native-compact enables bounded native flags, cursors, validation, and an explicit per-call full override." })),
+}, { description: "Repository discovery runtime policy. Default profile is baseline." });
+const ResourceRegistryConfig = Type.Object({
+    remote: Type.Optional(Type.String({ description: "Git remote URL for the private registry. The repository contains reusable top-level skills/ and agents/ plus project-scoped state under projects/." })),
+    branch: Type.Optional(Type.String({ description: "Registry branch used for install/update/push/pull. Defaults to main." })),
+    projectKey: Type.Optional(Type.String({ description: "Optional explicit key for this project's projects/<key>/tasks.jsonc, plans/, and TODO.md state. Normally derived from the current Git origin." })),
+}, { description: "Private Git-backed registry for reusable skills/agents and project-scoped tasks/plans state." });
 // ---------------------------------------------------------------------------
 // LSP
 // ---------------------------------------------------------------------------
@@ -234,12 +210,16 @@ export const PiToolsSuiteConfigSchema = Type.Object({
     ]), { description: "Force per-todo thinking for matching provider/model or bare-model keys. Keys support * and ? wildcards; null removes an inherited override." })),
     lookupModel: Type.Optional(Type.Union([Type.String(), Type.Null()], { description: "Vision-capable provider/model used by GLM's lookup tool; unset or null disables lookup." })),
     terminalBell: Type.Optional(TerminalBellConfig),
+    commentChecker: Type.Optional(CommentCheckerConfig),
     dcp: Type.Optional(DcpConfig),
-    asyncSubagents: Type.Optional(AsyncSubagentsConfig),
     toolRenderer: Type.Optional(ToolRendererConfig),
     promptCommands: Type.Optional(PromptCommandsConfig),
     secretFirewall: Type.Optional(SecretFirewallConfig),
+    contextGateway: Type.Optional(ContextGatewayConfig),
+    repoDiscovery: Type.Optional(RepoDiscoveryConfig),
+    resourceRegistry: Type.Optional(ResourceRegistryConfig),
     lsp: Type.Optional(LspConfig),
+    asyncSubagents: Type.Optional(Type.Never({ description: "Removed legacy key. Configure sub-agents in .pi/agents/*.md and model pools in .pi/agents/presets.jsonc." })),
 }, {
     $id: "https://unpkg.com/pi-ui-extend/schemas/pi-tools-suite.json",
     $schema: "https://json-schema.org/draft-07/schema#",

package/dist/schemas/pix-schema.d.ts

@@ -64,5 +64,12 @@ export declare const PixConfigSchema: Type.TObject<{
             label: Type.TString;
         }>>>;
     }>>;
+    desktop: Type.TOptional<Type.TObject<{
+        externalEditor: Type.TOptional<Type.TString>;
+        git: Type.TOptional<Type.TObject<{
+            reviewModelRef: Type.TOptional<Type.TString>;
+            commitMessageModelRef: Type.TOptional<Type.TString>;
+        }>>;
+    }>>;
 }>;
 export type PixConfigSchemaType = Static<typeof PixConfigSchema>;

package/dist/schemas/pix-schema.js

@@ -69,6 +69,19 @@ const DictationConfig = Type.Object({
     language: Type.Optional(Type.String({ description: "Selected language code, e.g. 'en' or 'ru'." })),
     languages: Type.Optional(Type.Record(Type.String(), DictationLanguageModelConfig, { description: "Available language models keyed by language code." })),
 }, { description: "Voice dictation (Vosk) configuration." });
+const DesktopConfig = Type.Object({
+    externalEditor: Type.Optional(Type.String({
+        description: "External editor used by Pix Desktop project explorer. Known aliases include zed, code/vscode, cursor, subl/sublime, idea/intellij, and webstorm; an executable path/name is also accepted.",
+    })),
+    git: Type.Optional(Type.Object({
+        reviewModelRef: Type.Optional(Type.String({
+            description: "Model reference used by Pix Desktop for LLM review of Git diffs, optionally with a :thinking suffix.",
+        })),
+        commitMessageModelRef: Type.Optional(Type.String({
+            description: "Model reference used by Pix Desktop to generate Git commit messages, optionally with a :thinking suffix.",
+        })),
+    }, { description: "Pix Desktop Git/Source Control LLM preferences." })),
+}, { description: "Pix Desktop-specific preferences." });
 // ---------------------------------------------------------------------------
 // Top-level schema
 // ---------------------------------------------------------------------------
@@ -85,6 +98,7 @@ export const PixConfigSchema = Type.Object({
     modelColors: Type.Optional(ModelColorsConfig),
     iconTheme: Type.Optional(IconThemeConfig),
     dictation: Type.Optional(DictationConfig),
+    desktop: Type.Optional(DesktopConfig),
 }, {
     $id: "https://unpkg.com/pi-ui-extend/schemas/pix.json",
     $schema: "https://json-schema.org/draft-07/schema#",

package/dist/schemas/tasks-schema.d.ts

@@ -0,0 +1,18 @@
+/** JSON Schema for project-scoped Desktop tasks stored in <cwd>/.pi/tasks.jsonc. */
+import { Static, Type } from "typebox";
+export declare const ProjectTasksSchema: Type.TObject<{
+    $schema: Type.TOptional<Type.TString>;
+    version: Type.TLiteral<1>;
+    tasks: Type.TArray<Type.TObject<{
+        id: Type.TString;
+        title: Type.TString;
+        description: Type.TOptional<Type.TString>;
+        type: Type.TUnion<[Type.TLiteral<"bug">, Type.TLiteral<"feature">, Type.TLiteral<"improvement">]>;
+        status: Type.TUnion<[Type.TLiteral<"backlog">, Type.TLiteral<"todo">, Type.TLiteral<"in-progress">, Type.TLiteral<"done">]>;
+        priority: Type.TUnion<[Type.TLiteral<"low">, Type.TLiteral<"medium">, Type.TLiteral<"high">, Type.TLiteral<"urgent">]>;
+        sessionId: Type.TOptional<Type.TString>;
+        createdAt: Type.TString;
+        updatedAt: Type.TString;
+    }>>;
+}>;
+export type ProjectTasksSchemaType = Static<typeof ProjectTasksSchema>;

package/dist/schemas/tasks-schema.js

@@ -0,0 +1,41 @@
+/** JSON Schema for project-scoped Desktop tasks stored in <cwd>/.pi/tasks.jsonc. */
+import { Type } from "typebox";
+const TaskType = Type.Union([
+    Type.Literal("bug"),
+    Type.Literal("feature"),
+    Type.Literal("improvement"),
+]);
+const TaskStatus = Type.Union([
+    Type.Literal("backlog"),
+    Type.Literal("todo"),
+    Type.Literal("in-progress"),
+    Type.Literal("done"),
+]);
+const TaskPriority = Type.Union([
+    Type.Literal("low"),
+    Type.Literal("medium"),
+    Type.Literal("high"),
+    Type.Literal("urgent"),
+]);
+const ProjectTask = Type.Object({
+    id: Type.String({ minLength: 1, maxLength: 128, description: "Stable unique task id." }),
+    title: Type.String({ minLength: 1, maxLength: 200, description: "Short task title." }),
+    description: Type.Optional(Type.String({ maxLength: 10_000, description: "Optional detailed task description." })),
+    type: TaskType,
+    status: TaskStatus,
+    priority: TaskPriority,
+    sessionId: Type.Optional(Type.String({ minLength: 1, maxLength: 512, description: "Optional Pi session associated with this task." })),
+    createdAt: Type.String({ format: "date-time", description: "RFC 3339 creation timestamp." }),
+    updatedAt: Type.String({ format: "date-time", description: "RFC 3339 last-update timestamp." }),
+}, { additionalProperties: false });
+export const ProjectTasksSchema = Type.Object({
+    $schema: Type.Optional(Type.String({ description: "JSON Schema URL used by editors for validation and autocomplete." })),
+    version: Type.Literal(1, { description: "Task document format version." }),
+    tasks: Type.Array(ProjectTask, { maxItems: 10_000, description: "Project tasks. Task ids must be unique." }),
+}, {
+    $id: "https://unpkg.com/pi-ui-extend/schemas/tasks.json",
+    $schema: "https://json-schema.org/draft-07/schema#",
+    title: "Pix Project Tasks",
+    description: "Project-scoped task document stored in <cwd>/.pi/tasks.jsonc.",
+    additionalProperties: false,
+});

package/docs/concurrency.md

@@ -1,9 +1,15 @@
 # Spec: Application concurrency and lifecycle safety
 
+<!-- markdownlint-disable MD013 -->
+
 ## Type
 
 Change
 
+## Lifecycle
+
+Active implemented contract.
+
 ## Goal
 
 Keep tab, session, editor, extension UI, persistence, and shutdown work bound to

package/docs/desktop-mvp.md

@@ -4,6 +4,13 @@
 
 Change
 
+## Lifecycle
+
+Historical baseline. This document records the first Desktop vertical slice and
+still contains useful process-host/ACP transport contracts, but it is no longer
+the current feature-scope inventory. Later implemented Desktop behavior is
+specified by the `specs/desktop-*.md` family.
+
 ## Goal
 
 Provide a lightweight desktop client for Pix using Tauri 2 and Svelte 5 +
@@ -21,7 +28,11 @@ updates, cancel a running turn, and answer extension elicitations.
   elicitations.
 - Development commands and a documented local setup path.
 
-## Non-goals
+## MVP-era non-goals
+
+The items below were intentionally out of scope for the first slice. Several
+were implemented later and are governed by newer feature specs; they are not
+current product non-goals.
 
 - Feature parity with `PiUiExtendApp`.
 - Voice input, an embedded terminal, custom widgets, image attachments,

package/docs/desktop-task-manager.md

@@ -2,123 +2,134 @@
 
 ## Type
 
-Change
+As-is
+
+## Lifecycle
+
+Active current contract.
 
 ## Goal
 
-Add a project-scoped task list to Pix Desktop in a persistent left sidebar and
-allow a saved task to start work immediately in a new session tab.
+Provide a project-scoped task list in Pix Desktop and let a saved task start or
+reopen work in a Desktop session without conflating project tasks with the
+agent's session-local todo list.
 
 ## Scope
 
 - A collapsible, resizable left sidebar with `Tasks` and `Project` tabs.
-- A compact task list with create, edit, delete, filtering, and manual status
-  changes.
-- Task type (`bug`, `feature`, `improvement`), status (`backlog`, `todo`,
-  `in-progress`, `done`), and priority (`low`, `medium`, `high`, `urgent`).
-- Project-local persistence in `.pi/tasks.json` with a versioned schema.
-- Starting a task in a new ACP session, automatically sending a generated
-  prompt, marking the task in progress, and storing the new session id.
-- Opening an already-linked session instead of creating a duplicate.
+- Create, edit, delete, manual status changes, drag reordering, and moving tasks
+  between type groups.
+- Task type (`bug`, `feature`, `improvement`) and status (`backlog`, `todo`,
+  `in-progress`, `done`).
+- Persisted priority (`low`, `medium`, `high`, `urgent`). New tasks currently
+  receive `medium`; priority is not exposed by the current task editor or rows.
+- Project-local persistence in `.pi/tasks.jsonc` with a versioned schema.
+- One-time migration from the legacy strict-JSON `.pi/tasks.json` file.
+- Starting an unlinked task in a new ACP session and reopening an already-linked
+  session instead of creating a duplicate.
+- Task descriptions can contain attachment markers; those attachments are
+  resolved when the task prompt is built.
 
 ## Non-goals
 
-- Kanban, drag and drop, subtasks, dependencies, assignees, due dates,
-  comments, or task history.
+- Kanban columns, subtasks, dependencies, assignees, due dates, comments, or
+  task history.
+- Task filtering controls in the current sidebar UI.
+- Editing or displaying priority in the current sidebar UI.
 - Automatic transition to `done` when an agent turn finishes.
-- Synchronizing the project task file with the agent's session-local todo list.
+- Synchronizing `.pi/tasks.jsonc` with the agent's session-local todo list.
 - Concurrent multi-window file merging.
 
 ## Behavior
 
-1. The sidebar is visible below the title/session chrome, starts on `Tasks`,
-   remembers its width and collapsed state locally, and preserves the main
-   session workspace at narrow window sizes.
-2. Task rows show a title, type, status, priority, and actions. Status and
-   priority are communicated by a Lucide icon, text, and color so meaning never
-   depends on color alone. `done` is green, `in-progress` is yellow, and idle
-   states are neutral; all colors support light and dark themes.
-3. Creating or editing validates a non-empty title. A description is optional.
-4. Filters affect only the visible list and do not modify persisted ordering.
-5. A missing `.pi/tasks.json` is treated as an empty version-1 document.
-6. Starting an unlinked task creates and selects a new ACP session, persists
-   its id and `in-progress` status, appends the generated user prompt to the
-   transcript, and sends it immediately.
-7. Starting a linked task loads that session. A missing/stale linked session is
-   reported as a recoverable error and does not silently create another one.
-8. Task completion remains manual.
+1. The sidebar starts on `Tasks`, remembers its width/collapsed state locally,
+   and keeps a compact tab rail available while collapsed.
+2. Tasks are grouped by type. Dragging a task reorders it; dropping it into a
+   different group also changes its type and updates `updatedAt`.
+3. Task rows show title, status, session/run action, edit, and delete controls.
+   Status uses icon, text, and color rather than color alone.
+4. Creating a task requires a non-empty title, starts with status `todo` and
+   priority `medium`, and may include description text and attachments.
+5. Editing changes title, description, and type. Status is changed separately.
+   Existing persisted priority is preserved.
+6. `.pi/tasks.jsonc` is authoritative. Missing `.pi`/task storage produces an
+   empty version-1 document. JSONC comments and trailing commas are accepted.
+7. If `.pi/tasks.jsonc` is absent and legacy `.pi/tasks.json` exists, Pix reads
+   and validates the legacy document, adds the schema reference when absent,
+   writes `.pi/tasks.jsonc`, deletes the legacy file, and returns the migrated
+   document. If JSONC already exists, it wins and the legacy file is ignored.
+8. Starting an unlinked task creates/selects a new ACP session, persists its
+   session id, changes any non-`done` task to `in-progress`, preserves `done`,
+   appends the generated task prompt, and sends it immediately.
+9. Starting a linked task opens that session. A stale/missing linked session is
+   a recoverable error and does not silently create another session.
+10. Task completion remains manual.
 
 ## Contracts
 
-- Project file: `.pi/tasks.json` containing `{ version: 1, tasks: [...] }`.
-- Every task has a unique id, title, type, status, priority, `createdAt`, and
-  `updatedAt`; description and `sessionId` may be omitted.
-- Tauri exposes narrow read/write commands for this one file. Workspace paths
-  are validated and `.pi` symlinks may not escape the workspace.
-- The webview sends a complete validated document on each mutation. Writes use
-  a same-directory temporary file and replacement to avoid partial JSON.
+- Project file: `.pi/tasks.jsonc`.
+- Document shape: optional `$schema`, `version: 1`, and `tasks`.
+- Each task has a unique id, title, type, status, priority, `createdAt`, and
+  `updatedAt`; description and `sessionId` are optional.
+- Unknown fields, duplicate ids, unsupported enum values, empty titles,
+  malformed timestamps, unsupported versions, and oversized documents are
+  rejected.
+- The Tauri backend confines task paths to the active workspace, rejects escape
+  through `.pi` symlinks, and caps the document at 1 MB.
+- Writes validate the complete document, write a same-directory temporary file,
+  and replace the target to avoid partial JSONC files.
 
 ## Invariants
 
-- The task document version must be supported before it is displayed or saved.
-- Duplicate ids, unknown enum values, empty titles, and malformed timestamps
-  are rejected.
-- A task is linked to at most one session in this MVP.
-- Starting a task is disabled while another prompt/session operation is active.
-- A failed save does not leave the UI claiming a task state that was not
-  persisted.
+- Failed validation never replaces the task file.
+- Failed persistence restores the previous in-memory task document.
+- A task is linked to at most one session.
+- Running/reordering/editing is disabled while conflicting task/session work is
+  active.
+- Dragging between groups changes only ordering/type; other task fields survive.
 
 ## Edge cases
 
-- Switching workspaces discards the previous workspace's in-memory task view
-  and loads the new project file.
-- Empty and missing files have distinct behavior: missing means no tasks;
-  malformed or empty JSON is an error.
-- Save, session creation, and prompt failures remain visible and retryable.
-- Collapsing the sidebar keeps its tab rail available; choosing a tab expands
-  it.
+- Switching workspaces discards the previous in-memory task view and loads the
+  new project's task document.
+- Missing storage means no tasks; malformed or empty JSON/JSONC is an error.
+- A legacy task file is migrated at most once because successful migration
+  removes `.pi/tasks.json`.
+- Save, session creation, attachment preparation, and prompt failures remain
+  visible and retryable.
 
 ## Related files
 
 - `desktop/src/App.svelte`
-- `desktop/src/components/`
-- `desktop/src/lib/`
-- `desktop/src/styles.css`
+- `desktop/src/components/WorkspaceSidebar.svelte`
+- `desktop/src/lib/project-tasks.ts`
+- `desktop/src/lib/project-tasks.test.ts`
 - `desktop/src-tauri/src/lib.rs`
+- `src/schemas/tasks-schema.ts`
 
 ## Verification
 
-- Unit tests for task parsing, validation, filtering, prompt generation, and
-  sidebar preference parsing.
-- Rust tests for missing/read/write/malformed files and workspace escape.
-- `npm --prefix desktop test`
-- `npm --prefix desktop run check`
-- `npm --prefix desktop run build:web`
-- `cargo test --manifest-path desktop/src-tauri/Cargo.toml`
+- `desktop/src/lib/project-tasks.test.ts` covers parsing, prompt generation, and
+  drag/reorder semantics.
+- Rust tests in `desktop/src-tauri/src/lib.rs` cover missing/read/write/malformed
+  JSONC, validation, workspace confinement, and legacy JSON migration.
+- Run `npm --prefix desktop test`, `npm --prefix desktop run check`, and
+  `cargo test --manifest-path desktop/src-tauri/Cargo.toml`.
 
 ## Risks / unknowns
 
-- Whole-document writes assume one active desktop writer per project.
-- A linked session may later be removed outside Pix Desktop; the first version
-  reports this rather than automatically unlinking it.
-- Windows replacement semantics may require a fallback around replacing an
-  existing task file while retaining best-effort crash safety.
+- Whole-document writes assume one active writer per project; multi-window merge
+  semantics remain out of scope.
+- A linked session can be removed outside Pix Desktop and remains linked until
+  the user repairs or edits the task.
+- Priority remains part of the persisted schema although the current UI does not
+  expose priority editing.
 
 ## Evidence
 
-- Confirmed by code: desktop session creation/loading and prompt submission are
-  orchestrated in `desktop/src/App.svelte` through `AcpClient`.
-- Confirmed by code: Tauri already validates workspace-contained project file
-  reads in `desktop/src-tauri/src/lib.rs`.
-- Confirmed by tests: session tab ordering and ACP request behavior have focused
-  Vitest coverage under `desktop/src/lib/`.
-- Confirmed by docs: `DESIGN.md` specifies a compact persistent sidebar,
-  semantic theme roles, Lucide icons, and non-color status cues.
-- Implemented: `.pi/tasks.json` now has an explicit version-1 contract and
-  rejects unsupported versions rather than guessing a migration.
-- Verified by tests: all 82 desktop Vitest tests and all 8 Rust tests pass;
-  Svelte/TypeScript checks report no errors or warnings.
-- Verified visually: browser QA covered clean preference state, resize/collapse,
-  tabs, filters, and semantic colors in light/dark themes.
-- Verified natively: actual Tauri UI/backend CRUD, Run, persisted linkage,
-  Open session without duplication, and delete cleanup all passed.
+- Confirmed by code: `desktop/src/App.svelte`,
+  `desktop/src/components/WorkspaceSidebar.svelte`, and
+  `desktop/src/lib/project-tasks.ts` implement the current task lifecycle.
+- Confirmed by code: `desktop/src-tauri/src/lib.rs` owns JSONC persistence,
+  validation, confinement, atomic replacement, and legacy migration.
+- Confirmed by tests: project-task unit tests and Tauri task persistence tests.