sneakoscope 2.0.5 → 2.0.7

package/dist/core/agents/agent-patch-schema.js

@@ -27,6 +27,7 @@ export function normalizeAgentPatchEnvelope(input) {
         ...(input?.verification_node_id === undefined ? {} : { verification_node_id: String(input.verification_node_id) }),
         ...(input?.rollback_node_id === undefined ? {} : { rollback_node_id: String(input.rollback_node_id) }),
         ...(input?.lease_proof ? { lease_proof: normalizeLeaseProof(input.lease_proof) } : {}),
+        ...(input?.git_worktree ? { git_worktree: normalizeGitWorktreeMetadata(input.git_worktree) } : {}),
         ...(input?.rationale ? { rationale: String(input.rationale) } : {}),
         ...(input?.verification_hint ? { verification_hint: normalizeHint(input.verification_hint) } : {}),
         ...(input?.rollback_hint ? { rollback_hint: normalizeHint(input.rollback_hint) } : {}),
@@ -49,12 +50,14 @@ export function validateAgentPatchEnvelope(envelope) {
         violations.push('lease_id_missing');
     if (!envelope.operations.length)
         violations.push('operations_missing');
-    if (envelope.source && !['fixture', 'model_authored', 'process_generated', 'zellij_generated'].includes(envelope.source))
+    if (envelope.source && !['fixture', 'model_authored', 'process_generated', 'zellij_generated', 'git-worktree-diff'].includes(envelope.source))
         violations.push('source_invalid');
     if (envelope.source === 'model_authored' && !hasFiniteNumber(envelope.backend_child_process_id) && !envelope.backend_sdk_thread_id && !envelope.backend_ollama_request_id)
         violations.push('model_authored_backend_proof_missing');
     if (envelope.source === 'fixture' && envelope.backend_child_process_id !== undefined)
         violations.push('fixture_backend_child_process_id_present');
+    if (envelope.source === 'git-worktree-diff' && !envelope.git_worktree?.worktree_path)
+        violations.push('git_worktree_metadata_missing');
     for (const operation of envelope.operations) {
         if (!operation.path || operation.path.includes('\0') || operation.path.startsWith('/') || operation.path.split(/[\\/]/).includes('..')) {
             violations.push(`invalid_path:${operation.path || 'missing'}`);
@@ -74,7 +77,7 @@ export function validateAgentPatchEnvelope(envelope) {
 }
 function normalizeEnvelopeSource(value) {
     const text = String(value || '');
-    return text === 'fixture' || text === 'model_authored' || text === 'process_generated' || text === 'zellij_generated' ? text : null;
+    return text === 'fixture' || text === 'model_authored' || text === 'process_generated' || text === 'zellij_generated' || text === 'git-worktree-diff' ? text : null;
 }
 function hasFiniteNumber(value) {
     return value !== null && value !== undefined && value !== '' && Number.isFinite(Number(value));
@@ -104,6 +107,17 @@ function normalizeLeaseProof(input) {
         ...(input?.rollback_node_id === undefined ? {} : { rollback_node_id: String(input.rollback_node_id) })
     };
 }
+function normalizeGitWorktreeMetadata(input) {
+    return {
+        main_repo_root: String(input?.main_repo_root || ''),
+        worktree_path: String(input?.worktree_path || ''),
+        branch: input?.branch == null ? null : String(input.branch),
+        base_head: input?.base_head == null ? null : String(input.base_head),
+        worktree_head: input?.worktree_head == null ? null : String(input.worktree_head),
+        changed_files: Array.isArray(input?.changed_files) ? input.changed_files.map(String) : [],
+        diff_bytes: Number(input?.diff_bytes || 0)
+    };
+}
 function normalizeHint(input) {
     return {
         ...(input?.command === undefined ? {} : { command: String(input.command) }),

package/dist/core/agents/agent-proof-evidence.js

@@ -21,6 +21,7 @@ export async function writeAgentProofEvidence(root, input) {
     const scheduler = input.scheduler || await readJson(path.join(root, 'agent-scheduler-state.json'), null);
     const taskGraph = input.partition?.task_graph || await readJson(path.join(root, 'agent-task-graph.json'), null);
     const parallelWritePolicy = input.parallelWritePolicy || await readJson(path.join(root, 'agent-parallel-write-policy.json'), null);
+    const gitWorktreeRuntime = input.gitWorktreeRuntime || await readJson(path.join(root, 'agent-git-worktree-runtime.json'), null);
     const patchQueue = await readJson(path.join(root, 'agent-patch-queue.json'), null);
     const patchQueueEvents = await readTextSafe(path.join(root, 'agent-patch-queue-events.jsonl'));
     const patchMerge = await readJson(path.join(root, 'agent-merge-coordinator-report.json'), null);
@@ -119,6 +120,14 @@ export async function writeAgentProofEvidence(root, input) {
         return !changed || Boolean(row.rollback_digest);
     }) : true;
     const parallelPatchApplyVerified = patchSwarm ? Array.isArray(patchProof?.wall_clock_parallel_evidence) && patchProof.wall_clock_parallel_evidence.length > 0 || Number(patchSwarm?.parallel_apply_count || 0) > 1 : false;
+    const readOnlyNoWriteLeaseMode = isReadOnlyNoWriteLeaseMode({
+        results: input.results || [],
+        leases: input.partition?.leases || [],
+        parallelWritePolicy,
+        taskGraph,
+        narutoWorkGraph
+    });
+    const changedFileLeaseBlockers = readOnlyNoWriteLeaseMode ? [] : agentChangedFileLeaseViolations(input.results || [], input.partition?.leases || []);
     const blockers = [
         ...(lifecycle.ok ? [] : ['agent_lifecycle_not_all_closed']),
         ...(lifecycle.ok ? [] : lifecycle.open_sessions.map((id) => 'session_open:' + id)),
@@ -172,6 +181,7 @@ export async function writeAgentProofEvidence(root, input) {
         ...(noSubagentScalingPolicy?.ok === false ? noSubagentScalingPolicy.blockers || ['no_subagent_scaling_policy_not_ok'] : []),
         ...(fastModePropagation?.ok === false ? fastModePropagation.blockers || ['fast_mode_propagation_not_ok'] : []),
         ...(patchSwarm?.ok === false ? patchSwarm.blockers || ['patch_swarm_not_ok'] : []),
+        ...(gitWorktreeRuntime?.required === true && gitWorktreeRuntime?.ok === false ? gitWorktreeRuntime.blockers || ['git_worktree_runtime_not_ok'] : []),
         ...(patchSwarm && !patchQueue ? ['patch_queue_missing'] : []),
         ...(patchSwarm && !patchMerge ? ['patch_merge_report_missing'] : []),
         ...(patchSwarm && !patchApplyResults ? ['patch_apply_results_missing'] : []),
@@ -195,7 +205,7 @@ export async function writeAgentProofEvidence(root, input) {
         ...(isNarutoRoute && !narutoVerificationDag ? ['naruto_verification_dag_missing'] : []),
         ...(isNarutoRoute && !narutoGptFinalPack ? ['naruto_gpt_final_pack_missing'] : []),
         ...(isNarutoRoute && !narutoZellijDashboard ? ['naruto_zellij_dashboard_missing'] : []),
-        ...agentChangedFileLeaseViolations(input.results || [], input.partition?.leases || [])
+        ...changedFileLeaseBlockers
     ];
     const evidence = {
         schema: AGENT_PROOF_EVIDENCE_SCHEMA,
@@ -209,6 +219,7 @@ export async function writeAgentProofEvidence(root, input) {
         // Deployed Core Skill snapshot consulted at route start (read-only; never
         // confers mutation rights). Null when no snapshot is deployed for this route.
         selected_core_skill: input.selectedCoreSkill || null,
+        git_worktree_runtime: gitWorktreeRuntime,
         route_blackbox_kind: input.routeBlackboxKind || (realRouteCommandUsed ? 'actual_route_command' : 'generic_agent_route_standin'),
         real_route_command_used: realRouteCommandUsed,
         native_cli_session_proof: nativeCliSessionProof ? 'native-cli-session-proof.json' : null,
@@ -369,7 +380,7 @@ export async function writeAgentProofEvidence(root, input) {
         triwiki_use_first_count: Number(input.triwikiContext?.use_first?.length || 0),
         triwiki_hydrate_first_count: Number(input.triwikiContext?.hydrate_first?.length || 0),
         triwiki_claim_count: Number(input.triwikiContext?.claim_count || 0),
-        changed_files_lease_checked: true,
+        changed_files_lease_checked: !readOnlyNoWriteLeaseMode,
         dependency_collision_risk: input.partition?.no_overlap_proof?.dependency_collision_risk || [],
         blockers
     };
@@ -448,6 +459,20 @@ function agentChangedFileLeaseViolations(results, leases) {
     }
     return violations;
 }
+function isReadOnlyNoWriteLeaseMode(input) {
+    const writeLeaseCount = input.leases.filter((lease) => lease.kind === 'write').length;
+    if (writeLeaseCount > 0)
+        return false;
+    const resultWriteSignals = input.results.some((result) => (Array.isArray(result?.writes) && result.writes.length > 0)
+        || (Array.isArray(result?.patch_envelopes) && result.patch_envelopes.length > 0));
+    if (resultWriteSignals)
+        return false;
+    const policyReadonly = input.parallelWritePolicy?.readonly === true;
+    const policyWriteOff = String(input.parallelWritePolicy?.write_mode || 'off') === 'off';
+    const narutoReadOnly = input.narutoWorkGraph?.readonly === true || Number(input.narutoWorkGraph?.write_allowed_count || 0) === 0;
+    const taskGraphNoWrites = Number(input.taskGraph?.write_allowed_count || 0) === 0;
+    return policyReadonly || policyWriteOff || narutoReadOnly || taskGraphNoWrites;
+}
 function pathWithin(file, leasePath) {
     const left = String(file || '').replace(/\\/g, '/').replace(/^\.\//, '');
     const right = String(leasePath || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');

package/dist/core/agents/agent-worker-pipeline.js

@@ -67,7 +67,8 @@ export function validateAgentWorkerResult(result) {
         normalized.blockers.push(...patchEnvelopeValidation.blockers.map((issue) => 'patch_envelope_invalid:' + issue));
         normalized.verification = { status: 'failed', checks: [...normalized.verification.checks, 'agent-patch-envelope-schema'] };
     }
-    if (patchEnvelopeValidation.envelopes.length === 0 && (normalized.changed_files.length > 0 || normalized.writes.length > 0)) {
+    const readOnlyOrNoopWithoutPatch = acceptsNoPatchReadOnlyOrNoop(result?.no_patch_reason);
+    if (patchEnvelopeValidation.envelopes.length === 0 && (normalized.writes.length > 0 || (!readOnlyOrNoopWithoutPatch && normalized.changed_files.length > 0))) {
         normalized.status = 'blocked';
         normalized.blockers.push('no_patch_generated');
         normalized.verification = { status: 'failed', checks: [...normalized.verification.checks, 'agent-patch-envelope-required-for-write'] };
@@ -132,4 +133,11 @@ function normalizeVerification(value) {
         checks: Array.isArray(value?.checks) ? value.checks : []
     };
 }
+function acceptsNoPatchReadOnlyOrNoop(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    return value.ok === true
+        && value.read_only_or_noop_evidence === true
+        && String(value.reason || '') === 'read_only_or_no_write_paths';
+}
 //# sourceMappingURL=agent-worker-pipeline.js.map

package/dist/core/agents/native-cli-session-swarm.js

@@ -26,6 +26,8 @@ class NativeCliSessionSwarmRecorder {
         await this.persist();
     }
     async launchWorker(ctx) {
+        const worktree = normalizeWorkerWorktree(ctx.agent?.worktree || ctx.slice?.worktree || ctx.opts?.worktree || null);
+        const workerCwd = worktree?.path || ctx.opts.cwd || packageRoot();
         const workerDirRel = path.join(ctx.agent.session_artifact_dir || path.join('sessions', ctx.agent.id), 'worker');
         const workerDir = path.join(this.root, workerDirRel);
         await ensureDir(workerDir);
@@ -45,6 +47,9 @@ class NativeCliSessionSwarmRecorder {
             backend_explicit: this.input.backendExplicit === true,
             no_ollama: this.input.noOllama === true || ctx.opts.noOllama === true,
             agent_root: this.root,
+            main_repo_root: worktree?.main_repo_root || ctx.opts.cwd || packageRoot(),
+            cwd: workerCwd,
+            worktree,
             agent: ctx.agent,
             slice: ctx.slice,
             worker_artifact_dir: workerDirRel,
@@ -89,6 +94,7 @@ class NativeCliSessionSwarmRecorder {
             patch_envelope_path: patchRel,
             fast_mode: this.input.fastModePolicy.fast_mode,
             service_tier: this.input.fastModePolicy.service_tier,
+            cwd: workerCwd,
             status: 'launching',
             exit_code: null,
             blockers: []
@@ -110,7 +116,7 @@ class NativeCliSessionSwarmRecorder {
             });
         }
         const child = spawn(process.execPath, args, {
-            cwd: ctx.opts.cwd || packageRoot(),
+            cwd: workerCwd,
             env: {
                 ...process.env,
                 ...(ctx.opts.env || {}),
@@ -179,6 +185,8 @@ class NativeCliSessionSwarmRecorder {
     async launchWorkerInZellijPane(input) {
         const sessionName = String(input.ctx.opts.zellijSessionName || (this.input.missionId ? `sks-${this.input.missionId}` : 'sks-agent-runtime'));
         const slotId = String(input.ctx.agent.slot_id || input.ctx.agent.id || 'slot-001');
+        const worktree = normalizeWorkerWorktree(input.ctx.agent?.worktree || input.ctx.slice?.worktree || input.ctx.opts?.worktree || null);
+        const workerCwd = worktree?.path || input.ctx.opts.cwd || packageRoot();
         const activeToken = this.nextPaneToken--;
         this.active.add(activeToken);
         this.maxObserved = Math.max(this.maxObserved, this.active.size);
@@ -222,9 +230,10 @@ class NativeCliSessionSwarmRecorder {
             patchEnvelopePath: input.record.patch_envelope_path,
             stdoutLog: input.stdoutRel,
             stderrLog: input.stderrRel,
-            cwd: input.ctx.opts.cwd || packageRoot(),
+            cwd: workerCwd,
             providerContext,
-            serviceTier: this.input.fastModePolicy.service_tier
+            serviceTier: this.input.fastModePolicy.service_tier,
+            worktree: worktree ? { id: worktree.id, path: worktree.path, branch: worktree.branch } : null
         });
         const launchBlockers = paneRecord.blockers || [];
         input.record.command_line = ['zellij', '--session', sessionName, 'action', 'new-pane', '--direction', paneRecord.direction_applied, '--name', paneRecord.pane_name, '--', 'sh', '-lc', '<native-cli-worker-command>'];
@@ -239,6 +248,7 @@ class NativeCliSessionSwarmRecorder {
         input.record.provider = paneRecord.provider;
         input.record.service_tier = paneRecord.service_tier;
         input.record.provider_context = paneRecord.provider_context;
+        input.record.worktree = worktree;
         input.record.status = launchBlockers.length ? 'failed' : 'running';
         input.record.blockers = launchBlockers;
         await this.record(input.record);
@@ -323,7 +333,7 @@ class NativeCliSessionSwarmRecorder {
         paneRecord = await closeWorkerPane({
             root: this.root,
             paneRecord,
-            cwd: input.ctx.opts.cwd || packageRoot(),
+            cwd: workerCwd,
             status: input.record.status === 'closed' ? 'closed' : 'failed',
             blockers: input.record.blockers,
             sdkThreadId,
@@ -462,4 +472,15 @@ function redactWorkerArgs(args) {
 function shellQuote(value) {
     return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
+function normalizeWorkerWorktree(value) {
+    const pathValue = value?.path || value?.worktree_path;
+    if (!pathValue)
+        return null;
+    return {
+        id: String(value?.id || value?.worktree_id || value?.slot_id || 'worktree'),
+        path: String(pathValue),
+        branch: String(value?.branch || 'unknown'),
+        main_repo_root: value?.main_repo_root == null ? null : String(value.main_repo_root)
+    };
+}
 //# sourceMappingURL=native-cli-session-swarm.js.map

package/dist/core/agents/native-cli-worker.js

@@ -27,6 +27,8 @@ export async function runNativeCliWorker(input = {}) {
     };
     const slice = intake.slice || {};
     const backend = String(input.backend || intake.backend || 'fake');
+    const workerCwd = path.resolve(String(input.cwd || intake.cwd || process.cwd()));
+    const worktree = normalizeWorkerWorktree(input.worktree || intake.worktree || null);
     const policy = resolveFastModePolicy({
         fastMode: intake.fast_mode ?? input.fastMode,
         serviceTier: intake.service_tier ?? input.serviceTier
@@ -37,6 +39,10 @@ export async function runNativeCliWorker(input = {}) {
     const heartbeatRel = String(input.heartbeatPath || intake.heartbeat_path || path.join(workerDirRel, 'worker-heartbeat.jsonl'));
     const patchRel = String(input.patchEnvelopePath || intake.patch_envelope_path || path.join(workerDirRel, 'worker-patch-envelope.json'));
     await ensureDir(workerDir);
+    try {
+        process.chdir(workerCwd);
+    }
+    catch { }
     const recursion = scanAgentTextForRecursion(JSON.stringify({ agent, slice, backend }));
     const guard = {
         schema: 'sks.native-cli-worker-recursion-guard.v1',
@@ -56,6 +62,9 @@ export async function runNativeCliWorker(input = {}) {
         persona_id: String(agent.persona_id || input.personaId || ''),
         lease_id: String(intake.lease_id || input.leaseId || ''),
         agent_root: agentRoot,
+        main_repo_root: String(input.mainRepoRoot || intake.main_repo_root || worktree?.main_repo_root || agentRoot),
+        cwd: workerCwd,
+        worktree,
         worker_artifact_dir: workerDirRel,
         result_path: resultRel,
         heartbeat_path: heartbeatRel,
@@ -65,7 +74,9 @@ export async function runNativeCliWorker(input = {}) {
             backend: backend === 'zellij' ? 'codex-sdk' : backend,
             output_schema_id: 'sks.agent-worker-result.v1',
             sandbox_policy: Array.isArray(slice.write_paths) && slice.write_paths.length > 0 ? 'workspace-write' : 'read-only',
-            thread_policy: 'new_thread_per_generation'
+            thread_policy: 'new_thread_per_generation',
+            worktree,
+            cwd: workerCwd
         },
         service_tier: policy.service_tier,
         fast_mode: policy.fast_mode,
@@ -143,6 +154,8 @@ export async function runNativeCliWorker(input = {}) {
         generated_at: nowIso(),
         ok: guard.ok,
         backend,
+        cwd: workerCwd,
+        worktree,
         agent_id: agent.id,
         session_id: agent.session_id,
         slot_id: agent.slot_id || null,
@@ -221,6 +234,9 @@ export async function runNativeCliWorker(input = {}) {
         slot_id: agent.slot_id || null,
         generation_index: agent.generation_index || null,
         process_id: process.pid,
+        main_repo_root: String(input.mainRepoRoot || intake.main_repo_root || worktree?.main_repo_root || agentRoot),
+        cwd: workerCwd,
+        worktree,
         artifact_dir: workerDirRel,
         patch_envelope: patchEnvelopes.length ? patchRel : null,
         no_patch_reason: patchEnvelopes.length ? null : path.join(workerDirRel, 'worker-no-patch-reason.json'),
@@ -290,4 +306,15 @@ function redactCommandLine(argv) {
         return part;
     });
 }
+function normalizeWorkerWorktree(value) {
+    const pathValue = value?.path || value?.worktree_path;
+    if (!pathValue)
+        return null;
+    return {
+        id: String(value?.id || value?.worktree_id || value?.slot_id || 'worktree'),
+        path: String(pathValue),
+        branch: String(value?.branch || 'unknown'),
+        main_repo_root: value?.main_repo_root == null ? null : String(value.main_repo_root)
+    };
+}
 //# sourceMappingURL=native-cli-worker.js.map

package/dist/core/agents/native-worker-backend-router.js

@@ -57,6 +57,7 @@ export async function runNativeWorkerBackendRouter(input) {
         result = validateAgentWorkerResult({
             ...processRun,
             patch_envelopes: patchEnvelopes,
+            ...(patchEnvelopes.length ? {} : { no_patch_reason: buildNoPatchReason(input, backend) }),
             artifacts: [...new Set([...(processRun.artifacts || []), ...(patchEnvelopes.length ? [input.patchRel] : [])])],
             process_child_report: processReport,
             model_authored_patch_envelopes: false,
@@ -81,6 +82,7 @@ export async function runNativeWorkerBackendRouter(input) {
             ...ollamaRun,
             backend: 'ollama',
             patch_envelopes: patchEnvelopes,
+            ...(patchEnvelopes.length ? {} : { no_patch_reason: buildNoPatchReason(input, backend) }),
             model_authored_patch_envelopes: patchEnvelopes.length > 0,
             fixture_patch_envelopes: false,
             verification: { status: ollamaRun.status === 'done' ? 'passed' : 'failed', checks: [...(ollamaRun.verification?.checks || []), 'native-worker-backend-router', 'ollama-api-generate'] }
@@ -147,6 +149,7 @@ export async function runNativeWorkerBackendRouter(input) {
             ...sdkWorkerResult,
             backend: sdkTask.backend === 'local-llm' ? 'local-llm' : 'codex-sdk',
             patch_envelopes: patchEnvelopes,
+            ...(patchEnvelopes.length ? {} : { no_patch_reason: buildNoPatchReason(input, sdkTask.backend || backend) }),
             codex_child_report: sdkReport,
             codex_sdk_thread: sdkReport,
             model_authored_patch_envelopes: patchEnvelopes.length > 0,
@@ -189,6 +192,7 @@ export async function runNativeWorkerBackendRouter(input) {
         result = validateAgentWorkerResult({
             ...zellijRun,
             patch_envelopes: patchEnvelopes,
+            ...(patchEnvelopes.length ? {} : { no_patch_reason: buildNoPatchReason(input, backend) }),
             zellij_child_report: zellijReport,
             model_authored_patch_envelopes: false,
             fixture_patch_envelopes: false,
@@ -279,10 +283,24 @@ function buildWorkerPrompt(slice) {
         '',
         write.length
             ? `Write-capable slice. Return JSON matching ${CODEX_AGENT_WORKER_RESULT_SCHEMA_ID}; include patch_envelopes for write_paths=${JSON.stringify(write)}.`
-            : `Read-only slice. Return JSON matching ${CODEX_AGENT_WORKER_RESULT_SCHEMA_ID}.`,
+            : `Read-only slice. Return JSON matching ${CODEX_AGENT_WORKER_RESULT_SCHEMA_ID}; do not report pre-existing repository dirtiness as changed_files.`,
         'Required JSON fields: status, summary, findings, changed_files, patch_envelopes, verification, rollback_notes, blockers.'
     ].join('\n');
 }
+function buildNoPatchReason(input, backend) {
+    const writePathCount = writePaths(input.slice, input.intake).length;
+    return {
+        schema: 'sks.native-cli-worker-no-patch-reason.v1',
+        generated_at: nowIso(),
+        ok: writePathCount === 0,
+        reason: writePathCount ? 'write_capable_task_without_backend_patch_envelope' : 'read_only_or_no_write_paths',
+        route_justification: writePathCount ? 'backend returned no patch envelopes for a write-capable task' : 'task has no write paths',
+        read_only_or_noop_evidence: writePathCount === 0,
+        task_slice_id: input.slice?.id || null,
+        backend,
+        blockers: writePathCount && backend !== 'fake' ? ['write_capable_no_patch_envelope'] : []
+    };
+}
 function hasWriteLease(slice, intake) {
     return writePaths(slice, intake).length > 0;
 }

package/dist/core/codex-app.js

@@ -4,6 +4,8 @@ import fsp from 'node:fs/promises';
 import { exists, runProcess } from './fsx.js';
 import { EMPTY_CODEX_INFO, getCodexInfo } from './codex-adapter.js';
 import { CODEX_CHROME_EXTENSION_DOC_URL, DEFAULT_CODEX_APP_PLUGINS as DEFAULT_CODEX_APP_PLUGIN_TUPLES, RESERVED_CODEX_PLUGIN_SKILL_NAMES } from './routes.js';
+import { PRODUCT_DESIGN_PLUGIN, normalizeProductDesignPluginEvidence } from './product-design-plugin.js';
+import { PRODUCT_DESIGN_AUTO_INSTALL_ENV, ensureProductDesignPluginInstalled, productDesignAutoInstallRequested } from './product-design-app-server.js';
 export const CODEX_APP_DOCS_URL = 'https://developers.openai.com/codex/app/features';
 export const CODEX_CHANGELOG_URL = 'https://developers.openai.com/codex/changelog';
 export const CODEX_ACCESS_TOKENS_DOCS_URL = 'https://developers.openai.com/codex/enterprise/access-tokens';
@@ -128,6 +130,7 @@ export async function codexAppIntegrationStatus(opts = {}) {
     const chromePath = await findPluginCache('chrome', opts);
     const computerUsePath = await findPluginCache('computer-use', opts);
     const defaultPlugins = await codexDefaultPluginStatus(opts);
+    const productDesignPlugin = await codexProductDesignPluginStatus(opts);
     const pluginSkillShadows = await codexPluginSkillShadowStatus(opts);
     const fastModeConfig = await codexFastModeConfigStatus(opts);
     const computerUseMcpListed = /computer[-_ ]?use/i.test(mcpText);
@@ -209,6 +212,7 @@ export async function codexAppIntegrationStatus(opts = {}) {
             browser_use_cache: browserUsePath,
             chrome_cache: chromePath,
             default_plugins: defaultPlugins,
+            design_product: productDesignPlugin,
             skill_shadows: pluginSkillShadows,
             picker: {
                 ok: pluginPickerReady,
@@ -219,7 +223,7 @@ export async function codexAppIntegrationStatus(opts = {}) {
             }
         },
         chrome_extension: chromeExtension,
-        guidance: codexAppGuidance({ appInstalled, codex, mcpList, featureList, requiredFeatureFlags, requiredFeatureFlagsOk, defaultPlugins, pluginSkillShadows, fastModeConfig, gitActions, imageGenerationReady, inAppBrowserReady, browserUseFeatureReady, computerUseReady, browserUseReady, browserToolReady, computerUseMcpListed, browserUseMcpListed, chromeExtension, remoteControl })
+        guidance: codexAppGuidance({ appInstalled, codex, mcpList, featureList, requiredFeatureFlags, requiredFeatureFlagsOk, defaultPlugins, productDesignPlugin, pluginSkillShadows, fastModeConfig, gitActions, imageGenerationReady, inAppBrowserReady, browserUseFeatureReady, computerUseReady, browserUseReady, browserToolReady, computerUseMcpListed, browserUseMcpListed, chromeExtension, remoteControl })
     };
 }
 export async function codexChromeExtensionStatus(opts = {}) {
@@ -438,7 +442,7 @@ export function codexAccessTokenStatus(env = process.env) {
             : ['No CODEX_ACCESS_TOKEN detected in the current process environment. This is fine for interactive ChatGPT login or API-key auth.']
     };
 }
-export function codexAppGuidance({ appInstalled, codex, mcpList, featureList, requiredFeatureFlags = {}, requiredFeatureFlagsOk = true, defaultPlugins = { ok: true, missing_enabled: [] }, pluginSkillShadows = { ok: true, blocking: [] }, fastModeConfig = { ok: true, blockers: [] }, gitActions = { ok: true, blockers: [] }, imageGenerationReady, inAppBrowserReady, browserUseFeatureReady, computerUseReady, browserUseReady, browserToolReady, computerUseMcpListed, browserUseMcpListed, chromeExtension, remoteControl }) {
+export function codexAppGuidance({ appInstalled, codex, mcpList, featureList, requiredFeatureFlags = {}, requiredFeatureFlagsOk = true, defaultPlugins = { ok: true, missing_enabled: [] }, productDesignPlugin = null, pluginSkillShadows = { ok: true, blocking: [] }, fastModeConfig = { ok: true, blockers: [] }, gitActions = { ok: true, blockers: [] }, imageGenerationReady, inAppBrowserReady, browserUseFeatureReady, computerUseReady, browserUseReady, browserToolReady, computerUseMcpListed, browserUseMcpListed, chromeExtension, remoteControl }) {
     const lines = [];
     if (!appInstalled) {
         lines.push('Install and open Codex App for first-party MCP/plugin tools. SKS Zellij launch can still run with Codex CLI alone, but Codex Computer Use and imagegen/gpt-image-2 evidence will be unavailable until Codex App is ready.');
@@ -474,6 +478,18 @@ export function codexAppGuidance({ appInstalled, codex, mcpList, featureList, re
         lines.push(`Codex default plugin source(s) missing: ${defaultPlugins.missing_installed.join(', ')}. The @ plugin picker can hide built-in surfaces when plugin files are absent even if config says enabled.`);
         lines.push('Run: sks doctor --fix, then restart Codex App if the plugin cache was just restored.');
     }
+    if (productDesignPlugin?.ok) {
+        lines.push(`Product Design plugin is ready for design routes via ${productDesignPlugin.source || 'verified evidence'} (${productDesignPlugin.id}).`);
+    }
+    else if (productDesignPlugin?.auto_install?.attempted) {
+        lines.push(`Product Design auto-install was attempted but did not produce ready evidence: ${(productDesignPlugin.blockers || []).join(', ') || 'unverified'}. Recheck with: ${productDesignPlugin.auto_install.command}`);
+    }
+    else if (productDesignPlugin?.app_server?.checked && !productDesignPlugin.app_server.ok) {
+        lines.push(`Product Design app-server lookup ran but is not ready: ${(productDesignPlugin.blockers || []).join(', ') || 'unverified'}. Run: ${productDesignPlugin.auto_install?.command || 'sks codex-app product-design --json'}`);
+    }
+    else if (productDesignPlugin?.remote_lookup_required) {
+        lines.push(`Product Design is a remote vertical marketplace plugin and may not appear in \`codex plugin list\`; design routes should run ${productDesignPlugin.auto_install?.command || 'sks codex-app product-design --json'} or set ${PRODUCT_DESIGN_AUTO_INSTALL_ENV}=1 before falling back to legacy design.md skills.`);
+    }
     if (pluginSkillShadows?.generated?.length) {
         const names = pluginSkillShadows.generated.map((entry) => `${entry.name}:${entry.scope}`).join(', ');
         lines.push(`Codex plugin picker generated skill shadow(s) detected: ${names}. Generated SKS skills with first-party plugin names can hide @ plugin entries after upgrades.`);
@@ -536,6 +552,7 @@ export function formatCodexAppStatus(status, { includeRaw = false } = {}) {
         `App Flags:  ${status.features?.required_flags_ok ? 'ok' : `missing ${missingRequiredFeatureFlags(status.features?.required_flags).join(', ') || 'required flags'}`}`,
         `Fast UI:    ${status.features?.fast_mode_config?.ok ? 'ok' : `locked ${(status.features?.fast_mode_config?.blockers || []).join(', ') || 'config'}`}`,
         `Default Plugins:${status.plugins?.default_plugins?.ok ? ' ok' : ` missing ${defaultPluginMissingSummary(status.plugins?.default_plugins) || 'plugin install/config'}`}`,
+        `Product Design:${productDesignStatusSummary(status.plugins?.design_product)}`,
         `Plugin Picker:${status.plugins?.picker?.ok ? ' ok' : ` blocked ${pluginPickerBlockers(status).join(', ') || 'config'}`}`,
         `Git Actions:${status.features?.git_actions?.ok ? ' ok' : ` blocked ${(status.features?.git_actions?.blockers || []).join(', ') || 'config'}`}`,
         `Chrome Ext: ${status.chrome_extension?.ok ? 'ok' : `setup ${(status.chrome_extension?.blockers || []).join(', ') || 'required'}`}`,
@@ -552,6 +569,30 @@ export function formatCodexAppStatus(status, { includeRaw = false } = {}) {
         lines.push('', status.features.stdout.trim());
     return lines.join('\n');
 }
+export function formatCodexProductDesignPluginStatus(status) {
+    const lines = [
+        'Codex App Product Design Plugin',
+        '',
+        `Ready:        ${status.ok ? 'yes' : 'no'}`,
+        `Installed:    ${status.installed ? 'yes' : 'no'}`,
+        `Enabled:      ${status.enabled === true ? 'yes' : status.enabled === false ? 'no' : 'unknown'}`,
+        `Source:       ${status.source || 'unverified'}`,
+        `Marketplace:  ${status.marketplace}`,
+        `Remote ID:    ${status.remote_plugin_id}`,
+        `Auto Install: ${status.auto_install?.requested ? 'requested' : 'not requested'}${status.auto_install?.attempted ? ' (attempted)' : ''}`,
+        `Command:      ${status.auto_install?.command || 'sks codex-app product-design --json'}`,
+        '',
+        ...(status.blockers || []).map((blocker) => `- ${blocker}`)
+    ];
+    if (status.remote_evidence?.missing_skills?.length) {
+        lines.push(`- missing skills: ${status.remote_evidence.missing_skills.join(', ')}`);
+    }
+    if (status.ok)
+        lines.push('- Product Design is ready for design routes.');
+    else if (!status.auto_install?.requested)
+        lines.push('- Run `sks codex-app product-design --json`, or set SKS_PRODUCT_DESIGN_AUTO_INSTALL=1 for design-route auto-ensure.');
+    return lines.join('\n');
+}
 function summarizeCodexMcpError(text) {
     const cleanLines = String(text || '')
         .split(/\r?\n/)
@@ -629,6 +670,76 @@ async function codexDefaultPluginStatus(opts = {}) {
         missing_enabled: missingEnabled
     };
 }
+export async function codexProductDesignPluginStatus(opts = {}) {
+    const home = opts.home || os.homedir();
+    const cwd = opts.cwd || process.cwd();
+    const globalConfigPath = path.join(home || '', '.codex', 'config.toml');
+    const projectConfigPath = path.join(cwd || '', '.codex', 'config.toml');
+    const globalConfig = await readTextIfExists(globalConfigPath);
+    const projectConfig = path.resolve(projectConfigPath) === path.resolve(globalConfigPath)
+        ? ''
+        : await readTextIfExists(projectConfigPath);
+    const configText = `${globalConfig}\n${projectConfig}`;
+    const plugin = { name: PRODUCT_DESIGN_PLUGIN.name, marketplace: PRODUCT_DESIGN_PLUGIN.marketplace };
+    const autoInstallProductDesign = productDesignAutoInstallRequested(opts);
+    const appServerStatus = opts.productDesignAppServerStatus || (autoInstallProductDesign
+        ? await ensureProductDesignPluginInstalled({
+            ...opts,
+            autoInstallProductDesign
+        })
+        : null);
+    const injectedRemoteEvidence = opts.productDesignPluginReadResponse
+        ? normalizeProductDesignPluginEvidence(opts.productDesignPluginReadResponse)
+        : null;
+    const appServerEvidence = appServerStatus?.remote_evidence?.schema === 'sks.product-design-plugin-evidence.v1'
+        ? appServerStatus.remote_evidence
+        : null;
+    const remoteEvidence = appServerEvidence || injectedRemoteEvidence;
+    const localSource = await findDefaultPluginSource(plugin, { home, configText });
+    const configEnabled = codexPluginEnabled(configText, plugin);
+    const enabled = remoteEvidence?.enabled === true ? true : configEnabled ? true : null;
+    const installed = Boolean(localSource) || remoteEvidence?.installed === true;
+    const ok = Boolean(remoteEvidence?.ok || (installed && enabled === true));
+    const remoteLookupRequired = !remoteEvidence?.ok && (!localSource || enabled !== true) && !appServerStatus?.checked;
+    const blockers = ok ? [] : Array.from(new Set([
+        ...(!installed ? ['product_design_plugin_not_installed_or_not_locally_visible'] : []),
+        ...(enabled !== true ? ['product_design_plugin_enabled_state_requires_remote_evidence'] : []),
+        ...(remoteLookupRequired ? ['product_design_remote_vertical_lookup_required'] : []),
+        ...(autoInstallProductDesign && appServerStatus && !appServerStatus.ok ? ['product_design_app_server_install_failed'] : []),
+        ...(appServerStatus?.blockers || [])
+    ]));
+    return {
+        schema: 'sks.codex-product-design-plugin-status.v1',
+        ok,
+        checked: true,
+        route_required_only: true,
+        id: PRODUCT_DESIGN_PLUGIN.id,
+        name: PRODUCT_DESIGN_PLUGIN.name,
+        display_name: PRODUCT_DESIGN_PLUGIN.display_name,
+        marketplace: PRODUCT_DESIGN_PLUGIN.marketplace,
+        marketplace_kind: PRODUCT_DESIGN_PLUGIN.marketplace_kind,
+        remote_plugin_id: PRODUCT_DESIGN_PLUGIN.remote_plugin_id,
+        installed,
+        enabled,
+        source: remoteEvidence?.ok
+            ? appServerStatus?.install_attempted ? 'app_server_plugin_install' : 'app_server_plugin_read'
+            : localSource ? 'local_plugin_cache_or_marketplace_source' : null,
+        local_source: localSource,
+        remote_evidence: remoteEvidence,
+        app_server: appServerStatus,
+        auto_install: {
+            requested: autoInstallProductDesign,
+            attempted: Boolean(appServerStatus?.install_attempted),
+            command: 'sks codex-app product-design --json',
+            env: PRODUCT_DESIGN_AUTO_INSTALL_ENV
+        },
+        remote_lookup_required: remoteLookupRequired,
+        app_server_read_params: PRODUCT_DESIGN_PLUGIN.app_server.read_params,
+        app_server_install_params: PRODUCT_DESIGN_PLUGIN.app_server.install_params,
+        app_server_list_params: PRODUCT_DESIGN_PLUGIN.app_server.list_params,
+        blockers
+    };
+}
 async function codexPluginSkillShadowStatus(opts = {}) {
     const home = opts.home || os.homedir();
     const cwd = opts.cwd || process.cwd();
@@ -754,6 +865,17 @@ function pluginPickerBlockers(status = {}) {
         out.push('fast_mode_config');
     return out;
 }
+function productDesignStatusSummary(status = {}) {
+    if (status.ok)
+        return ' ok';
+    if (status.auto_install?.attempted)
+        return ' install unverified';
+    if (status.remote_lookup_required)
+        return ' remote lookup required';
+    if (status.app_server?.checked)
+        return ' app-server unverified';
+    return ' not checked';
+}
 function defaultPluginMissingSummary(defaultPlugins = {}) {
     return [
         ...(defaultPlugins?.missing_installed || []),