From e641c8b9ab558602320e1f865ce25b92443301f9 Mon Sep 17 00:00:00 2001
From: potaser <h4erj@outlook.com>
Date: Wed, 5 Aug 2026 09:40:45 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E8=BD=BB=E9=87=8F=E6=8B=93=E5=B1=95?=
 =?UTF-8?q?=E5=88=86=E6=9E=90=20+=20WGS2GWAS=20=E9=98=B6=E6=AE=B5=E6=94=AF?=
 =?UTF-8?q?=E6=8C=81=20+=20=E7=BB=93=E6=9E=9C=E5=8C=BA=E5=9F=9F=E9=87=8D?=
 =?UTF-8?q?=E6=9E=84=20+=20=E7=89=A9=E7=A7=8D=E8=A7=92=E8=89=B2=E8=A7=A3?=
 =?UTF-8?q?=E6=9E=90=E5=A2=9E=E5=BC=BA=20+=20=E4=BC=9A=E8=AF=9D=20Job=20?=
 =?UTF-8?q?=E9=9A=94=E7=A6=BB?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

【轻量拓展分析】
- 新增 gfa_core/extension_stage_lightweight/ 核心模块，支持用户上传代码/数据/原始命令
- 前端卡片式交互流程：候选核对 → 验证 → 结果审查 → 授权发布 → 运行
- Celery 不受限任务 + 轮询机制 + sessionStorage 操作恢复
- 启动脚本新增 BBAV5_LIGHTWEIGHT_* 环境变量

【WGS2GWAS 支持】
- 新增 13 个 WGS 阶段定义（QC → MAF/Missing Filter）
- email_haplotype_region.py 新增 LTR-RT 分析功能

【结果区域重构】
- 单层折叠 → 三组双层折叠：RNA-seq / 基因家族 / WGS2GWAS
- 结果按执行时间排序，保留最新尝试

【物种角色解析增强】
- 新增 _resolve_subfamily_request_species_roles()
- 支持 reference 角色的识别
- 直接 stage 请求保留 intent 中的物种角色

【会话 Job 隔离】
- rebind_job() 跨 job 时创建新会话，返回新 conversation_id

【前端交互增强】
- RAG 文献问答模式
- NL 触发 config/samples 自动填写、亚家族确认表、基因家族成员确认表
- 执行状态从后端 resource_tasks 恢复

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 apps/web/pipeline_backend.py                  |   32 +-
 apps/web/vue3/index.html                      | 1195 +++++++++-
 apps/web/vue3/main.py                         |  216 +-
 celery_app.py                                 |    4 +
 .../extension_stage/raw_package_normalizer.py |  182 ++
 .../extension_stage_lightweight/__init__.py   |   20 +
 gfa_core/extension_stage_lightweight/api.py   |  739 ++++++
 .../command_model.py                          |  454 ++++
 .../confirmation.py                           |  181 ++
 .../extension_stage_lightweight/converter.py  |  207 ++
 .../deepseek_semantics.py                     |  397 ++++
 .../extension_stage_lightweight/evidence.py   |  176 ++
 .../process_control.py                        |  389 +++
 .../runtime_binding.py                        | 2105 +++++++++++++++++
 .../semantic_model.py                         |  410 ++++
 .../semantic_repair.py                        |  376 +++
 .../extension_stage_lightweight/service.py    |  795 +++++++
 gfa_core/gene_family_scope.py                 |    1 +
 gfa_core/gene_family_stage_context.py         |    2 +-
 gfa_core/mas/agents/router_runtime.py         |   22 +
 gfa_core/mas/artifact_resolver.py             |    1 +
 gfa_core/mas/persistent_conversation.py       |   29 +-
 gfa_core/mas/tools/stage_tools.py             |    1 +
 start_celery_9000.sh                          |    4 +
 start_plantai_9000.sh                         |    4 +
 tasks.py                                      |   31 +-
 tests/unit/test_autofill_entrypoints.py       |   33 +-
 .../test_extension_stage_lightweight_api.py   |  930 ++++++++
 ...tension_stage_lightweight_command_model.py |  373 +++
 ...xtension_stage_lightweight_confirmation.py |  287 +++
 ...on_stage_lightweight_deepseek_semantics.py |  364 +++
 ...st_extension_stage_lightweight_evidence.py |   99 +
 ...tension_stage_lightweight_fact_contract.py |  123 +
 ...ion_stage_lightweight_frontend_contract.py |  250 ++
 ...nsion_stage_lightweight_process_control.py |  583 +++++
 ...tage_lightweight_raw_package_normalizer.py |   62 +
 ...test_extension_stage_lightweight_replay.py |   96 +
 ...nsion_stage_lightweight_runtime_binding.py |  467 ++++
 ...ge_lightweight_runtime_binding_resolver.py |  630 +++++
 ...nsion_stage_lightweight_runtime_package.py | 1459 ++++++++++++
 ...ension_stage_lightweight_semantic_model.py |  472 ++++
 ...nsion_stage_lightweight_semantic_repair.py |  477 ++++
 ...est_extension_stage_lightweight_service.py |  576 +++++
 ...tension_stage_lightweight_shell_binding.py |   57 +
 ...ension_stage_lightweight_shell_pipeline.py |   41 +
 ...sion_stage_lightweight_target_launchers.py |   25 +
 .../test_frontend_cpu_monitor_contract.py     |   13 +
 ...t_frontend_execution_indicator_recovery.py |   40 +
 .../test_gene_family_scope_reference_roots.py |   11 +
 ...t_persistent_conversation_job_isolation.py |   53 +
 tests/unit/test_result_browser_persistence.py |   77 +
 .../unit/test_stage_tool_tree_passthrough.py  |   62 +
 tests/unit/test_subfamily_prediction_plan.py  |  290 +++
 53 files changed, 15831 insertions(+), 92 deletions(-)
 create mode 100644 gfa_core/extension_stage/raw_package_normalizer.py
 create mode 100644 gfa_core/extension_stage_lightweight/__init__.py
 create mode 100644 gfa_core/extension_stage_lightweight/api.py
 create mode 100644 gfa_core/extension_stage_lightweight/command_model.py
 create mode 100644 gfa_core/extension_stage_lightweight/confirmation.py
 create mode 100644 gfa_core/extension_stage_lightweight/converter.py
 create mode 100644 gfa_core/extension_stage_lightweight/deepseek_semantics.py
 create mode 100644 gfa_core/extension_stage_lightweight/evidence.py
 create mode 100644 gfa_core/extension_stage_lightweight/process_control.py
 create mode 100644 gfa_core/extension_stage_lightweight/runtime_binding.py
 create mode 100644 gfa_core/extension_stage_lightweight/semantic_model.py
 create mode 100644 gfa_core/extension_stage_lightweight/semantic_repair.py
 create mode 100644 gfa_core/extension_stage_lightweight/service.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_api.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_command_model.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_confirmation.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_deepseek_semantics.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_evidence.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_fact_contract.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_frontend_contract.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_process_control.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_raw_package_normalizer.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_replay.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_runtime_binding.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_runtime_binding_resolver.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_runtime_package.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_semantic_model.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_semantic_repair.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_service.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_shell_binding.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_shell_pipeline.py
 create mode 100644 tests/unit/test_extension_stage_lightweight_target_launchers.py
 create mode 100644 tests/unit/test_frontend_cpu_monitor_contract.py
 create mode 100644 tests/unit/test_frontend_execution_indicator_recovery.py
 create mode 100644 tests/unit/test_gene_family_scope_reference_roots.py
 create mode 100644 tests/unit/test_persistent_conversation_job_isolation.py
 create mode 100644 tests/unit/test_result_browser_persistence.py
 create mode 100644 tests/unit/test_stage_tool_tree_passthrough.py

diff --git a/apps/web/pipeline_backend.py b/apps/web/pipeline_backend.py
index d4c12267a..7834670b4 100644
--- a/apps/web/pipeline_backend.py
+++ b/apps/web/pipeline_backend.py
@@ -1073,14 +1073,22 @@ def resolve_scoped_protein_fasta_from_phylogeny(
     )
 
 
-def resolve_scoped_tree_from_phylogeny(
-    ws: Path,
-    final_dir: Path,
-    prefix: str,
-    scope_path: Path,
-) -> tuple[Path, dict]:
-    scope_data = read_scope(scope_path)
-    manifest_candidates = stage_manifest_candidates(final_dir, "phylogeny", prefix, scope_data)
+def resolve_scoped_tree_from_phylogeny(
+    ws: Path,
+    final_dir: Path,
+    prefix: str,
+    scope_path: Path,
+    explicit_tree_file: str = "",
+) -> tuple[Path, dict]:
+    scope_data = read_scope(scope_path)
+    if explicit_tree_file:
+        selected_tree = Path(explicit_tree_file).expanduser()
+        if not selected_tree.is_absolute():
+            selected_tree = ws / selected_tree
+        if selected_tree.exists() and selected_tree.stat().st_size > 0:
+            return selected_tree.resolve(), scope_data
+        raise FileNotFoundError(f"Specified scoped tree file not found: {explicit_tree_file}")
+    manifest_candidates = stage_manifest_candidates(final_dir, "phylogeny", prefix, scope_data)
 
     for manifest_file in manifest_candidates:
         if not manifest_file.exists():
@@ -8261,7 +8269,13 @@ def run_stage(
             if member_set_id:
                 cmd += ["--member-set-id", member_set_id]
             try:
-                motif_tree_file, _motif_scope_data = resolve_scoped_tree_from_phylogeny(ws, final_dir, prefix, scope_path)
+                motif_tree_file, _motif_scope_data = resolve_scoped_tree_from_phylogeny(
+                    ws,
+                    final_dir,
+                    prefix,
+                    scope_path,
+                    explicit_tree_file=tree_file,
+                )
                 cmd += ["--tree", str(motif_tree_file)]
                 motif_scope_id = str(_motif_scope_data.get("scope_id") or "")
             except Exception as exc:
diff --git a/apps/web/vue3/index.html b/apps/web/vue3/index.html
index a4a27f036..c1acbfe65 100644
--- a/apps/web/vue3/index.html
+++ b/apps/web/vue3/index.html
@@ -1383,6 +1383,7 @@
                                 </el-option>
                             </el-select>
                             <span>名称</span><el-input v-model="extensionBuild.displayName" size="small" placeholder="例如 HMMER hmmsearch"></el-input>
+                            <span>原始命令</span><el-input v-model="extensionBuild.command" size="small" placeholder="例如 bash run.sh input.fa"></el-input>
                             <span>环境</span>
                             <el-select v-model="extensionBuild.runtimeEnv" size="small">
                                 <el-option label="test4py311" value="test4py311"></el-option>
@@ -1405,6 +1406,13 @@
                                     <el-button size="small" text @click="removeExtensionFile('data', file)">移除</el-button>
                                 </div>
                             </div>
+                            <span>服务器测试数据路径</span>
+                            <el-input
+                                v-model="extensionBuild.dataPaths"
+                                type="textarea"
+                                :rows="3"
+                                placeholder="大文件可直接引用；每行填写一个绝对路径">
+                            </el-input>
                         </div>
                         <div style="display:flex; gap:6px; margin-top:9px; align-items:center; justify-content:space-between; flex-wrap:nowrap;">
                             <el-button
@@ -1414,6 +1422,9 @@
                                 @click="buildExtensionStage">
                                 生成并发布
                             </el-button>
+                            <el-button v-if="isLightweightExtensionSelected" size="small" type="success" @click="openLightweightRuntimeCard()">
+                                运行已发布
+                            </el-button>
                             <el-button size="small" @click="loadExtensionRuns(); extensionResultDialogVisible = true">运行结果</el-button>
                         </div>
                     </div>
@@ -2136,8 +2147,51 @@
                         </div>
                     </div>
 
+                    <div v-if="lightweightExtensionConversation.cards.length" style="display:flex;flex-direction:column;gap:8px;">
+                        <div v-for="card in lightweightExtensionConversation.cards" :key="card.card_id + ':' + card.status" style="display:flex;justify-content:flex-start;align-items:flex-start;gap:10px;margin-bottom:6px;">
+                            <div class="role-badge ai">AI</div>
+                            <div class="execution-log-item assistant" style="width:min(760px,95%);font-size:12px;line-height:1.55;">
+                                <div style="display:flex;justify-content:space-between;gap:8px;align-items:start;">
+                                    <div>
+                                        <div style="font-weight:600;color:#303133;">{{ card.title }}</div>
+                                        <div style="color:#606266;margin-top:2px;">{{ card.purpose }}</div>
+                                    </div>
+                                    <el-tag size="small" :type="card.type || 'info'">{{ card.status_label || card.status }}</el-tag>
+                                </div>
+                                <div v-if="card.summary" style="margin-top:7px;color:#303133;white-space:pre-wrap;word-break:break-word;">{{ card.summary }}</div>
+                                <el-table v-if="card.rows && card.rows.length && !card.collapsed" :data="card.rows" size="small" border style="margin-top:8px;">
+                                    <el-table-column prop="item" label="项目" min-width="130"></el-table-column>
+                                    <el-table-column prop="value" label="内容" min-width="280"></el-table-column>
+                                </el-table>
+                                <div v-if="card.collapsed" style="margin-top:7px;color:#67c23a;">{{ card.collapsed_summary }}</div>
+                                <template v-if="card.kind === 'runtime' && !card.collapsed">
+                                    <div v-for="input in card.inputs" :key="input.key" style="display:grid;grid-template-columns:145px 1fr;gap:8px;align-items:center;margin-top:8px;">
+                                        <span>{{ input.key }}</span><el-input v-model="input.value" size="small" :placeholder="`当前 job 的 input/ 或 workspace/ 中的文件，例如 ${input.key}`"></el-input>
+                                    </div>
+                                    <div v-for="parameter in card.parameters" :key="parameter.key" style="display:grid;grid-template-columns:145px 1fr;gap:8px;align-items:center;margin-top:8px;">
+                                        <span>{{ parameter.label }}</span><el-input v-model="parameter.value" size="small"></el-input>
+                                    </div>
+                                    <div style="display:grid;grid-template-columns:145px 1fr;gap:8px;align-items:center;margin-top:8px;">
+                                        <span>输出前缀</span><el-input v-model="card.explicit_prefix" size="small" placeholder="留空则使用 output"></el-input>
+                                    </div>
+                                </template>
+                                <div v-if="card.error" style="margin-top:8px;color:#f56c6c;white-space:pre-wrap;word-break:break-word;">{{ card.error }}</div>
+                                <div v-if="!card.collapsed" style="display:flex;gap:6px;flex-wrap:wrap;margin-top:9px;">
+                                    <el-button v-if="card.actions && card.actions.confirm" type="primary" size="small" :loading="card.loading" :disabled="card.loading" @click="confirmLightweightCandidate(card)">Yes，确认无误</el-button>
+                                    <el-button v-if="card.actions && card.actions.cancel" size="small" :disabled="card.loading" @click="cancelLightweightCard(card)">取消</el-button>
+                                    <el-button v-if="card.actions && card.actions.revise" size="small" :disabled="card.loading || lightweightExtensionConversation.pendingRevisionCardId === card.card_id" @click="beginLightweightRevision(card)">提出修订意见</el-button>
+                                    <el-button v-if="card.actions && card.actions.retry_semantic" type="primary" size="small" :loading="card.loading" :disabled="card.loading" @click="retryLightweightSemantic(card)">重新生成说明</el-button>
+                                    <el-button v-if="card.actions && card.actions.validate" type="primary" size="small" :loading="card.loading" :disabled="card.loading" @click="validateLightweightExtension(card)">开始验证</el-button>
+                                    <el-button v-if="card.actions && card.actions.review" type="primary" size="small" :loading="card.loading" :disabled="card.loading" @click="reviewLightweightResult(card)">结果无误，继续</el-button>
+                                    <el-button v-if="card.actions && card.actions.publish" type="success" size="small" :loading="card.loading" :disabled="card.loading" @click="publishLightweightExtension(card)">授权发布</el-button>
+                                    <el-button v-if="card.actions && card.actions.run" type="primary" size="small" :loading="card.loading" :disabled="card.loading" @click="runLightweightExtension(card)">确认执行</el-button>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+
                     <!-- 非RAG加载指示器 -->
-                    <div v-else-if="nlLoading" style="display: flex; align-items: center; justify-content: center; padding: 20px;">
+                    <div v-if="nlLoading && !ragProgress.active" style="display: flex; align-items: center; justify-content: center; padding: 20px;">
                         <el-icon class="is-loading" style="font-size: 24px; color: #409EFF;"><loading /></el-icon>
                         <span style="margin-left: 10px; color: #606266;">{{ nlStatusText || '正在处理请求...' }}</span>
                     </div>
@@ -2230,7 +2284,7 @@
                     </div>
                     <el-input
                         v-model="nlInput"
-                        :placeholder="preferenceMode ? 'Ask a question about methods or biology...' : 'Describe what you want to run (default prefix At).'"
+                        :placeholder="lightweightExtensionConversation.pendingRevisionCardId ? '请在这里说明需要修订的内容，然后发送。' : (preferenceMode ? 'Ask a question about methods or biology...' : 'Describe what you want to run (default prefix At).')"
                         @keyup.enter="handleNlInput"
                         :disabled="executing || isExecuting"
                         type="textarea"
@@ -2250,15 +2304,15 @@
                     <el-tab-pane label="📊 Analysis Results" name="results" class="results-tab-pane">
 
                 <!-- Running Async Task -->
-                <div v-if="(currentTask && currentTask.stage) || isBatchExecuting || isExecuting" style="margin-bottom: 8px; padding: 8px; background: #e6f7ff; border: 1px solid #91d5ff; border-radius: 0px;">
+                <div v-if="showExecutionIndicator" style="margin-bottom: 8px; padding: 8px; background: #e6f7ff; border: 1px solid #91d5ff; border-radius: 0px;">
                     <div style="display: flex; align-items: center; gap: 8px;">
                         <div style="font-size: 16px; color: #1890ff; animation: rotating 2s linear infinite;">⏳</div>
                         <div style="flex: 1;">
                             <div style="font-weight: 500; color: #096dd9; font-size: 12px;">
-                                {{ (currentTask && currentTask.stage ? currentTask.stage : (currentBatchStage || confirmParams.stage || 'analysis')).toUpperCase() }} Executing
+                                {{ executionIndicatorStage.toUpperCase() }} Executing
                             </div>
                             <div style="font-size: 11px; color: #666;">
-                                ⏱️ {{ executeElapsed }}s | {{ isBatchExecuting ? 'Batch / methodology queue' : 'Refresh every 5s' }}
+                                ⏱️ {{ executionIndicatorElapsed }}s | {{ executionIndicatorStatusText }}
                             </div>
                         </div>
                         <div style="display: flex; gap: 6px;">
@@ -2284,9 +2338,20 @@
 
                 <!-- Result Files Section -->
                 <div class="result-file-section" style="flex: 1; overflow-y: auto; min-height: 0;">
-                    <el-collapse v-model="activeStages" accordion style="font-size: 12px;">
+                    <el-collapse v-model="activeResultGroups" accordion style="font-size: 12px;">
+                        <el-collapse-item
+                            v-for="group in resultGroups"
+                            :key="group.name"
+                            :name="group.name">
+                            <template #title>
+                                <div style="display:flex;align-items:center;justify-content:space-between;width:100%;padding-right:10px;">
+                                    <span style="font-weight:600;">{{ group.label }}</span>
+                                    <span style="color:#999;font-size:12px;">{{ group.fileCount }} files</span>
+                                </div>
+                            </template>
+                            <el-collapse v-model="activeStages" accordion style="font-size: 12px; padding-left: 8px;">
                         <!-- MCScanX HTML结果（独立项，可展开） -->
-                        <el-collapse-item name="mcscanx_html" v-if="mcscanxHtmlFiles && mcscanxHtmlFiles.length > 0">
+                        <el-collapse-item name="mcscanx_html" v-if="group.name === 'gene_family' && mcscanxHtmlFiles && mcscanxHtmlFiles.length > 0">
                             <template #title>
                                 <div style="display:flex;align-items:center;justify-content:space-between;width:100%;padding-right:10px;">
                                     <span>
@@ -2309,7 +2374,7 @@
                         </el-collapse-item>
 
                         <el-collapse-item
-                            v-for="stage in visibleStages"
+                            v-for="stage in group.stages"
                             :key="stage.name"
                             :name="stage.name"
                             :title="stage.label + ' (' + (stage.files ? stage.files.length : 0) + ')'">
@@ -2509,6 +2574,11 @@
                             </div>
                             <div v-else style="color:#999;font-size:12px;padding:8px;">No files</div>
                         </el-collapse-item>
+                            <div v-if="group.stages.length === 0 && !(group.name === 'gene_family' && mcscanxHtmlFiles && mcscanxHtmlFiles.length)" style="color:#999;font-size:12px;padding:8px;">
+                                暂无结果
+                            </div>
+                            </el-collapse>
+                        </el-collapse-item>
                     </el-collapse>
                 </div>
 
@@ -7493,6 +7563,15 @@ RNA-seq KEGG/fgsea 会优先使用物种级 KEGG gene set；没有物种级缓
                             const latestConversation = conversations.value[0];
                             currentConversationId.value = latestConversation.conversation_id;
                             currentConversation.value = latestConversation;
+                            if (latestConversation.job_id) {
+                                jobInfo.job_id = latestConversation.job_id;
+                                jobInfo.input_dir = latestConversation.input_dir || '';
+                                jobInfo.output_dir = latestConversation.output_dir || '';
+                                jobInfo.working_dir = latestConversation.working_dir || '';
+                                activeRnaseqScopeId.value = '';
+                                window.parentJobInfo = { ...jobInfo };
+                                await refreshResults(latestConversation.job_id);
+                            }
                             try {
                                 const msgResponse = await fetch(`/api/conversations/${latestConversation.conversation_id}/messages?limit=500`);
                                 if (msgResponse.ok) {
@@ -8531,6 +8610,7 @@ RNA-seq KEGG/fgsea 会优先使用物种级 KEGG gene set；没有物种级缓
                     workers: [],
                     queues: [],
                     active_tasks: [],
+                    resource_tasks: [],
                     summary: {
                         worker_count: 0,
                         queue_count: 0,
@@ -8632,6 +8712,7 @@ RNA-seq KEGG/fgsea 会优先使用物种级 KEGG gene set；没有物种级缓
                     { stage: 'rnaseq_candidate_family', label: 'candidate', group: 'rnaseq', default_cpu: 4, max_cpu: 4 }
                 ]);
                 let runtimeMonitorTimer = null;
+                let resourceMonitorTimer = null;
                 const runtimeWorkerCount = computed(() => Number((runtimeOverview.summary && runtimeOverview.summary.worker_count) || 0));
                 const runtimeActiveTaskCount = computed(() => Number((runtimeOverview.summary && runtimeOverview.summary.active_task_count) || 0));
                 const geneFamilyStageCpuRows = computed(() => stageCpuRows.filter((row) => row.group === 'gene_family'));
@@ -9027,6 +9108,7 @@ RNA-seq KEGG/fgsea 会优先使用物种级 KEGG gene set；没有物种级缓
                     description: '',
                     codeFiles: [],
                     dataFiles: [],
+                    dataPaths: '',
                     extensionId: '',
                     loading: false,
                     trialing: false,
@@ -9042,6 +9124,16 @@ RNA-seq KEGG/fgsea 会优先使用物种级 KEGG gene set；没有物种级缓
                     statusDialogVisible: false,
                     statusEvents: []
                 });
+                const lightweightExtensions = ref([]);
+                const lightweightExtensionConversation = reactive({
+                    cards: [],
+                    activeOperationToken: '',
+                    activeExtensionId: '',
+                    pendingRevisionCardId: ''
+                });
+                const lightweightOperationPromises = new Map();
+                const lightweightConversationCardKeys = new Set();
+                const lightweightOperationStorageKey = 'bbav5_lightweight_extension_operation';
                 const extensionStages = ref([]);
                 const extensionIsPublishedSuccessful = (item) => {
                     if (!item) return false;
@@ -9049,7 +9141,15 @@ RNA-seq KEGG/fgsea 会优先使用物种级 KEGG gene set；没有物种级缓
                     const templateGate = String(item.template_gate_status || '').trim();
                     return String(item.golden_status || '') === 'passed' && ['passed', 'legacy_unchecked'].includes(templateGate);
                 };
-                const extensionCompletedStages = computed(() => (extensionStages.value || []).filter(extensionIsPublishedSuccessful));
+                const extensionCompletedStages = computed(() => [
+                    ...(extensionStages.value || []).filter(extensionIsPublishedSuccessful),
+                    ...(lightweightExtensions.value || [])
+                        .filter(item => String(item.status || '') === 'published')
+                        .map(item => ({ ...item, lightweight: true, display_name: item.extension_id }))
+                ]);
+                const isLightweightExtensionSelected = computed(() => (lightweightExtensions.value || []).some(item => (
+                    item.extension_id === extensionBuild.extensionId && String(item.status || '') === 'published'
+                )));
                 const extensionStageOptionLabel = (item) => {
                     if (!item) return '';
                     const name = item.display_name || item.name || item.extension_id || '拓展阶段';
@@ -9058,6 +9158,12 @@ RNA-seq KEGG/fgsea 会优先使用物种级 KEGG gene set；没有物种级缓
                 };
                 const selectExistingExtensionStage = (extensionId) => {
                     const item = (extensionStages.value || []).find(stage => stage.extension_id === extensionId);
+                    const lightweight = (lightweightExtensions.value || []).find(stage => stage.extension_id === extensionId);
+                    if (lightweight) {
+                        extensionBuild.extensionId = lightweight.extension_id || '';
+                        extensionBuild.displayName = lightweight.extension_id || extensionBuild.displayName || '';
+                        return;
+                    }
                     if (!item) {
                         if (!extensionId) {
                             extensionBuild.extensionId = '';
@@ -9967,6 +10073,18 @@ compare: [[flesh, peel]]`;
                     { name: 'pop_structure', label: 'Population Structure', status: 'pending', images: [], files: [], elapsed_time: 0 },
                     { name: 'pop_ld_decay', label: 'Population LD Decay', status: 'pending', images: [], files: [], elapsed_time: 0 },
                     { name: 'pop_snp_density', label: 'SNP Density', status: 'pending', images: [], files: [], elapsed_time: 0 },
+                    { name: 'wgs_qc', label: 'WGS QC', status: 'pending', images: [], files: [], elapsed_time: 0 },
+                    { name: 'wgs_index', label: 'WGS Reference Index', status: 'pending', images: [], files: [], elapsed_time: 0 },
+                    { name: 'wgs_align', label: 'WGS Alignment', status: 'pending', images: [], files: [], elapsed_time: 0 },
+                    { name: 'wgs_markdup', label: 'WGS Mark Duplicates', status: 'pending', images: [], files: [], elapsed_time: 0 },
+                    { name: 'wgs_bam_qc', label: 'WGS BAM QC', status: 'pending', images: [], files: [], elapsed_time: 0 },
+                    { name: 'wgs_haplotype_calling', label: 'WGS Haplotype Calling', status: 'pending', images: [], files: [], elapsed_time: 0 },
+                    { name: 'wgs_gvcf_combine', label: 'WGS GVCF Combine', status: 'pending', images: [], files: [], elapsed_time: 0 },
+                    { name: 'wgs_joint_genotyping', label: 'WGS Joint Genotyping', status: 'pending', images: [], files: [], elapsed_time: 0 },
+                    { name: 'wgs_variant_select', label: 'WGS Variant Select', status: 'pending', images: [], files: [], elapsed_time: 0 },
+                    { name: 'wgs_variant_filter', label: 'WGS Variant Filter', status: 'pending', images: [], files: [], elapsed_time: 0 },
+                    { name: 'wgs_impute', label: 'WGS Imputation', status: 'pending', images: [], files: [], elapsed_time: 0 },
+                    { name: 'wgs_maf_missing_filter', label: 'WGS MAF / Missing Filter', status: 'pending', images: [], files: [], elapsed_time: 0 },
                     { name: 'genome_prepare', label: '0️⃣ Genome Prepare', status: 'pending', images: [], files: [], elapsed_time: 0 },
                     { name: 'identify', label: '1️⃣ Identify', status: 'pending', images: [], files: [], elapsed_time: 0 },
                     { name: 'identify_refine', label: '1.1 Identify Refine', status: 'pending', images: [], files: [], elapsed_time: 0 },
@@ -10005,7 +10123,32 @@ compare: [[flesh, peel]]`;
                 ]);
                 // 新版结果区域 - 展开的阶段
                 const activeStages = ref('phylogeny');
+                const activeResultGroups = ref('gene_family');
                 const resultStageFilter = ref('');
+                const rnaseqResultStageNames = new Set([
+                    'rnaseq_qc', 'rnaseq_align', 'rnaseq_quant', 'rnaseq_sample_qc',
+                    'rnaseq_de', 'annotation', 'rnaseq_go_enrich', 'rnaseq_kegg_enrich',
+                    'rnaseq_fgsea', 'rnaseq_wgcna', 'rnaseq_candidate_family'
+                ]);
+                const wgsPopulationGwasStageNames = new Set([
+                    'wgs_qc', 'wgs_index', 'wgs_align', 'wgs_markdup', 'wgs_bam_qc',
+                    'wgs_haplotype_calling', 'wgs_gvcf_combine', 'wgs_joint_genotyping',
+                    'wgs_variant_select', 'wgs_variant_filter', 'wgs_impute', 'wgs_maf_missing_filter',
+                    'pop_pca', 'pop_phylogeny', 'pop_structure', 'pop_ld_decay', 'pop_snp_density',
+                    'gwas_fmt', 'gwas_kinship', 'gwas_trait', 'gwas_cov', 'gwas_mlm',
+                    'gwas_plot', 'gwas_emmax', 'gwas_emplot', 'gwas_glm'
+                ]);
+                const resultGroupNameForStage = (stageName = '') => {
+                    if (rnaseqResultStageNames.has(stageName)) return 'rnaseq';
+                    if (wgsPopulationGwasStageNames.has(stageName)) return 'wgs_population_gwas';
+                    return 'gene_family';
+                };
+                const wgsPopulationGwasResultRank = (stageName = '') => {
+                    if (stageName.startsWith('wgs_')) return 0;
+                    if (stageName.startsWith('pop_')) return 1;
+                    if (stageName.startsWith('gwas_')) return 2;
+                    return 3;
+                };
                 const resultStageAliases = {
                     phylogeny: ['phylogeny', 'phylogeny_msa', 'msa_region_plot'],
                     reference_classification: ['reference_classification'],
@@ -10024,12 +10167,12 @@ compare: [[flesh, peel]]`;
                     if (!filter) return null;
                     return new Set(resultStageAliases[filter] || [filter]);
                 });
-                const visibleStages = computed(() => stages);
                 const setResultStageFilter = (stageName = '') => {
                     const stage = stageName || '';
                     resultStageFilter.value = stage;
                     if (stage) {
                         activeStages.value = stage === 'subfamily_confirm' ? 'reference_classification' : stage;
+                        activeResultGroups.value = resultGroupNameForStage(activeStages.value);
                         rightPanelTab.value = 'results';
                     }
                 };
@@ -10631,6 +10774,26 @@ compare: [[flesh, peel]]`;
                     return images + resultDisplayFiles(stage).length + msaFiles + stageMsaGroupCount(stage) + stageReplotGroupCount(stage) + resetCount;
                 };
 
+                const resultGroups = computed(() => {
+                    const definitions = [
+                        { name: 'rnaseq', label: 'RNA-seq' },
+                        { name: 'gene_family', label: '基因家族' },
+                        { name: 'wgs_population_gwas', label: 'WGS2GWAS（遗传变异与群体分析）' }
+                    ];
+                    return definitions.map(group => {
+                        const groupStages = stages.filter(stage => resultGroupNameForStage(stage.name) === group.name);
+                        if (group.name === 'wgs_population_gwas') {
+                            groupStages.sort((a, b) => wgsPopulationGwasResultRank(a.name) - wgsPopulationGwasResultRank(b.name));
+                        }
+                        return {
+                            ...group,
+                            stages: groupStages,
+                            fileCount: groupStages.reduce((total, stage) => total + resultVisibleCount(stage), 0)
+                                + (group.name === 'gene_family' ? (mcscanxHtmlFiles.value || []).length : 0)
+                        };
+                    });
+                });
+
                 const treeReplotGroupTitle = (stage) => {
                     const count = Array.isArray(stage?.replot_groups?.tree) ? stage.replot_groups.tree.length : 0;
                     const sectionNo = {
@@ -11328,7 +11491,7 @@ compare: [[flesh, peel]]`;
                             // 更新当前会话的 job_id
                             if (currentConversationId.value) {
                                 try {
-                                    await fetch('/api/conversations/link-to-job', {
+                                    const linkResponse = await fetch('/api/conversations/link-to-job', {
                                         method: 'POST',
                                         headers: { 'Content-Type': 'application/json' },
                                         body: JSON.stringify({
@@ -11336,6 +11499,11 @@ compare: [[flesh, peel]]`;
                                             job_id: data.job_id
                                         })
                                     });
+                                    const linkData = await linkResponse.json();
+                                    if (linkData.conversation_id) {
+                                        currentConversationId.value = linkData.conversation_id;
+                                        currentConversation.value = null;
+                                    }
                                     console.log('[会话] 已绑定 job:', data.job_id);
                                     await loadConversations();  // 刷新列表
                                 } catch (e) {
@@ -11390,7 +11558,7 @@ compare: [[flesh, peel]]`;
                             // 更新当前会话的 job_id
                             if (currentConversationId.value) {
                                 try {
-                                    await fetch('/api/conversations/link-to-job', {
+                                    const linkResponse = await fetch('/api/conversations/link-to-job', {
                                         method: 'POST',
                                         headers: { 'Content-Type': 'application/json' },
                                         body: JSON.stringify({
@@ -11398,6 +11566,13 @@ compare: [[flesh, peel]]`;
                                             job_id: data.job_id
                                         })
                                     });
+                                    const linkData = await linkResponse.json();
+                                    if (linkData.conversation_id && linkData.conversation_id !== currentConversationId.value) {
+                                        currentConversationId.value = linkData.conversation_id;
+                                        currentConversation.value = null;
+                                        messages.value = [];
+                                        agentSession.messages = messages.value;
+                                    }
                                     console.log('[会话] 已绑定 job:', data.job_id);
                                     await loadConversations();
                                 } catch (e) {
@@ -17771,6 +17946,54 @@ compare: [[flesh, peel]]`;
                 const currentTaskId = ref(null);
                 /** In-flight /api/execute task_ids (batch may run several in parallel) */
                 const activePipelineTaskIds = ref([]);
+                const ACTIVE_RUNTIME_TASK_STATUSES = new Set([
+                    'queued', 'pending', 'running', 'started', 'waiting_resource', 'retry'
+                ]);
+                const currentJobRuntimeTasks = computed(() => {
+                    const currentJobId = String(jobInfo.job_id || '');
+                    if (!currentJobId || currentJobId === 'default_job') return [];
+                    return (runtimeOverview.resource_tasks || [])
+                        .filter(task => (
+                            String(task.job_id || '') === currentJobId &&
+                            ACTIVE_RUNTIME_TASK_STATUSES.has(String(task.status || '').toLowerCase())
+                        ))
+                        .sort((a, b) => String(b.updated_at || '').localeCompare(String(a.updated_at || '')));
+                });
+                const recoveredRuntimeTask = computed(() => currentJobRuntimeTasks.value[0] || null);
+                const executionIndicatorTask = computed(() => {
+                    const localTask = currentTask.value;
+                    const currentJobId = String(jobInfo.job_id || '');
+                    if (
+                        localTask?.stage &&
+                        (!localTask.job_id || String(localTask.job_id) === currentJobId)
+                    ) {
+                        return localTask;
+                    }
+                    const backendTask = recoveredRuntimeTask.value;
+                    if (!backendTask) return null;
+                    return {
+                        id: backendTask.task_id || backendTask.id || '',
+                        stage: backendTask.stage || 'analysis',
+                        job_id: backendTask.job_id || '',
+                        started_at: backendTask.started_at || backendTask.updated_at || ''
+                    };
+                });
+                const showExecutionIndicator = computed(() => (
+                    !!executionIndicatorTask.value || isBatchExecuting.value || isExecuting.value
+                ));
+                const executionIndicatorStage = computed(() => (
+                    executionIndicatorTask.value?.stage || currentBatchStage.value || confirmParams.stage || 'analysis'
+                ));
+                const executionIndicatorElapsed = computed(() => {
+                    if (isBatchExecuting.value || isExecuting.value) return executeElapsed.value;
+                    const startedAt = Date.parse(executionIndicatorTask.value?.started_at || '');
+                    if (!Number.isFinite(startedAt)) return executeElapsed.value;
+                    return Math.max(0, (Date.now() - startedAt) / 1000).toFixed(1);
+                });
+                const executionIndicatorStatusText = computed(() => (
+                    isBatchExecuting.value ? 'Batch / methodology queue' :
+                        (recoveredRuntimeTask.value ? 'Backend task · refresh every 5s' : 'Refresh every 5s')
+                ));
                 const domainReviewDialogVisible = ref(false);
                 const domainReviewLoading = ref(false);
                 const domainReviewApplying = ref(false);
@@ -18140,7 +18363,8 @@ compare: [[flesh, peel]]`;
                     rememberGwasGlmIdentity(stageName, result);
                     handoffGwasGlmProducerIdentity(stageName, result);
                     setResultStageFilter(stageName);
-                    await refreshResults(null, stageName);
+                    const completedJobId = typeof jobInfo !== 'undefined' ? jobInfo.job_id : null;
+                    await refreshResults(completedJobId, stageName);
                     if (stageName === 'identify') {
                         let confirmed = false;
                         if (subfamilyPerSpeciesMode(stageParams)) {
@@ -18558,10 +18782,25 @@ compare: [[flesh, peel]]`;
 
                 // Stop：先 revoke Celery（所有在跑的 pipeline task_id），再停批量队列（与 PlantAI 一致：仅右侧 Stop）
                 const stopExecution = async () => {
+                    if (currentTask.value?.type === 'lightweight_extension') {
+                        isStopping.value = true;
+                        try {
+                            await stopLightweightOperation();
+                            ElMessage.success('已请求停止当前拓展分析；状态仍会继续轮询直到进程退出。');
+                        } catch (err) {
+                            ElMessage.error(`停止拓展分析失败：${err.message || err}`);
+                        } finally {
+                            isStopping.value = false;
+                        }
+                        return;
+                    }
                     const idSet = new Set();
                     if (currentTask.value?.id) idSet.add(currentTask.value.id);
                     if (currentTaskId.value) idSet.add(currentTaskId.value);
                     (activePipelineTaskIds.value || []).forEach((id) => id && idSet.add(id));
+                    currentJobRuntimeTasks.value.forEach((task) => {
+                        if (task.task_id) idSet.add(task.task_id);
+                    });
 
                     let stoppedBatch = false;
                     if (isBatchExecuting.value) {
@@ -18885,7 +19124,8 @@ compare: [[flesh, peel]]`;
                             // 异步任务 - 启动轮询
                             currentTask.value = {
                                 id: data.task_id,
-                                stage: confirmParams.stage
+                                stage: confirmParams.stage,
+                                job_id: jobInfo.job_id
                             };
                             currentTaskId.value = data.task_id;
 
@@ -19023,11 +19263,15 @@ compare: [[flesh, peel]]`;
                     return merged;
                 };
                 const onExtensionCodeFilesChange = (event) => {
-                    extensionBuild.codeFiles = appendExtensionFiles(extensionBuild.codeFiles, event.target.files);
+                    const selected = Array.from(event.target.files || []);
+                    extensionBuild.codeFiles = appendExtensionFiles(extensionBuild.codeFiles, selected);
+                    if (selected.length) ElMessage.success(`已选择 ${selected.length} 个原始代码文件`);
                     event.target.value = '';
                 };
                 const onExtensionDataFilesChange = (event) => {
-                    extensionBuild.dataFiles = appendExtensionFiles(extensionBuild.dataFiles, event.target.files);
+                    const selected = Array.from(event.target.files || []);
+                    extensionBuild.dataFiles = appendExtensionFiles(extensionBuild.dataFiles, selected);
+                    if (selected.length) ElMessage.success(`已选择 ${selected.length} 个测试数据文件`);
                     event.target.value = '';
                 };
                 const removeExtensionFile = (kind, file) => {
@@ -19043,7 +19287,15 @@ compare: [[flesh, peel]]`;
                     try {
                         const data = await response.json();
                         const detail = data.detail || data.message || data.error;
-                        return detail ? `${fallback || '请求失败'}：${detail}` : `${fallback || '请求失败'}${statusText ? `（HTTP ${statusText}）` : ''}`;
+                        let message = '';
+                        if (typeof detail === 'string') {
+                            message = detail;
+                        } else if (Array.isArray(detail)) {
+                            message = detail.map(item => item?.msg || item?.message || JSON.stringify(item)).join('；');
+                        } else if (detail && typeof detail === 'object') {
+                            message = detail.message || JSON.stringify(detail);
+                        }
+                        return message ? `${fallback || '请求失败'}：${message}` : `${fallback || '请求失败'}${statusText ? `（HTTP ${statusText}）` : ''}`;
                     } catch (_) {
                         try {
                             const text = await response.text();
@@ -19082,7 +19334,604 @@ compare: [[flesh, peel]]`;
 
 命令：${command}` : error;
                 };
-                const buildExtensionStage = async () => {
+                const extensionConfirmedParameterPayload = () => {
+                    const payload = {};
+                    Object.entries(extensionBuild.confirmParameters || {}).forEach(([name, spec]) => {
+                        if (spec && typeof spec === 'object' && !Array.isArray(spec)) {
+                            payload[name] = spec.current_value ?? spec.value ?? spec.default ?? '';
+                        } else {
+                            payload[name] = spec ?? '';
+                        }
+                    });
+                    return payload;
+                };
+                const defaultExtensionPrePublishMessage = () => {
+                    const name = String(extensionBuild.displayName || extensionBuild.extensionId || '').trim();
+                    return name ? `执行拓展分析 ${name}` : '执行拓展分析';
+                };
+                const resetExtensionPrePublishState = () => {
+                    extensionBuild.prePublishNlGate = null;
+                    extensionBuild.prePublishUiGate = null;
+                    extensionBuild.prePublishReady = false;
+                    extensionBuild.prePublishError = '';
+                    extensionBuild.postPublishUiGate = null;
+                    extensionBuild.postPublishReady = false;
+                    extensionBuild.postPublishError = '';
+                    extensionBuild.prePublishMessage = defaultExtensionPrePublishMessage();
+                };
+                const ensureExtensionPrePublishMessage = () => {
+                    if (!String(extensionBuild.prePublishMessage || '').trim()) {
+                        extensionBuild.prePublishMessage = defaultExtensionPrePublishMessage();
+                    }
+                    return String(extensionBuild.prePublishMessage || '').trim();
+                };
+                const runExtensionPrePublishGates = async () => {
+                    if (!extensionBuild.extensionId) {
+                        ElMessage.warning('请先生成拓展分析阶段。');
+                        return;
+                    }
+                    if (!jobInfo.job_id) {
+                        extensionBuild.prePublishError = '当前 job_id 为空，不能运行发布前验收。';
+                        ElMessage.warning(extensionBuild.prePublishError);
+                        return;
+                    }
+                    extensionBuild.prePublishRunning = true;
+                    extensionBuild.prePublishReady = false;
+                    extensionBuild.prePublishError = '';
+                    extensionBuild.prePublishNlGate = null;
+                    extensionBuild.prePublishUiGate = null;
+                    const message = ensureExtensionPrePublishMessage();
+                    const parameters = extensionConfirmedParameterPayload();
+                    try {
+                        pushExtensionStatus('开始发布前 NL Runtime Gate...', 'gate', true);
+                        const nlResponse = await extensionApiFetch(`/api/extension-stages/${encodeURIComponent(extensionBuild.extensionId)}/nl-runtime-gate-repair`, {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify({
+                                message,
+                                job_id: jobInfo.job_id,
+                                input_paths: [],
+                                parameters,
+                                execute: true,
+                                max_attempts: 20,
+                                auto_publish: false
+                            })
+                        });
+                        if (!nlResponse.ok) throw new Error(await extensionApiError(nlResponse, 'NL Runtime Gate 失败'));
+                        const nlData = await nlResponse.json();
+                        const nlGate = nlData.nl_runtime_gate || (nlData.extension && nlData.extension.nl_runtime_gate) || {};
+                        extensionBuild.prePublishNlGate = nlGate;
+                        if (String(nlGate.status || '') !== 'passed') {
+                            throw new Error(`NL Runtime Gate 未通过：${nlData.last_error || nlGate.failure_type || nlGate.status || 'unknown'}`);
+                        }
+                        pushExtensionStatus('NL Runtime Gate 已通过，开始 UI Display Gate...', 'gate', true);
+                        const uiResponse = await extensionApiFetch(`/api/extension-stages/${encodeURIComponent(extensionBuild.extensionId)}/frontend-e2e-gate`, {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify({
+                                message,
+                                job_id: jobInfo.job_id,
+                                input_paths: [],
+                                parameters,
+                                execute: true,
+                                timeout_sec: 600,
+                                gate_phase: 'pre_publish'
+                            })
+                        });
+                        if (!uiResponse.ok) throw new Error(await extensionApiError(uiResponse, 'UI Display Gate 失败'));
+                        const uiData = await uiResponse.json();
+                        const uiGate = uiData.ui_display_gate || {};
+                        extensionBuild.prePublishUiGate = uiGate;
+                        if (String(uiGate.status || '') !== 'passed' || String(uiGate.mode || '') !== 'playwright') {
+                            throw new Error(`UI Display Gate 未通过：${uiGate.failure_type || uiGate.status || 'unknown'}；mode=${uiGate.mode || '-'}`);
+                        }
+                        extensionBuild.prePublishReady = true;
+                        await loadExtensionStages(true);
+                        pushExtensionStatus('发布前验收已全部通过，可以发布。', 'gate', true);
+                        ElMessage.success('发布前验收已通过');
+                    } catch (err) {
+                        extensionBuild.prePublishReady = false;
+                        extensionBuild.prePublishError = err.message || '发布前验收失败';
+                        pushExtensionStatus(extensionBuild.prePublishError, 'error', true);
+                        ElMessage.error(extensionBuild.prePublishError.split('\n')[0]);
+                    } finally {
+                        extensionBuild.prePublishRunning = false;
+                    }
+                };
+                const openExtensionPrePublishDialog = () => {
+                    resetExtensionPrePublishState();
+                    extensionBuild.prePublishDialogVisible = true;
+                };
+                const lightweightOperationToken = (action) => `${action}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+                const lightweightCardKey = (card) => `${card.card_id}:${card.status}`;
+                const addLightweightCard = (card) => {
+                    const key = lightweightCardKey(card);
+                    if (lightweightConversationCardKeys.has(key)) return null;
+                    lightweightConversationCardKeys.add(key);
+                    const next = reactive({
+                        type: 'info',
+                        rows: [],
+                        actions: {},
+                        logs: [],
+                        loading: false,
+                        collapsed: false,
+                        ...card
+                    });
+                    lightweightExtensionConversation.cards.push(next);
+                    return next;
+                };
+                const finishLightweightCard = (card, summary) => {
+                    card.loading = false;
+                    card.collapsed = true;
+                    card.collapsed_summary = summary;
+                    card.actions = {};
+                };
+                const lightweightErrorText = (view, fallback) => {
+                    const error = view && view.error || {};
+                    const phase = error.phase || view?.action || 'operation';
+                    const message = error.message || fallback || '操作失败';
+                    return `阶段：${phase}\n原因：${message}`;
+                };
+                const lightweightHelp = async (extensionId) => {
+                    const response = await extensionApiFetch(`/api/lightweight-extension-stages/${encodeURIComponent(extensionId)}/help`);
+                    if (!response.ok) throw new Error(await extensionApiError(response, '读取拓展分析说明失败'));
+                    return await response.json();
+                };
+                const isLightweightExtensionId = (extensionId) => (lightweightExtensions.value || []).some(item => item.extension_id === extensionId);
+                const lightweightRunById = (runs, runId) => (runs || []).find(item => item && item.run_id === runId) || {};
+                const lightweightResumeNext = (action) => ({
+                    upload: 'candidate', retry_semantic: 'candidate', confirm: 'validate', revise: 'candidate', validate: 'review',
+                    review: 'publish', publish: 'list', run: 'runtime_result'
+                })[action] || '';
+                const lightweightCandidateConfirmationSummary = (card) => card.revision_summary
+                    ? `✓ 已确认候选｜已修订：${card.revision_summary}`
+                    : '✓ 已确认候选｜未作修订';
+                const lightweightParameterText = (item) => {
+                    const label = item.flag || item.fact_id || '';
+                    const value = item.value ?? item.default_value ?? item.default ?? '';
+                    return value === '' ? label : `${label} = ${value}`;
+                };
+                const lightweightResultRows = (run) => {
+                    const projection = run.projection || {};
+                    const stdout = projection.stdout || {};
+                    return [
+                        { item: '实际命令', value: run.command || run.execution_command || '见执行日志' },
+                        { item: '输出文件', value: (projection.files || []).map(item => item.path).join('；') || '（无文件输出）' },
+                        { item: '标准输出', value: stdout.present ? (stdout.text || '') : '（无）' },
+                        { item: '日志', value: Object.values(run.logs || {}).join('；') || '（无）' }
+                    ];
+                };
+                const lightweightRows = (help) => {
+                    const inputs = (help.inputs || []).filter(item => item && item.replaceable).map(item => item.path).filter(Boolean);
+                    const parameters = (help.parameters || []).map(lightweightParameterText).filter(Boolean);
+                    const outputFiles = ((help.outputs || {}).files || []).map(item => item.path).filter(Boolean);
+                    return [
+                        { item: '功能', value: help.function_summary || '-' },
+                        { item: '原始命令', value: help.original_command || '-' },
+                        { item: '输入文件', value: inputs.join('；') || '（无）' },
+                        { item: '可改参数', value: parameters.join('；') || '（无）' },
+                        { item: '输出', value: outputFiles.join('；') || (((help.outputs || {}).stdout || {}).present ? '标准输出（直接展示）' : '（无）') }
+                    ];
+                };
+                const setLightweightRunning = (extensionId, operationToken) => {
+                    lightweightExtensionConversation.activeExtensionId = extensionId;
+                    lightweightExtensionConversation.activeOperationToken = operationToken;
+                    currentTask.value = { id: operationToken, stage: 'extension_stage', type: 'lightweight_extension', job_id: jobInfo.job_id };
+                    currentTaskId.value = operationToken;
+                    executing.value = true;
+                    isExecuting.value = true;
+                    executeStartTime = Date.now();
+                    executeElapsed.value = '0.0';
+                    if (!executeTimer) {
+                        executeTimer = setInterval(() => {
+                            if (executeStartTime) executeElapsed.value = ((Date.now() - executeStartTime) / 1000).toFixed(1);
+                        }, 100);
+                    }
+                };
+                const clearLightweightRunning = (operationToken) => {
+                    if (lightweightExtensionConversation.activeOperationToken !== operationToken) return;
+                    lightweightExtensionConversation.activeOperationToken = '';
+                    lightweightExtensionConversation.activeExtensionId = '';
+                    if (executeTimer) {
+                        clearInterval(executeTimer);
+                        executeTimer = null;
+                    }
+                    executing.value = false;
+                    isExecuting.value = false;
+                    currentTask.value = null;
+                    currentTaskId.value = null;
+                };
+                const rememberLightweightOperation = (extensionId, action, operationToken, cardId) => {
+                    try {
+                        sessionStorage.setItem(lightweightOperationStorageKey, JSON.stringify({ extensionId, action, operationToken, cardId }));
+                    } catch (_) {}
+                };
+                const forgetLightweightOperation = (operationToken) => {
+                    try {
+                        const current = JSON.parse(sessionStorage.getItem(lightweightOperationStorageKey) || 'null');
+                        if (current && current.operationToken === operationToken) sessionStorage.removeItem(lightweightOperationStorageKey);
+                    } catch (_) {}
+                };
+                const pollLightweightOperation = (extensionId, operationToken, card, onComplete) => {
+                    if (lightweightOperationPromises.has(operationToken)) return lightweightOperationPromises.get(operationToken);
+                    const promise = new Promise((resolve) => {
+                        const poll = async () => {
+                            try {
+                                const response = await extensionApiFetch(`/api/lightweight-extension-stages/operations/${encodeURIComponent(operationToken)}`);
+                                if (!response.ok) throw new Error(await extensionApiError(response, '读取拓展分析状态失败'));
+                                const view = await response.json();
+                                const terminal = ['completed', 'failed'].includes(String(view.state || ''));
+                                if (!terminal) {
+                                    setLightweightRunning(extensionId, operationToken);
+                                    window.setTimeout(poll, 800);
+                                    return;
+                                }
+                                clearLightweightRunning(operationToken);
+                                lightweightOperationPromises.delete(operationToken);
+                                forgetLightweightOperation(operationToken);
+                                card.loading = false;
+                                if (view.outcome === 'failed' || view.error || view.state === 'failed') {
+                                    card.status = 'failed';
+                                    card.status_label = '失败';
+                                    card.type = 'danger';
+                                    card.error = lightweightErrorText(view);
+                                    card.logs = view.logs || (view.error && view.error.logs) || [];
+                                    if (String(view?.error?.phase || '') === 'semantic_candidate') {
+                                        card.title = '拓展分析说明生成失败';
+                                        card.purpose = '原始命令、测试数据和执行事实已经保留；这里只重新生成说明，不会重新运行原始命令。';
+                                        card.summary = '可以直接重试，或取消后检查错误原因。';
+                                        card.actions = { retry_semantic: true, cancel: true };
+                                    }
+                                    resolve(view);
+                                    return;
+                                }
+                                await onComplete(view);
+                                resolve(view);
+                            } catch (err) {
+                                clearLightweightRunning(operationToken);
+                                lightweightOperationPromises.delete(operationToken);
+                                forgetLightweightOperation(operationToken);
+                                card.loading = false;
+                                card.status = 'failed';
+                                card.status_label = '失败';
+                                card.type = 'danger';
+                                card.error = `阶段：前端轮询\n原因：${err.message || '无法读取操作状态'}`;
+                                resolve({ state: 'failed', error: { phase: 'frontend_poll', message: err.message } });
+                            }
+                        };
+                        poll();
+                    });
+                    lightweightOperationPromises.set(operationToken, promise);
+                    return promise;
+                };
+                const submitLightweightOperation = async (extensionId, action, endpoint, payload, card, onComplete) => {
+                    if (card.loading) return null;
+                    const operationToken = lightweightOperationToken(action);
+                    card.loading = true;
+                    card.status = 'running';
+                    card.status_label = '运行中';
+                    card.type = 'primary';
+                    try {
+                        const response = await extensionApiFetch(endpoint, {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify({ operation_token: operationToken, ...payload })
+                        });
+                        if (!response.ok) throw new Error(await extensionApiError(response, `${action} 提交失败`));
+                        rememberLightweightOperation(extensionId, action, operationToken, card.card_id);
+                        setLightweightRunning(extensionId, operationToken);
+                        return await pollLightweightOperation(extensionId, operationToken, card, onComplete);
+                    } catch (err) {
+                        clearLightweightRunning(operationToken);
+                        card.loading = false;
+                        card.status = 'failed';
+                        card.status_label = '失败';
+                        card.type = 'danger';
+                        card.error = `阶段：${action}\n原因：${err.message || '提交失败'}`;
+                        return null;
+                    }
+                };
+                const showLightweightCandidate = async (extensionId, summary = '执行入口已在隔离环境运行。请核对系统记录的事实与说明；确认后才会验证。', revisionSummary = '') => {
+                    const help = await lightweightHelp(extensionId);
+                    addLightweightCard({
+                        card_id: `${extensionId}:candidate:${Date.now()}`,
+                        status: 'pending',
+                        status_label: '待确认',
+                        title: '拓展分析候选核对',
+                        purpose: '这张卡用于核对系统从真实执行中锁定的命令、输入、参数和输出。',
+                        summary,
+                        rows: lightweightRows(help),
+                        extension_id: extensionId,
+                        revision_summary: revisionSummary,
+                        actions: { confirm: true, cancel: true, revise: true }
+                    });
+                };
+                const buildLightweightExtensionStage = async () => {
+                    const hasCommand = Boolean(String(extensionBuild.command || '').trim());
+                    const hasCode = extensionBuild.codeFiles.length > 0;
+                    const hasDataPaths = Boolean(String(extensionBuild.dataPaths || '').trim());
+                    if (!extensionBuild.displayName || (!extensionBuild.dataFiles.length && !hasDataPaths) || (!hasCommand && !hasCode)) {
+                        ElMessage.warning('请填写名称并提供测试数据文件或服务器路径；原始命令和原始代码至少提供一项。');
+                        return;
+                    }
+                    const extensionId = String(extensionBuild.displayName).trim().toLowerCase()
+                        .replace(/[^a-z0-9_-]+/g, '_').replace(/^_+|_+$/g, '') || `extension_${Date.now()}`;
+                    const token = lightweightOperationToken('upload');
+                    const card = addLightweightCard({
+                        card_id: `${extensionId}:upload`, status: 'running', status_label: '运行中', type: 'primary',
+                        title: '正在生成拓展分析', purpose: '系统正在确定执行入口，并运行上传的代码和测试数据，提取不可修改的执行事实。',
+                        summary: '原始包可复现检查中…', extension_id: extensionId
+                    });
+                    if (!card) return;
+                    extensionBuild.loading = true;
+                    try {
+                        const form = new FormData();
+                        form.append('extension_id', extensionId);
+                        if (hasCommand) form.append('original_command', extensionBuild.command);
+                        form.append('operation_token', token);
+                        extensionBuild.codeFiles.forEach(file => form.append('raw_code_files', file));
+                        extensionBuild.dataFiles.forEach(file => form.append('raw_data_files', file));
+                        if (hasDataPaths) form.append('raw_data_paths', extensionBuild.dataPaths);
+                        const response = await extensionApiFetch('/api/lightweight-extension-stages/upload', { method: 'POST', body: form });
+                        if (!response.ok) throw new Error(await extensionApiError(response, '原始包可复现检查提交失败'));
+                        ElMessage.success('文件上传成功，已开始生成并验收');
+                        rememberLightweightOperation(extensionId, 'upload', token, card.card_id);
+                        setLightweightRunning(extensionId, token);
+                        await pollLightweightOperation(extensionId, token, card, async () => {
+                            finishLightweightCard(card, '✓ 执行入口已成功复现；候选信息已生成。');
+                            extensionBuild.extensionId = extensionId;
+                            await loadLightweightExtensionStages();
+                            await showLightweightCandidate(extensionId);
+                        });
+                    } catch (err) {
+                        clearLightweightRunning(token);
+                        card.status = 'failed';
+                        card.status_label = '失败';
+                        card.type = 'danger';
+                        card.error = `阶段：upload\n原因：${err.message || '原始包可复现检查提交失败'}`;
+                    } finally {
+                        extensionBuild.loading = false;
+                    }
+                };
+                const confirmLightweightCandidate = async (card) => {
+                    await submitLightweightOperation(card.extension_id, 'confirm', `/api/lightweight-extension-stages/${encodeURIComponent(card.extension_id)}/confirm`, {}, card, async () => {
+                        finishLightweightCard(card, lightweightCandidateConfirmationSummary(card));
+                        addLightweightCard({
+                            card_id: `${card.extension_id}:validate`, status: 'pending', status_label: '待执行',
+                            title: '开始验证', purpose: '这张卡用于用同一份测试数据执行已确认的工具，并生成可核对的结果。',
+                            summary: '确认无误后点击“开始验证”。', extension_id: card.extension_id,
+                            actions: { validate: true }
+                        });
+                    });
+                };
+                const cancelLightweightCard = (card) => {
+                    if (lightweightExtensionConversation.pendingRevisionCardId === card.card_id) {
+                        lightweightExtensionConversation.pendingRevisionCardId = '';
+                    }
+                    card.status = 'cancelled';
+                    card.status_label = '已取消';
+                    finishLightweightCard(card, '已取消；没有提交后续执行。');
+                };
+                const beginLightweightRevision = (card) => {
+                    lightweightExtensionConversation.pendingRevisionCardId = card.card_id;
+                    card.summary = '请在页面下方的主对话输入框说明需要修订的内容，然后发送。命令和真实执行事实不会被修改。';
+                };
+                const reviseLightweightCandidate = async (card, feedback) => {
+                    const normalizedFeedback = String(feedback || '').trim();
+                    if (!normalizedFeedback) {
+                        ElMessage.warning('请写明修订意见。');
+                        return;
+                    }
+                    return await submitLightweightOperation(card.extension_id, 'revise', `/api/lightweight-extension-stages/${encodeURIComponent(card.extension_id)}/revise`, {
+                        feedback: normalizedFeedback,
+                        revision_target: 'semantic'
+                    }, card, async () => {
+                        const summary = `已修订：${normalizedFeedback}`;
+                        finishLightweightCard(card, `✓ ${summary}`);
+                        await showLightweightCandidate(card.extension_id, summary, normalizedFeedback);
+                    });
+                };
+                const retryLightweightSemantic = async (card) => {
+                    return await submitLightweightOperation(
+                        card.extension_id,
+                        'retry_semantic',
+                        `/api/lightweight-extension-stages/${encodeURIComponent(card.extension_id)}/retry-semantic`,
+                        {},
+                        card,
+                        async () => {
+                            finishLightweightCard(card, '✓ 语义说明已重新生成；执行命令未重新运行。');
+                            await showLightweightCandidate(card.extension_id);
+                        }
+                    );
+                };
+                const validationRows = async (extensionId, runId) => {
+                    const response = await extensionApiFetch(`/api/lightweight-extension-stages/${encodeURIComponent(extensionId)}/results`);
+                    if (!response.ok) throw new Error(await extensionApiError(response, '读取验证结果失败'));
+                    const data = await response.json();
+                    return lightweightResultRows(lightweightRunById(data.validation_runs, runId));
+                };
+                const validateLightweightExtension = async (card) => {
+                    await submitLightweightOperation(card.extension_id, 'validate', `/api/lightweight-extension-stages/${encodeURIComponent(card.extension_id)}/validate`, {}, card, async (view) => {
+                        finishLightweightCard(card, '✓ 验证已完成；结果核对卡已生成。');
+                        addLightweightCard({
+                            card_id: `${card.extension_id}:result_review:${view.run_id}`, status: 'pending', status_label: '待核对',
+                            title: '运行结果核对', purpose: '这张卡用于查看实际命令、输出与日志；核对无误后才允许授权发布。',
+                            rows: await validationRows(card.extension_id, view.run_id), extension_id: card.extension_id,
+                            actions: { review: true }
+                        });
+                    });
+                };
+                const reviewLightweightResult = async (card) => {
+                    await submitLightweightOperation(card.extension_id, 'review', `/api/lightweight-extension-stages/${encodeURIComponent(card.extension_id)}/review`, {}, card, async () => {
+                        finishLightweightCard(card, '✓ 已核对运行结果。');
+                        addLightweightCard({
+                            card_id: `${card.extension_id}:publish`, status: 'pending', status_label: '待授权',
+                            title: '授权发布', purpose: '这张卡用于确认将已经验证的工具发布为可复用的拓展分析。',
+                            summary: '确认后才会发布；不会自动发布。', extension_id: card.extension_id,
+                            actions: { publish: true, cancel: true }
+                        });
+                    });
+                };
+                const publishLightweightExtension = async (card) => {
+                    await submitLightweightOperation(card.extension_id, 'publish', `/api/lightweight-extension-stages/${encodeURIComponent(card.extension_id)}/publish`, {}, card, async () => {
+                        finishLightweightCard(card, '✓ 已显式授权并发布。');
+                        await loadLightweightExtensionStages();
+                    });
+                };
+                const openLightweightRuntimeCard = async (selectedExtensionId = extensionBuild.extensionId) => {
+                    const extensionId = selectedExtensionId;
+                    if (!extensionId) return;
+                    try {
+                        const help = await lightweightHelp(extensionId);
+                        addLightweightCard({
+                            card_id: `${extensionId}:runtime:${Date.now()}`, status: 'pending', status_label: '待确认', kind: 'runtime',
+                            title: '输入文件和参数', purpose: '这张卡用于确认本次新数据运行的输入文件和原始命令已有参数；确认后立即执行，不会再次弹出确认。',
+                            extension_id: extensionId,
+                            inputs: (help.inputs || []).filter(item => item && item.replaceable).map(item => ({ key: item.path, value: '' })),
+                            parameters: (help.parameters || []).map(item => ({ key: item.fact_id, label: item.flag || item.fact_id, value: item.value || item.flag || '' })),
+                            explicit_prefix: '', actions: { run: true, cancel: true }
+                        });
+                    } catch (err) {
+                        ElMessage.error(err.message || '读取运行说明失败');
+                    }
+                };
+                const runtimeInputPath = (jobId, value) => {
+                    const text = String(value || '').trim();
+                    if (!text || text.startsWith('/')) return text;
+                    if (text.startsWith('input/') || text.startsWith('workspace/')) return text;
+                    return `input/${jobId}/${text}`;
+                };
+                const runLightweightExtension = async (card) => {
+                    const jobId = String(jobInfo.job_id || '').trim();
+                    if (!jobId || jobId === 'default_job') {
+                        ElMessage.warning('请先选择实际运行 Job。');
+                        return;
+                    }
+                    const inputOverrides = Object.fromEntries((card.inputs || []).map(item => [item.key, runtimeInputPath(jobId, item.value)]));
+                    if (Object.values(inputOverrides).some(value => !value)) {
+                        ElMessage.warning('请填写每个输入文件。');
+                        return;
+                    }
+                    const parameterOverrides = Object.fromEntries((card.parameters || []).map(item => [item.key, item.value]));
+                    await submitLightweightOperation(card.extension_id, 'run', `/api/lightweight-extension-stages/${encodeURIComponent(card.extension_id)}/run`, {
+                        run_job_id: jobId,
+                        input_overrides: inputOverrides,
+                        parameter_overrides: parameterOverrides,
+                        explicit_prefix: String(card.explicit_prefix || '').trim() || null
+                    }, card, async (view) => {
+                        finishLightweightCard(card, '✓ 已确认输入与参数；本次运行已完成。');
+                        const response = await extensionApiFetch(`/api/lightweight-extension-stages/${encodeURIComponent(card.extension_id)}/results`);
+                        const data = response.ok ? await response.json() : {};
+                        const run = lightweightRunById(data.runtime_runs, view.run_id);
+                        addLightweightCard({
+                            card_id: `${card.extension_id}:runtime_result:${view.run_id}`, status: 'completed', status_label: '已完成', type: 'success',
+                            title: '运行结果', purpose: '这张卡展示本次新数据运行生成的文件、标准输出和日志。',
+                            extension_id: card.extension_id,
+                            rows: lightweightResultRows(run)
+                        });
+                    });
+                };
+                const resumeLightweightOperation = async () => {
+                    let saved;
+                    try {
+                        saved = JSON.parse(sessionStorage.getItem(lightweightOperationStorageKey) || 'null');
+                    } catch (_) {
+                        return;
+                    }
+                    if (!saved || !saved.extensionId || !saved.operationToken || !saved.action) return;
+                    const card = addLightweightCard({
+                        card_id: saved.cardId || `${saved.extensionId}:${saved.action}`,
+                        status: 'running', status_label: '运行中', type: 'primary', extension_id: saved.extensionId,
+                        title: '正在恢复拓展分析状态', purpose: '页面已恢复；系统继续轮询同一个操作，不会重复提交。',
+                        summary: `正在恢复 ${saved.action}…`
+                    });
+                    if (!card) return;
+                    await pollLightweightOperation(saved.extensionId, saved.operationToken, card, async (view) => {
+                        const next = lightweightResumeNext(saved.action);
+                        switch (next) {
+                            case 'candidate':
+                                finishLightweightCard(card, '✓ 已恢复并完成；候选核对卡已生成。');
+                                extensionBuild.extensionId = saved.extensionId;
+                                await loadLightweightExtensionStages();
+                                await showLightweightCandidate(saved.extensionId, saved.action === 'revise' ? '已恢复修订；请核对最新候选。' : undefined);
+                                break;
+                            case 'validate':
+                                finishLightweightCard(card, '✓ 已恢复确认；可以开始验证。');
+                                addLightweightCard({
+                                    card_id: `${saved.extensionId}:validate`, status: 'pending', status_label: '待执行',
+                                    title: '开始验证', purpose: '这张卡用于用同一份测试数据执行已确认的工具，并生成可核对的结果。',
+                                    summary: '确认无误后点击“开始验证”。', extension_id: saved.extensionId, actions: { validate: true }
+                                });
+                                break;
+                            case 'review':
+                                finishLightweightCard(card, '✓ 已恢复验证；结果核对卡已生成。');
+                                addLightweightCard({
+                                    card_id: `${saved.extensionId}:result_review:${view.run_id}`, status: 'pending', status_label: '待核对',
+                                    title: '运行结果核对', purpose: '这张卡用于查看实际命令、输出与日志；核对无误后才允许授权发布。',
+                                    rows: await validationRows(saved.extensionId, view.run_id), extension_id: saved.extensionId, actions: { review: true }
+                                });
+                                break;
+                            case 'publish':
+                                finishLightweightCard(card, '✓ 已恢复结果核对；可以授权发布。');
+                                addLightweightCard({
+                                    card_id: `${saved.extensionId}:publish`, status: 'pending', status_label: '待授权',
+                                    title: '授权发布', purpose: '这张卡用于确认将已经验证的工具发布为可复用的拓展分析。',
+                                    summary: '确认后才会发布；不会自动发布。', extension_id: saved.extensionId, actions: { publish: true, cancel: true }
+                                });
+                                break;
+                            case 'list':
+                                finishLightweightCard(card, '✓ 已恢复并发布。');
+                                await loadLightweightExtensionStages();
+                                break;
+                            case 'runtime_result': {
+                                finishLightweightCard(card, '✓ 已恢复运行；本次结果卡已生成。');
+                                const response = await extensionApiFetch(`/api/lightweight-extension-stages/${encodeURIComponent(saved.extensionId)}/results`);
+                                const data = response.ok ? await response.json() : {};
+                                addLightweightCard({
+                                    card_id: `${saved.extensionId}:runtime_result:${view.run_id}`, status: 'completed', status_label: '已完成', type: 'success',
+                                    title: '运行结果', purpose: '这张卡展示本次新数据运行生成的文件、标准输出和日志。',
+                                    extension_id: saved.extensionId, rows: lightweightResultRows(lightweightRunById(data.runtime_runs, view.run_id))
+                                });
+                                break;
+                            }
+                            default:
+                                finishLightweightCard(card, '✓ 已恢复并完成。');
+                        }
+                    });
+                };
+                const stopLightweightOperation = async () => {
+                    const extensionId = lightweightExtensionConversation.activeExtensionId;
+                    const operationToken = lightweightExtensionConversation.activeOperationToken;
+                    if (!extensionId || !operationToken) return false;
+                    const response = await extensionApiFetch(`/api/lightweight-extension-stages/${encodeURIComponent(extensionId)}/operations/${encodeURIComponent(operationToken)}/stop`, { method: 'POST' });
+                    if (!response.ok) throw new Error(await extensionApiError(response, '停止拓展分析失败'));
+                    return true;
+                };
+                const loadLightweightExtensionStages = async () => {
+                    try {
+                        const response = await extensionApiFetch('/api/lightweight-extension-stages/');
+                        if (!response.ok) throw new Error(await extensionApiError(response, '读取轻量拓展分析列表失败'));
+                        lightweightExtensions.value = (await response.json()).extensions || [];
+                    } catch (err) {
+                        console.warn('[lightweight extension] list failed', err);
+                    }
+                };
+                const answerLightweightExtensionHelp = async (message) => {
+                    const query = String(message || '');
+                    const matched = (lightweightExtensions.value || []).find(item => query.includes(item.extension_id));
+                    if (!matched) {
+                        const response = await extensionApiFetch('/api/lightweight-extension-stages/intent', {
+                            method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ message: query })
+                        });
+                        const data = response.ok ? await response.json() : {};
+                        await addAgentMessage('assistant', data.usage || '上传可执行代码、测试数据和原始命令，核对候选后验证并授权发布；发布后可指定输入和原命令已有参数运行。');
+                        return true;
+                    }
+                    const help = await lightweightHelp(matched.extension_id);
+                    await addAgentMessage('assistant', lightweightRows(help).map(row => `${row.item}：${row.value}`).join('\n'));
+                    return true;
+                };
+                const buildExtensionStageLegacy = async () => {
                     if (!extensionBuild.displayName || !extensionBuild.codeFiles.length) {
                         ElMessage.warning('请填写名称，并上传原始代码。');
                         return;
@@ -19172,6 +20021,7 @@ compare: [[flesh, peel]]`;
                         extensionBuild.statusDialogVisible = false;
                     }
                 };
+                const buildExtensionStage = async () => buildLightweightExtensionStage();
                 const loadExtensionPreview = async () => {
                     if (!extensionBuild.extensionId) return null;
                     const response = await extensionApiFetch(`/api/extension-stages/${encodeURIComponent(extensionBuild.extensionId)}/preview`);
@@ -19294,7 +20144,8 @@ compare: [[flesh, peel]]`;
                         extensionStages.value = data.extensions || [];
                         if (extensionBuild.extensionId) {
                             const selected = extensionStages.value.find(item => item.extension_id === extensionBuild.extensionId);
-                            if (!selected || (!includeDrafts && !extensionIsPublishedSuccessful(selected))) extensionBuild.extensionId = '';
+                            const lightweight = lightweightExtensions.value.find(item => item.extension_id === extensionBuild.extensionId);
+                            if ((!selected || (!includeDrafts && !extensionIsPublishedSuccessful(selected))) && !lightweight) extensionBuild.extensionId = '';
                         }
                         if (!extensionRun.extensionId && extensionStages.value.length) {
                             const published = extensionStages.value.find(extensionIsPublishedSuccessful);
@@ -19460,11 +20311,15 @@ compare: [[flesh, peel]]`;
                     });
                 };
                 const runExtensionStageFromIntent = async (intent, userText = '') => {
-                    const params = intent?.params || {};
-                    const extensionId = params.extension_id || params.extensionId || '';
-                    if (!extensionId) throw new Error('没有识别到要执行的拓展分析阶段');
-                    const inputPaths = Array.isArray(params.input_paths) ? params.input_paths : [];
-                    const runParameters = { ...(params.parameters || {}) };
+	                    const params = intent?.params || {};
+	                    const extensionId = params.extension_id || params.extensionId || '';
+	                    if (!extensionId) throw new Error('没有识别到要执行的拓展分析阶段');
+	                    if (isLightweightExtensionId(extensionId)) {
+                        extensionBuild.extensionId = extensionId;
+                        return await openLightweightRuntimeCard(extensionId);
+                    }
+	                    const inputPaths = Array.isArray(params.input_paths) ? params.input_paths : [];
+	                    const runParameters = { ...(params.parameters || {}) };
                     if (params.targetSpecies) runParameters.targetSpecies = params.targetSpecies;
                     if (params.referenceSpecies) runParameters.referenceSpecies = params.referenceSpecies;
                     if (params.file_roles) runParameters.file_roles = params.file_roles;
@@ -21320,6 +22175,106 @@ compare: [[flesh, peel]]`;
                     nlLoading.value = true;
                     nlStatusText.value = '正在识别你的分析意图...';
 
+                    const revisionCard = lightweightExtensionConversation.cards.find(
+                        card => card.card_id === lightweightExtensionConversation.pendingRevisionCardId
+                    );
+                    if (revisionCard) {
+                        try {
+                            nlStatusText.value = '正在按你的意见修订拓展分析说明...';
+                            if (!currentConversationId.value) await createNewConversation();
+                            await addAgentMessage('user', userInput);
+                            lightweightExtensionConversation.pendingRevisionCardId = '';
+                            const result = await reviseLightweightCandidate(revisionCard, userInput);
+                            if (!result || result.state === 'failed') {
+                                lightweightExtensionConversation.pendingRevisionCardId = revisionCard.card_id;
+                            }
+                        } finally {
+                            nlInput.value = '';
+                            nlLoading.value = false;
+                            nlStatusText.value = '';
+                        }
+                        return;
+                    }
+
+                    const earlyLowerInput = userInput.toLowerCase();
+                    const wantsIdentifyMemberReviewEarly = (
+                        !userInput.includes('亚家族') &&
+                        (userInput.includes('基因家族成员') || userInput.includes('家族成员') || userInput.includes('成员筛选') || userInput.includes('成员确认') || earlyLowerInput.includes('member')) &&
+                        (userInput.includes('筛选') || userInput.includes('确认') || userInput.includes('修改') || userInput.includes('修订') || userInput.includes('调出') || userInput.includes('打开') || userInput.includes('弹出') || earlyLowerInput.includes('review') || earlyLowerInput.includes('filter') || earlyLowerInput.includes('edit'))
+                    );
+                    if (wantsIdentifyMemberReviewEarly) {
+                        try {
+                            if (!jobInfo.job_id || jobInfo.job_id === 'default_job') {
+                                ElMessage.warning('请先选择或创建 Working Directory');
+                                nlLoading.value = false;
+                                return;
+                            }
+                            if (!currentConversationId.value) {
+                                await createNewConversation();
+                            }
+                            addAgentMessage('user', userInput);
+                            const speciesForReview = inferSpeciesCodeFromText(userInput) || (params.targetSpecies && params.targetSpecies[0]) || '';
+                            const familyForReview = inferGeneFamilyFromText(userInput) || params.geneFamily || confirmParams.geneFamily || 'SPL';
+                            const reviewPrefix = speciesForReview ? `${speciesForReview}.${familyForReview}` : executionPrefix('identify');
+                            const opened = await maybeShowIdentifyDomainReview('identify', true, reviewPrefix);
+                            addAgentMessage('assistant', opened
+                                ? `已调出${speciesForReview ? speciesForReview + ' ' : ''}${familyForReview} 基因家族成员确认表。你可以按表格筛选后重建 final_members。`
+                                : `${speciesForReview ? speciesForReview + ' ' : ''}${familyForReview} 基因家族成员确认表没有打开：未找到 identify 结果或成员表。`);
+                        } finally {
+                            nlInput.value = '';
+                            nlLoading.value = false;
+                        }
+                        return;
+                    }
+
+                    // V2: RAG模式 - 文献问答
+                    if (ragMode.value) {
+                        try {
+                            nlStatusText.value = '正在检索知识库并生成回答...';
+                            addMessage('user', userInput);
+                            ragHistory.value.push({ role: 'user', content: userInput, time: new Date().toLocaleTimeString() });
+
+                            // 调用当前 bbav5 后端 RAG 代理，随页面端口走同源地址（例如 7880）
+                            const data = await fetchJsonWithTimeout('/api/agent/rag', {
+                                method: 'POST',
+                                headers: { 'Content-Type': 'application/json' },
+                                body: JSON.stringify({
+                                    query: userInput,
+                                    mode: 'rag',
+                                    top_k: 10
+                                })
+                            }, 120000, '知识库检索');
+                            const answer = normalizeRagAnswerForDisplay(data.success === false
+                                ? (data.message || '未找到相关信息')
+                                : (data.response || data.answer || '未找到相关信息'), userInput);
+                            const ragSources = data.sources || data.references || [];
+
+                            addMessage('assistant', answer, {
+                                intent: {
+                                    taskType: 'faq',
+                                    sources: ragSources
+                                }
+                            });
+                            ragHistory.value.push({ role: 'assistant', content: answer, time: new Date().toLocaleTimeString() });
+
+                            // 滚动到底部
+                            setTimeout(() => {
+                                if (chatArea.value) {
+                                    chatArea.value.scrollTop = chatArea.value.scrollHeight;
+                                }
+                            }, 100);
+
+                        } catch (err) {
+                            ElMessage.error('RAG请求失败: ' + err.message);
+                            addMessage('assistant', '抱歉，文献检索服务暂时不可用。');
+                        } finally {
+                            nlInput.value = '';
+                            nlLoading.value = false;
+                            nlStatusText.value = '';
+                        }
+                        return;
+                    }
+
                     // Agent模式 - 技能执行
                     try {
                         // 检查是否有绑定的 job
@@ -21338,6 +22293,129 @@ compare: [[flesh, peel]]`;
                         // 添加用户消息到Agent会话
                         addAgentMessage('user', userInput);
 
+                        const lowerInput = userInput.toLowerCase();
+                        const dataPaths = extractDataPathsFromText(userInput);
+                        const dataPath = dataPaths.join(',');
+                        const pathMatch = dataPath ? [dataPath, dataPath] : null;
+                        const inferredSpeciesCode = dataPaths.length > 1 ? '' : inferSpeciesCodeFromText(userInput);
+                        const inferredGeneFamily = inferGeneFamilyFromText(userInput);
+                        const wantsSubfamilyReviewTable = (
+                            (userInput.includes('亚家族') || lowerInput.includes('subfamily')) &&
+                            (userInput.includes('分类表') || userInput.includes('确认表') || userInput.includes('标签表') || userInput.includes('结果表') || lowerInput.includes('table')) &&
+                            (userInput.includes('打开') || userInput.includes('调出') || userInput.includes('弹出') || userInput.includes('修订') || userInput.includes('修改') || userInput.includes('确认') || lowerInput.includes('open') || lowerInput.includes('review') || lowerInput.includes('edit'))
+                        );
+                        if (wantsSubfamilyReviewTable) {
+                            const speciesMatch = userInput.match(/\b([A-Z][a-zA-Z0-9]{0,5})\b/);
+                            const requestedSpecies = speciesMatch ? speciesMatch[1] : '';
+                            const familyForReview = inferredGeneFamily || params.geneFamily || confirmParams.geneFamily || 'SPL';
+                            const reviewPrefix = requestedSpecies ? `${requestedSpecies}.${familyForReview}` : '';
+                            const opened = await maybeShowSubfamilyReview('reference_classification', true, reviewPrefix);
+                            if (opened) {
+                                addAgentMessage('assistant', `已调出${requestedSpecies ? requestedSpecies + ' ' : ''}亚家族分类确认表。你可以在弹窗中修订 confirmed_subfamily，点击“确认亚家族标签”后保存。`);
+                            } else {
+                                addAgentMessage('assistant', `${requestedSpecies ? requestedSpecies + ' ' : ''}亚家族分类确认表没有打开：未找到可确认的分类结果。请先确认该物种已完成 reference_classification。`);
+                            }
+                            nlInput.value = '';
+                            nlLoading.value = false;
+                            return;
+                        }
+                        const mentionsConfigAutofill = lowerInput.includes('config') || lowerInput.includes('config.xlsx') || userInput.includes('配置表') || userInput.includes('配置文件');
+                        const mentionsSamplesAutofill = lowerInput.includes('samples') || lowerInput.includes('samples.yaml') || userInput.includes('样本表') || userInput.includes('样本配置') || userInput.includes('样本文件');
+                        const wantsExtensionStage = lowerInput.includes('extension') || userInput.includes('拓展分析') || userInput.includes('扩展分析');
+                        const asksExtensionHelp = wantsExtensionStage && (
+                            lowerInput.includes('help') || userInput.includes('如何使用') || userInput.includes('怎么用') ||
+                            userInput.includes('输入') || userInput.includes('参数') || userInput.includes('功能') || userInput.includes('帮助')
+                        );
+                        if (asksExtensionHelp) {
+                            try {
+                                await answerLightweightExtensionHelp(userInput);
+                            } catch (err) {
+                                await addAgentMessage('assistant', `拓展分析帮助暂时不可用：${err.message || err}`);
+                            } finally {
+                                nlInput.value = '';
+                                nlLoading.value = false;
+                            }
+                            return;
+                        }
+                        const wantsAutofillOpen = userInput.includes('打开') || userInput.includes('调出') || userInput.includes('弹出') || userInput.includes('修订') || userInput.includes('修改') || userInput.includes('核对') || userInput.includes('检查') || lowerInput.includes('open') || lowerInput.includes('edit') || lowerInput.includes('review');
+                        const wantsAutofillRegenerate = userInput.includes('自动') || userInput.includes('填写') || userInput.includes('生成') || userInput.includes('重新识别') || userInput.includes('重新检测') || lowerInput.includes('autofill') || lowerInput.includes('regenerate');
+                        if (!wantsExtensionStage && mentionsConfigAutofill && (wantsAutofillOpen || wantsAutofillRegenerate)) {
+                            if (pathMatch) {
+                                inputPath.value = pathMatch[1];
+                                await loadFromPath({ suppressAutofill: true });
+                            }
+                            await openAutofillDialog('config', {
+                                description: userInput,
+                                speciesCode: inferredSpeciesCode,
+                                analysisFamily: '',
+                                autoGenerate: wantsAutofillRegenerate,
+                                keepCurrentRows: !wantsAutofillRegenerate,
+                            });
+                            addAgentMessage('assistant', wantsAutofillRegenerate
+                                ? '已重新识别并生成 config.xlsx 草稿。请在弹窗中核对并修订，确认后才会写入正式 config.xlsx。'
+                                : '已打开 config.xlsx 自动识别表。你可以直接修订单行，或用批量修订区筛选、预览、Apply。');
+                            nlInput.value = '';
+                            nlLoading.value = false;
+                            return;
+                        }
+                        if (!wantsExtensionStage && mentionsSamplesAutofill && (wantsAutofillOpen || wantsAutofillRegenerate)) {
+                            if (pathMatch) {
+                                inputPath.value = pathMatch[1];
+                                await loadFromPath({ suppressAutofill: true });
+                            }
+                            await openAutofillDialog('samples', {
+                                description: userInput,
+                                autoGenerate: wantsAutofillRegenerate,
+                                keepCurrentRows: !wantsAutofillRegenerate,
+                            });
+                            addAgentMessage('assistant', wantsAutofillRegenerate
+                                ? '已重新识别并生成 samples.yaml 草稿。请确认 run、sample_id、condition、replicate 和 control_group 后再写入正式 samples.yaml。'
+                                : '已打开 samples.yaml 自动识别表。你可以直接修订样本、分组、重复和对照组。');
+                            nlInput.value = '';
+                            nlLoading.value = false;
+                            return;
+                        }
+                        const isDataLocationStatement = pathMatch && !wantsExtensionStage && !isUtilitySequenceRequest(userInput) && (
+                            lowerInput.includes('rnaseq') || lowerInput.includes('rna-seq') || lowerInput.includes('fastq') ||
+                            lowerInput.includes('data') || lowerInput.includes('folder') || lowerInput.includes('directory') ||
+                            lowerInput.includes('path') || lowerInput.includes('located') || lowerInput.includes('stored') ||
+                            lowerInput.includes('reference') || lowerInput.includes('files are in') ||
+                            userInput.includes('转录组') || userInput.includes('样本') || userInput.includes('数据目录') ||
+                            userInput.includes('文件目录') || userInput.includes('文件在') || userInput.includes('数据在') ||
+                            userInput.includes('分析数据') || userInput.includes('文件夹') || userInput.includes('目录') ||
+                            userInput.includes('路径') || userInput.includes('放在') || userInput.includes('位于')
+                        );
+                        if (isDataLocationStatement) {
+                            inputPath.value = pathMatch[1];
+                            const beforeQueueLength = autofillAutoQueue.value.length;
+                            const loadResult = await loadFromPath({
+                                description: userInput,
+                                speciesCode: inferredSpeciesCode,
+                                analysisFamily: ''
+                            });
+                            const hasLoadDraftRows = (draft) => Array.isArray(draft?.rows) && draft.rows.length > 0;
+                            const hasSamplesDraft = !!loadResult?.samples_draft_created && hasLoadDraftRows(loadResult?.samples_draft);
+                            const hasConfigDraft = !!loadResult?.config_draft_created && hasLoadDraftRows(loadResult?.config_draft);
+                            if (autofillAutoQueue.value.length > beforeQueueLength || autofillDialogVisible.value || hasSamplesDraft || hasConfigDraft) {
+                                const msg = hasSamplesDraft
+                                    ? (hasConfigDraft
+                                        ? '已识别到 RNA-seq FASTQ 和参考资源，优先打开 samples.yaml 草稿供你核对样本、分组和对照；config.xlsx 草稿也已生成。'
+                                        : '已识别到 RNA-seq/FASTQ 数据并生成 samples.yaml 草稿。请在弹窗中核对 run、sample_id、condition、replicate、control_group 后再写入正式 samples.yaml。')
+                                    : '已把目录中的可识别参考资源导入当前 job，并生成 config.xlsx 草稿。请在弹窗中核对和修订，点击“确认并写入正式配置”后再执行正式分析。';
+                                addAgentMessage('assistant', msg);
+                                nlInput.value = '';
+                                nlLoading.value = false;
+                                return;
+                            }
+                            const loadedCount = loadResult?.count || 0;
+                            addAgentMessage('assistant', loadedCount > 0
+                                ? `已把路径中的 ${loadedCount} 个可识别文件软链接到当前 job，但没有发现需要自动填写 config.xlsx 或 samples.yaml 的文件类型；请检查目录或继续补充文件。`
+                                : '我识别到你是在提供数据路径，但该路径下没有发现可用于 config.xlsx / samples.yaml 的文件。请确认目录是否包含 genome/pep/cds/gff/hmm 或 FASTQ 文件。');
+                            nlInput.value = '';
+                            nlLoading.value = false;
+                            return;
+                        }
+
                         nlStatusText.value = '正在识别意图和分析类型...';
                         const data = await requestAgentChatWithProgress({
                             message: userInput,
@@ -21363,6 +22441,23 @@ compare: [[flesh, peel]]`;
                                 nlInput.value = '';
                                 return;
                             }
+                            if (data.intent.ui_action === 'open_config_dialog') {
+                                await openAutofillDialog('config', {
+                                    description: userInput,
+                                    keepCurrentRows: false,
+                                });
+                                const opened = await openExistingAutofillDraft('config');
+                                addAgentMessage('assistant', opened
+                                    ? (data.intent.message || '已打开当前 job 的 config.xlsx 核对表。')
+                                    : '当前 job 中没有找到可打开的 config.xlsx 草稿或正式配置。', {
+                                    stage: null,
+                                    taskType: 'ui_action',
+                                    params: { ui_action: data.intent.ui_action }
+                                }, false);
+                                nlLoading.value = false;
+                                nlInput.value = '';
+                                return;
+                            }
                             if (data.action === 'reply' || data.action === 'clarify') {
                                 addAgentMessage('assistant', data.intent.message || '请补充你的需求。', {
                                     stage: null,
@@ -21601,6 +22696,7 @@ compare: [[flesh, peel]]`;
                     runtimeOverview.workers = Array.isArray(data.workers) ? data.workers : [];
                     runtimeOverview.queues = Array.isArray(data.queues) ? data.queues : [];
                     runtimeOverview.active_tasks = Array.isArray(data.active_tasks) ? data.active_tasks : [];
+                    runtimeOverview.resource_tasks = Array.isArray(data.resource_tasks) ? data.resource_tasks : [];
                     runtimeOverview.summary = data.summary || {
                         worker_count: 0,
                         queue_count: 0,
@@ -21637,6 +22733,19 @@ compare: [[flesh, peel]]`;
                     tokenCostSummary.error = data.error || '';
                 };
 
+                const refreshResourceUsage = async () => {
+                    try {
+                        const response = await fetch('/api/resource/status', { cache: 'no-store' });
+                        if (!response.ok) return;
+                        const data = await response.json();
+                        if (data && data.usage) {
+                            runtimeOverview.resource_usage = data.usage;
+                        }
+                    } catch (_) {
+                        // Celery overview continues to provide a slower fallback snapshot.
+                    }
+                };
+
                 const refreshRuntimeOverview = async () => {
                     if (runtimeMonitorLoading.value) return;
                     runtimeMonitorLoading.value = true;
@@ -21785,8 +22894,11 @@ compare: [[flesh, peel]]`;
 
                 const startRuntimeMonitor = () => {
                     if (runtimeMonitorTimer) clearInterval(runtimeMonitorTimer);
+                    if (resourceMonitorTimer) clearInterval(resourceMonitorTimer);
                     refreshRuntimeOverview();
+                    refreshResourceUsage();
                     runtimeMonitorTimer = setInterval(refreshRuntimeOverview, 5000);
+                    resourceMonitorTimer = setInterval(refreshResourceUsage, 1000);
                 };
 
                 const stopRuntimeMonitor = () => {
@@ -21794,6 +22906,10 @@ compare: [[flesh, peel]]`;
                         clearInterval(runtimeMonitorTimer);
                         runtimeMonitorTimer = null;
                     }
+                    if (resourceMonitorTimer) {
+                        clearInterval(resourceMonitorTimer);
+                        resourceMonitorTimer = null;
+                    }
                 };
 
                 const activeGeneFamilyScopeId = () => {
@@ -21969,14 +23085,18 @@ compare: [[flesh, peel]]`;
                     stopRuntimeMonitor();
                 };
 
-                onMounted(() => {
-                    refreshInfo();
-                    refreshResults();
+                onMounted(async () => {
+                    await refreshInfo();
+                    await loadConversations();
+                    if (!currentConversation.value?.job_id && jobInfo.job_id) {
+                        await refreshResults(jobInfo.job_id);
+                    }
                     fetchAgentTasks();
                     startAgentTaskPolling();
                     startRuntimeMonitor();
-                    loadConversations();  // 加载会话列表
                     loadExtensionStages();
+                    loadLightweightExtensionStages();
+                    resumeLightweightOperation();
                     loadExtensionRuns();
                     loadMethodologyJobs();
                     
@@ -22177,11 +23297,16 @@ compare: [[flesh, peel]]`;
                     executeStagesWithDependencies,
                     executeStageWithConfirmation,
                     stages,
-                    visibleStages,
+                    resultGroups,
+                    activeResultGroups,
                     resultStageFilter,
                     setResultStageFilter,
                     // 异步任务轮询
                     currentTask,
+                    showExecutionIndicator,
+                    executionIndicatorStage,
+                    executionIndicatorElapsed,
+                    executionIndicatorStatusText,
                     // Stop Execution相关
                     isExecuting,
                     isStopping,
@@ -22303,6 +23428,8 @@ compare: [[flesh, peel]]`;
                     extensionBuild,
                     extensionStages,
                     extensionCompletedStages,
+                    lightweightExtensionConversation,
+                    isLightweightExtensionSelected,
                     extensionStageOptionLabel,
                     selectExistingExtensionStage,
                     extensionRuns,
@@ -22319,6 +23446,16 @@ compare: [[flesh, peel]]`;
                     onExtensionDataFilesChange,
                     removeExtensionFile,
                     buildExtensionStage,
+                    confirmLightweightCandidate,
+                    cancelLightweightCard,
+                    beginLightweightRevision,
+                    reviseLightweightCandidate,
+                    retryLightweightSemantic,
+                    validateLightweightExtension,
+                    reviewLightweightResult,
+                    publishLightweightExtension,
+                    openLightweightRuntimeCard,
+                    runLightweightExtension,
                     loadExtensionPreview,
                     openExtensionConfirm,
                     trialRunExtensionStage,
diff --git a/apps/web/vue3/main.py b/apps/web/vue3/main.py
index 1df1027c2..11a08cfba 100644
--- a/apps/web/vue3/main.py
+++ b/apps/web/vue3/main.py
@@ -665,19 +665,10 @@ def _apply_scope_selection_to_intent(intent: Dict[str, Any], message: str) -> No
         params["geneFamily"] = family
 
 
-def _confirmed_config_species_scope(job_id: str) -> Dict[str, list[str]]:
-    """Read species roles only when the job has authoritative config confirmation."""
+def _configured_species_scope(job_id: str) -> Dict[str, list[str]]:
+    """Read the species roles declared by the current job config."""
     if not job_id:
         return {}
-    try:
-        from gfa_core.mas.confirmation_snapshot import build_confirmation_snapshot
-
-        confirmation = build_confirmation_snapshot(PROJECT_ROOT, job_id)
-    except (OSError, ValueError):
-        return {}
-    if not confirmation.get("config_confirmed"):
-        return {}
-
     config_path = INPUT_ROOT / job_id / "config.xlsx"
     try:
         import pandas as pd
@@ -705,6 +696,21 @@ def _confirmed_config_species_scope(job_id: str) -> Dict[str, list[str]]:
     return scope if any(scope.values()) else {}
 
 
+def _confirmed_config_species_scope(job_id: str) -> Dict[str, list[str]]:
+    """Read species roles only when the job has authoritative config confirmation."""
+    if not job_id:
+        return {}
+    try:
+        from gfa_core.mas.confirmation_snapshot import build_confirmation_snapshot
+
+        confirmation = build_confirmation_snapshot(PROJECT_ROOT, job_id)
+    except (OSError, ValueError):
+        return {}
+    if not confirmation.get("config_confirmed"):
+        return {}
+    return _configured_species_scope(job_id)
+
+
 def _normalize_main_agent_analysis_intent(
     intent: Dict[str, Any],
     *,
@@ -1137,7 +1143,7 @@ def _load_identify_species_selection(job_id: str) -> Dict[str, Any]:
         current_role = entry.get("role", "unspecified")
         if role == "target":
             entry["role"] = "target"
-        elif role in {"ref", "seed_reference", "known_family_reference"} and current_role != "target":
+        elif role in {"ref", "reference", "seed_reference", "known_family_reference"} and current_role != "target":
             entry["role"] = role
         elif role in {"comparative", "compactive", "outgroup"} and current_role not in {"target", "ref", "seed_reference", "known_family_reference"}:
             entry["role"] = role
@@ -1185,7 +1191,7 @@ def _load_identify_species_selection(job_id: str) -> Dict[str, Any]:
             groups["target"].append(item)
         elif role in {"comparative", "compactive", "outgroup"}:
             groups["comparative"].append(item)
-        elif role in {"ref", "seed_reference", "known_family_reference"}:
+        elif role in {"ref", "reference", "seed_reference", "known_family_reference"}:
             groups["reference"].append(item)
         else:
             groups["other"].append(item)
@@ -1344,6 +1350,53 @@ def _extract_species_codes_from_text_for_job(job_id: str, text: str) -> list[str
     return ordered
 
 
+def _resolve_subfamily_request_species_roles(
+    job_id: str,
+    message: str,
+    intent: Optional[Dict[str, Any]] = None,
+) -> Dict[str, list[str]]:
+    """Preserve config roles while resolving species mentioned in a subfamily request."""
+    routed_intent = intent or {}
+    params = routed_intent.get("params") or {}
+    structured_targets = _canonicalize_species_codes_for_job(
+        job_id,
+        _param_list(params.get("targetSpecies") or routed_intent.get("target_species")),
+    )
+    structured_refs = _canonicalize_species_codes_for_job(
+        job_id,
+        _param_list(params.get("referenceSpecies") or routed_intent.get("reference_species")),
+    )
+    structured_comps = _canonicalize_species_codes_for_job(
+        job_id,
+        _param_list(params.get("comparativeSpecies") or routed_intent.get("comparative_species")),
+    )
+    mentioned = _extract_species_codes_from_text_for_job(job_id, message or "")
+    configured = _configured_species_scope(job_id)
+    configured_targets = _canonicalize_species_codes_for_job(job_id, configured.get("targetSpecies") or [])
+    configured_refs = _canonicalize_species_codes_for_job(job_id, configured.get("referenceSpecies") or [])
+    configured_comps = _canonicalize_species_codes_for_job(job_id, configured.get("comparativeSpecies") or [])
+    if configured:
+        target_candidates = [*structured_targets, *mentioned]
+        comp_candidates = [*structured_comps, *mentioned]
+        ref_candidates = [*structured_refs, *mentioned]
+        targets = [species for species in configured_targets if species in target_candidates]
+        comps = [species for species in configured_comps if species in comp_candidates]
+        refs = [species for species in configured_refs if species in ref_candidates]
+        if not refs:
+            refs = list(configured_refs)
+    else:
+        targets = structured_targets or mentioned
+        refs = structured_refs
+        comps = structured_comps
+    classification_species = list(dict.fromkeys([*targets, *comps]))
+    return {
+        "target_species": targets,
+        "reference_species": refs,
+        "comparative_species": comps,
+        "classification_species": classification_species,
+    }
+
+
 
 def _species_groups_from_selection(selection: Dict[str, Any]) -> tuple[list[str], list[str], list[str]]:
     groups = selection.get("groups", {}) if isinstance(selection, dict) else {}
@@ -1584,6 +1637,10 @@ def _split_subfamily_selected_species_by_config_roles(
     selected_set = set(selected)
     target_role = _subfamily_group_species(identify_selection or {}, ["target"])
     comparative_role = _subfamily_group_species(identify_selection or {}, ["comparative", "other"])
+    if not target_role and not comparative_role:
+        configured = _configured_species_scope(job_id)
+        target_role = _canonicalize_species_codes_for_job(job_id, configured.get("targetSpecies") or [])
+        comparative_role = _canonicalize_species_codes_for_job(job_id, configured.get("comparativeSpecies") or [])
     targets = [sp for sp in target_role if sp in selected_set]
     comps = [sp for sp in comparative_role if sp in selected_set and sp not in targets]
     if not targets:
@@ -1726,18 +1783,47 @@ def _downstream_gene_family_stages_for_context(message: str) -> list[str]:
     return list(dict.fromkeys(stages))
 
 
-def _resolve_contextual_gene_family_request(job_id: str, message: str, request_prefix: str = "") -> Dict[str, Any]:
+def _resolve_contextual_gene_family_request(
+    job_id: str,
+    message: str,
+    request_prefix: str = "",
+    requested_stages: list[str] | None = None,
+    request_intent: Dict[str, Any] | None = None,
+) -> Dict[str, Any]:
     """Resolve post-subfamily/default phylogeny context from real project state.
 
     This is deliberately rule-based: it decides scope/route boundaries from
     files and config, while LLM/intent parsing may still supply user wording.
     """
     text = str(message or "")
+    structured_stages = list(dict.fromkeys(
+        str(stage).strip()
+        for stage in (requested_stages or [])
+        if str(stage).strip()
+    ))
+    contextual_stage_request = bool(
+        set(structured_stages) & {"phylogeny", "motif", "domain", "structure", "combo"}
+    )
+    routed_intent = request_intent or {}
+    routed_params = routed_intent.get("params") or {}
+    structured_targets = _canonicalize_species_codes_for_job(
+        job_id,
+        _param_list(routed_params.get("targetSpecies") or routed_intent.get("target_species")),
+    )
+    structured_refs = _canonicalize_species_codes_for_job(
+        job_id,
+        _param_list(routed_params.get("referenceSpecies") or routed_intent.get("reference_species")),
+    )
+    structured_comps = _canonicalize_species_codes_for_job(
+        job_id,
+        _param_list(routed_params.get("comparativeSpecies") or routed_intent.get("comparative_species")),
+    )
     if not (
         _looks_like_phylogeny_query(text)
         or _looks_like_gene_family_workflow_query(text)
         or _looks_like_intraspecies_synteny_query(text)
         or _looks_like_tfbs_query(text)
+        or contextual_stage_request
     ):
         return {}
     selection = _load_identify_species_selection(job_id)
@@ -1762,11 +1848,13 @@ def _resolve_contextual_gene_family_request(job_id: str, message: str, request_p
             if sp not in mentioned_targets:
                 mentioned_targets.append(sp)
 
-    has_explicit_scope = bool(mentioned)
+    has_explicit_scope = bool(mentioned or structured_targets or structured_refs or structured_comps)
     is_all_species_request = _looks_like_all_species_query(text) or _looks_like_all_subfamily_species_query(text)
     is_intraspecies_synteny_request = _looks_like_intraspecies_synteny_query(text)
-    if has_explicit_scope:
+    if mentioned:
         targets = mentioned_targets or [sp for sp in mentioned if sp not in mentioned_refs and sp not in mentioned_comps]
+    elif structured_targets:
+        targets = list(structured_targets)
     elif is_all_species_request and config_targets:
         targets = list(config_targets)
     elif is_intraspecies_synteny_request and config_targets:
@@ -1780,8 +1868,8 @@ def _resolve_contextual_gene_family_request(job_id: str, message: str, request_p
     else:
         targets = []
 
-    refs = mentioned_refs or (list(config_refs) if is_all_species_request else [])
-    comps = mentioned_comps or (list(config_comps) if is_all_species_request else [])
+    refs = mentioned_refs or list(structured_refs) or (list(config_refs) if is_all_species_request else [])
+    comps = mentioned_comps or list(structured_comps) or (list(config_comps) if is_all_species_request else [])
     if refs and comps:
         scope_mode = "target_plus_reference_plus_comparative"
     elif refs:
@@ -1793,7 +1881,7 @@ def _resolve_contextual_gene_family_request(job_id: str, message: str, request_p
 
     if not family or not targets:
         return {}
-    stages = _downstream_gene_family_stages_for_context(text)
+    stages = structured_stages or _downstream_gene_family_stages_for_context(text)
     subfamily_label_stages = {"phylogeny", "motif", "domain", "structure", "combo"}
     needs_subfamily_labels_for_stage = any(stage in subfamily_label_stages for stage in stages)
     prefix = f"{targets[0]}.{family}" if len(targets) == 1 else f"Target.{family}"
@@ -1826,6 +1914,7 @@ def _resolve_contextual_gene_family_request(job_id: str, message: str, request_p
             or _requires_confirmed_subfamily_query(text)
             or _looks_like_gene_family_workflow_query(text)
             or _looks_like_phylogeny_query(text)
+            or contextual_stage_request
         )
     )
     requires_confirmed = wants_subfamily_context
@@ -3870,6 +3959,9 @@ def _attach_agent_manifest_status(task: Dict) -> None:
         print(f"[API DEBUG] Failed to attach agent manifest status: {e}")
 
 app = FastAPI(title="BotanicalBaseAgent API")
+from gfa_core.extension_stage_lightweight.api import create_lightweight_extension_router
+
+app.include_router(create_lightweight_extension_router())
 # MainAgent runtime state.  Analysis planning and execution remain owned by
 # the original IntentAgent/PlanningAgent/frontend flow below.
 llm_manager = None
@@ -4115,11 +4207,15 @@ async def link_agent_conversation_to_job(
     store = globals().get("agent_conversation_store")
     if store is None:
         raise HTTPException(status_code=503, detail="会话存储尚未初始化")
-    store.rebind_job(
+    conversation_id = store.rebind_job(
         session_id=request.conversation_id,
         job_id=request.job_id,
     )
-    return {"success": True, "message": "会话已关联 Working Directory"}
+    return {
+        "success": True,
+        "conversation_id": conversation_id,
+        "message": "会话已关联 Working Directory",
+    }
 
 
 
@@ -6014,6 +6110,13 @@ def _api_semantic_preflight(job_id: str, stage: str, prefix: str, params: Dict[s
             decisions[decision_key] = decision.to_dict() if decision else None
 
             if decision and decision.resolved:
+                if (
+                    need.role == "tree"
+                    and decision.selected
+                    and decision.selected.path
+                    and not str(params.get("treeFile") or "").strip()
+                ):
+                    materialized_params["treeFile"] = decision.selected.path
                 if (
                     stage == "wgs_index"
                     and need.role == "reference_fasta"
@@ -12598,7 +12701,7 @@ def _get_celery_overview() -> Dict[str, Any]:
 
         resource = snapshot(include_terminal=False)
         overview["resource_usage"] = resource.get("usage")
-        overview["resource_tasks"] = resource.get("tasks", [])[:20]
+        overview["resource_tasks"] = resource.get("tasks", [])
     except Exception as exc:
         overview["errors"].append(f"Resource governor snapshot failed: {exc}")
     overview["thresholds"] = {
@@ -13925,13 +14028,6 @@ async def get_results(
     def _add_manifest_result_group(manifest_file: Path, manifest: dict):
         if "combo_panel_test" in manifest_file.name.lower():
             return
-        if _is_subfamily_intermediate_manifest(manifest_file, manifest):
-            # These manifests are intermediate evidence generated inside the
-            # reference_classification branch. Final combo/circular tree/MSA
-            # artifacts are exposed under 2.5 亚家族确认 instead.
-            _remember_hidden_manifest_artifacts(manifest_file, manifest)
-            hidden_intermediate_artifact_names.add(manifest_file.name)
-            return
         group_name = (
             manifest.get("result_group")
             or (manifest.get("parameters") or {}).get("result_group")
@@ -14206,6 +14302,12 @@ async def get_results(
             except Exception:
                 pass
 
+    # Results are a persisted job view. Apply manifests by execution time so
+    # the latest attempt determines the visible stage status.
+    manifest_payloads.sort(
+        key=lambda item: (item[0].stat().st_mtime, item[0].name)
+    )
+
     # A refreshed GWAS format result request may not carry the genotype scope.
     # Rehydrate it only when the requested prefix (if any) identifies exactly
     # one successful scientific scope; otherwise remain fail-closed.
@@ -16729,6 +16831,7 @@ async def _run_agent_chat(
             {
                 "taskType": task_type,
                 "message": outcome_message,
+                "ui_action": outcome.get("ui_action"),
                 "job_id": request.job_id,
                 "workspace": (
                     str(PROJECT_ROOT / "workspace" / request.job_id)
@@ -17904,7 +18007,7 @@ def _build_contextual_gene_family_plan_response(request: Any, session_id: str, c
             # Subfamily review happens after reference_classification.
             if "identify" in stage_ids:
                 detail["dependencies"] = ["identify"]
-            if contextual_request.get("scopeMode") != "target_only" and contextual_request.get("context_route") in {"custom_phylogeny_scope", "plain_phylogeny"}:
+            if not needs_subfamily_evidence_chain and contextual_request.get("scopeMode") != "target_only" and contextual_request.get("context_route") in {"custom_phylogeny_scope", "plain_phylogeny"}:
                 detail_params["analysisRoute"] = "custom_phylogeny"
         detail["params"] = enrich_stage_params_with_context(stage_id, plan_prefix, detail_params)
         stages_detail.append(detail)
@@ -19652,8 +19755,12 @@ async def agent_plan(request: AgentPlanRequest):
                 request.message or "",
                 subfamily=True,
             )
-            explicit_species_for_subfamily = _extract_species_codes_from_text_for_job(request.job_id, request.message or "")
-            targets_for_subfamily = explicit_species_for_subfamily or _target_species_fallback_from_prefix(requested_prefix_for_subfamily)
+            request_roles_for_subfamily = _resolve_subfamily_request_species_roles(
+                request.job_id,
+                request.message or "",
+                request.intent,
+            )
+            targets_for_subfamily = request_roles_for_subfamily["classification_species"] or _target_species_fallback_from_prefix(requested_prefix_for_subfamily)
             if not targets_for_subfamily and prefix_species and prefix_species not in {"Target", "Multi"}:
                 targets_for_subfamily = [prefix_species]
             scope_defaults_for_subfamily = _latest_gene_family_scope_defaults(request.job_id, family_for_subfamily, requested_prefix_for_subfamily)
@@ -19675,7 +19782,7 @@ async def agent_plan(request: AgentPlanRequest):
                         *(scope_defaults_for_subfamily.get("target_species") or []),
                         *(scope_defaults_for_subfamily.get("comparative_species") or []),
                     ])) or targets_for_subfamily
-            refs_for_subfamily = scope_defaults_for_subfamily.get("reference_species") or [
+            refs_for_subfamily = request_roles_for_subfamily["reference_species"] or scope_defaults_for_subfamily.get("reference_species") or [
                 item.get("species")
                 for item in ((identify_selection_for_subfamily.get("groups") or {}).get("reference") or [])
                 if item.get("species")
@@ -19828,6 +19935,8 @@ async def agent_plan(request: AgentPlanRequest):
             request.job_id,
             request.message,
             request.prefix,
+            requested_stages=list((request.intent or {}).get("stages") or []),
+            request_intent=request.intent,
         )
         if contextual_request_pre_mas and not subfamily_prediction_query_for_context and not subfamily_confirm_query_for_context:
             response = _build_contextual_gene_family_plan_response(request, session_id, contextual_request_pre_mas)
@@ -19978,12 +20087,16 @@ async def agent_plan(request: AgentPlanRequest):
                 and not _requires_confirmed_subfamily_query(query_lower_early)
             )
             if subfamily_prediction_query_early:
-                explicit_species = _extract_species_codes_from_text_for_job(request.job_id, request.message or "")
+                request_roles_for_subfamily = _resolve_subfamily_request_species_roles(
+                    request.job_id,
+                    request.message or "",
+                    incoming_intent,
+                )
                 current_targets = _canonicalize_species_codes_for_job(
                     request.job_id,
                     _param_list(incoming_params.get("targetSpecies")) or _param_list(incoming_intent.get("target_species")),
                 )
-                target_species_for_subfamily = explicit_species or current_targets
+                target_species_for_subfamily = request_roles_for_subfamily["classification_species"] or current_targets
                 family_for_subfamily = _resolve_authoritative_gene_family(
                     request.job_id,
                     incoming_params.get("geneFamily") or incoming_intent.get("gene_family"),
@@ -19996,7 +20109,7 @@ async def agent_plan(request: AgentPlanRequest):
                 if not target_species_for_subfamily:
                     target_species_for_subfamily = scope_defaults_for_subfamily.get("target_species") or _target_species_fallback_from_prefix(effective_plan_prefix or requested_prefix)
                 identify_selection_for_subfamily = _load_identify_species_selection(request.job_id) if request.job_id else {}
-                reference_defaults_for_subfamily = _primary_reference_species_from_scope(request.job_id, family_for_subfamily, effective_plan_prefix or requested_prefix)
+                reference_defaults_for_subfamily = request_roles_for_subfamily["reference_species"] or _primary_reference_species_from_scope(request.job_id, family_for_subfamily, effective_plan_prefix or requested_prefix)
                 if not reference_defaults_for_subfamily:
                     reference_defaults_for_subfamily = scope_defaults_for_subfamily.get("reference_species") or []
                 if not reference_defaults_for_subfamily:
@@ -20014,8 +20127,8 @@ async def agent_plan(request: AgentPlanRequest):
                     incoming_intent["reference_species"] = reference_defaults_for_subfamily
                     incoming_params["scopeMode"] = "target_plus_reference"
                     incoming_intent["scopeMode"] = "target_plus_reference"
-                incoming_params["comparativeSpecies"] = []
-                incoming_intent["comparative_species"] = []
+                incoming_params["comparativeSpecies"] = request_roles_for_subfamily["comparative_species"]
+                incoming_intent["comparative_species"] = request_roles_for_subfamily["comparative_species"]
                 incoming_params["geneFamily"] = family_for_subfamily
                 incoming_intent["gene_family"] = family_for_subfamily
                 if target_species_for_subfamily and family_for_subfamily:
@@ -20036,14 +20149,19 @@ async def agent_plan(request: AgentPlanRequest):
                     request.message or "",
                     subfamily=True,
                 )
-                targets_for_subfamily = _canonicalize_species_codes_for_job(
+                request_roles_for_subfamily = _resolve_subfamily_request_species_roles(
                     request.job_id,
-                    _param_list(incoming_params.get("targetSpecies")) or _param_list(incoming_intent.get("target_species")) or _extract_species_codes_from_text_for_job(request.job_id, request.message or ""),
+                    request.message or "",
+                    incoming_intent,
+                )
+                targets_for_subfamily = request_roles_for_subfamily["classification_species"] or _canonicalize_species_codes_for_job(
+                    request.job_id,
+                    _param_list(incoming_params.get("targetSpecies")) or _param_list(incoming_intent.get("target_species")),
                 )
                 scope_defaults_for_subfamily = _latest_gene_family_scope_defaults(request.job_id, family_for_subfamily, effective_plan_prefix or requested_prefix)
                 if not targets_for_subfamily:
                     targets_for_subfamily = scope_defaults_for_subfamily.get("target_species") or _target_species_fallback_from_prefix(effective_plan_prefix or requested_prefix)
-                refs_for_subfamily = _canonicalize_species_codes_for_job(
+                refs_for_subfamily = request_roles_for_subfamily["reference_species"] or _canonicalize_species_codes_for_job(
                     request.job_id,
                     _param_list(incoming_params.get("referenceSpecies")) or _param_list(incoming_intent.get("reference_species")) or scope_defaults_for_subfamily.get("reference_species"),
                 )
@@ -20246,7 +20364,13 @@ async def agent_plan(request: AgentPlanRequest):
                 print(f"[Agent Plan] Deterministic subfamily intent plan: targets={targets_for_subfamily}, refs={refs_for_subfamily}, stages={deterministic_stages}")
                 return response
 
-            contextual_request_early = _resolve_contextual_gene_family_request(request.job_id, request.message, request.prefix)
+            contextual_request_early = _resolve_contextual_gene_family_request(
+                request.job_id,
+                request.message,
+                request.prefix,
+                requested_stages=list(incoming_intent.get("stages") or []),
+                request_intent=incoming_intent,
+            )
             if contextual_request_early and not subfamily_prediction_query_early and not subfamily_confirm_query_early:
                 response = _build_contextual_gene_family_plan_response(request, session_id, contextual_request_early)
                 plan_for_log = response.get('plan') or {}
@@ -20939,7 +21063,13 @@ async def agent_plan(request: AgentPlanRequest):
                 for key in ("targetSpecies", "referenceSpecies", "comparativeSpecies", "scopeMode", "geneFamily"):
                     if scope_params.get(key):
                         plan_params[key] = scope_params[key]
-                contextual_request = _resolve_contextual_gene_family_request(request.job_id, request.message, request.prefix)
+                contextual_request = _resolve_contextual_gene_family_request(
+                    request.job_id,
+                    request.message,
+                    request.prefix,
+                    requested_stages=list(intent.get("stages") or []),
+                    request_intent=intent,
+                )
                 if contextual_request and not subfamily_prediction_query and not subfamily_confirm_query:
                     stage_ids = list(contextual_request.get("stages") or [])
                     raw_stages = stage_ids
diff --git a/celery_app.py b/celery_app.py
index cbd6fc412..3f05d5d24 100755
--- a/celery_app.py
+++ b/celery_app.py
@@ -61,6 +61,10 @@ app.conf.update(
     task_annotations={
         "tasks.execute_agent_task": {"time_limit": 3600, "soft_time_limit": 3300},
         "tasks.execute_single_stage_task": {"time_limit": 172800, "soft_time_limit": 169200},
+        "tasks.execute_lightweight_extension_operation": {
+            "time_limit": None,
+            "soft_time_limit": None,
+        },
     },
     worker_prefetch_multiplier=1,
 )
diff --git a/gfa_core/extension_stage/raw_package_normalizer.py b/gfa_core/extension_stage/raw_package_normalizer.py
new file mode 100644
index 000000000..b06dd8bed
--- /dev/null
+++ b/gfa_core/extension_stage/raw_package_normalizer.py
@@ -0,0 +1,182 @@
+"""Normalize uploaded runnable code into one concrete extension entry command."""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+
+SHELL_SUFFIXES = {".sh", ".bash", ".command"}
+PYTHON_SUFFIXES = {".py"}
+R_SUFFIXES = {".r"}
+
+
+def normalize_raw_package(
+    *,
+    explicit_command: str,
+    raw_code: Path,
+    raw_data: Path,
+    saved_code: list[Path],
+) -> dict[str, Any]:
+    """Return a deterministic entry command record for an uploaded raw package."""
+    raw_code = Path(raw_code)
+    raw_data = Path(raw_data)
+    explicit_command = str(explicit_command or "").strip()
+    scripts = _script_inventory(saved_code, raw_code)
+
+    if explicit_command and not saved_code:
+        run_sh = raw_code / "run.sh"
+        run_sh.parent.mkdir(parents=True, exist_ok=True)
+        run_sh.write_text("#!/usr/bin/env bash\nset -euo pipefail\n\n" + explicit_command + "\n", encoding="utf-8")
+        run_sh.chmod(0o755)
+        return _record(
+            entry_command="bash run.sh",
+            entry_source="inline_command_wrapped",
+            entry_confidence="high",
+            requires_user_confirmation=False,
+            scripts=["run.sh"],
+            warnings=[],
+            raw_data=raw_data,
+        )
+
+    if explicit_command:
+        return _record(
+            entry_command=explicit_command,
+            entry_source="user_command",
+            entry_confidence="high",
+            requires_user_confirmation=False,
+            scripts=scripts,
+            warnings=[],
+            raw_data=raw_data,
+        )
+
+    shell_scripts = _scripts_by_suffix(saved_code, raw_code, SHELL_SUFFIXES)
+    if len(shell_scripts) == 1:
+        return _record(
+            entry_command=f"bash {shell_scripts[0]}",
+            entry_source="single_shell_script",
+            entry_confidence="high",
+            requires_user_confirmation=False,
+            scripts=scripts,
+            warnings=[],
+            raw_data=raw_data,
+        )
+    if len(shell_scripts) > 1:
+        ranked = _rank_shell_scripts(shell_scripts)
+        ambiguous = len(ranked) > 1 and _shell_rank_key(ranked[0]) == _shell_rank_key(ranked[1])
+        return _record(
+            entry_command=f"bash {ranked[0]}",
+            entry_source="ambiguous_shell_script" if ambiguous else "ranked_shell_script",
+            entry_confidence="low" if ambiguous else "medium",
+            requires_user_confirmation=ambiguous,
+            scripts=scripts,
+            warnings=["multiple shell entry candidates detected"] if ambiguous else [],
+            raw_data=raw_data,
+        )
+
+    python_scripts = _scripts_by_suffix(saved_code, raw_code, PYTHON_SUFFIXES)
+    if len(python_scripts) == 1:
+        return _record(
+            entry_command=f"python {python_scripts[0]}",
+            entry_source="single_python_script",
+            entry_confidence="medium",
+            requires_user_confirmation=False,
+            scripts=scripts,
+            warnings=["python script parameters may require confirmation"],
+            raw_data=raw_data,
+        )
+
+    r_scripts = _scripts_by_suffix(saved_code, raw_code, R_SUFFIXES)
+    if len(r_scripts) == 1:
+        return _record(
+            entry_command=f"Rscript {r_scripts[0]}",
+            entry_source="single_r_script",
+            entry_confidence="medium",
+            requires_user_confirmation=False,
+            scripts=scripts,
+            warnings=["R script parameters may require confirmation"],
+            raw_data=raw_data,
+        )
+
+    if saved_code:
+        first = sorted(saved_code, key=lambda p: p.relative_to(raw_code).as_posix().lower())[0]
+        rel = first.relative_to(raw_code).as_posix()
+        return _record(
+            entry_command=rel,
+            entry_source="fallback_code_file",
+            entry_confidence="low",
+            requires_user_confirmation=True,
+            scripts=scripts,
+            warnings=["could not identify a standard runnable entry script"],
+            raw_data=raw_data,
+        )
+
+    return _record(
+        entry_command="",
+        entry_source="missing_entry",
+        entry_confidence="none",
+        requires_user_confirmation=True,
+        scripts=[],
+        warnings=["no command or code file was provided"],
+        raw_data=raw_data,
+    )
+
+
+def _record(
+    *,
+    entry_command: str,
+    entry_source: str,
+    entry_confidence: str,
+    requires_user_confirmation: bool,
+    scripts: list[str],
+    warnings: list[str],
+    raw_data: Path,
+) -> dict[str, Any]:
+    return {
+        "schema_version": "raw_package_normalized_entry_v1",
+        "entry_command": entry_command,
+        "entry_source": entry_source,
+        "entry_confidence": entry_confidence,
+        "requires_user_confirmation": bool(requires_user_confirmation),
+        "detected_scripts": sorted(scripts),
+        "raw_test_data_files": sorted(p.relative_to(raw_data).as_posix() for p in raw_data.rglob("*") if p.is_file()),
+        "normalization_warnings": warnings,
+    }
+
+
+def _script_inventory(paths: list[Path], raw_code: Path) -> list[str]:
+    return [
+        path.relative_to(raw_code).as_posix()
+        for path in paths
+        if path.is_file() and path.suffix.lower() in SHELL_SUFFIXES | PYTHON_SUFFIXES | R_SUFFIXES
+    ]
+
+
+def _scripts_by_suffix(paths: list[Path], raw_code: Path, suffixes: set[str]) -> list[str]:
+    return sorted(
+        path.relative_to(raw_code).as_posix()
+        for path in paths
+        if path.is_file() and path.suffix.lower() in suffixes
+    )
+
+
+def _rank_shell_scripts(scripts: list[str]) -> list[str]:
+    return sorted(scripts, key=lambda name: (_shell_rank_key(name), name.lower()))
+
+
+def _shell_rank_key(name: str) -> int:
+    base = Path(name).name.lower()
+    stem = re.sub(r"\.(sh|bash|command)$", "", base)
+    if stem in {"run", "main"}:
+        return 0
+    if stem.startswith("run_") or stem.startswith("run-") or stem.startswith("run"):
+        return 1
+    if stem.endswith("_run") or stem.endswith("-run"):
+        return 2
+    if stem.startswith("main_") or stem.startswith("main-") or stem.startswith("main"):
+        return 3
+    if "install" in stem or "clean" in stem:
+        return 9
+    return 5
+
diff --git a/gfa_core/extension_stage_lightweight/__init__.py b/gfa_core/extension_stage_lightweight/__init__.py
new file mode 100644
index 000000000..b41293154
--- /dev/null
+++ b/gfa_core/extension_stage_lightweight/__init__.py
@@ -0,0 +1,20 @@
+"""Deterministic lightweight converter for already-runnable analysis packages."""
+
+from .evidence import run_raw_baseline, stage_package
+from .runtime_binding import (
+    RuntimeBindingError,
+    build_runtime_binding_contract,
+    render_runtime_package,
+    replay_runtime_binding,
+    resolve_runtime_bindings,
+)
+
+__all__ = [
+    "RuntimeBindingError",
+    "build_runtime_binding_contract",
+    "render_runtime_package",
+    "replay_runtime_binding",
+    "resolve_runtime_bindings",
+    "run_raw_baseline",
+    "stage_package",
+]
diff --git a/gfa_core/extension_stage_lightweight/api.py b/gfa_core/extension_stage_lightweight/api.py
new file mode 100644
index 000000000..09e5927c4
--- /dev/null
+++ b/gfa_core/extension_stage_lightweight/api.py
@@ -0,0 +1,739 @@
+"""Thin asynchronous HTTP boundary for the lightweight extension service."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from dataclasses import dataclass
+import fcntl
+import json
+import os
+from pathlib import Path
+import shutil
+import tempfile
+from typing import Any, Callable
+from uuid import uuid4
+
+from fastapi import APIRouter, File, Form, HTTPException, UploadFile
+from fastapi.responses import FileResponse
+from pydantic import BaseModel, Field
+
+from gfa_core.extension_stage.raw_package_normalizer import normalize_raw_package
+
+from .service import LightweightExtensionService
+
+
+UPLOAD_CHUNK_BYTES = 1024 * 1024
+
+
+def _safe_component(value: str, *, name: str) -> str:
+    value = str(value or "").strip()
+    if not value or value in {".", ".."} or "/" in value or "\\" in value:
+        raise ValueError(f"{name} must be one safe path component")
+    return value
+
+
+def _relative_path(value: str) -> Path:
+    path = Path(value or "")
+    if (
+        not value
+        or "\\" in value
+        or path.is_absolute()
+        or any(part in {"", ".", ".."} for part in path.parts)
+    ):
+        raise ValueError("uploaded filename must be a safe relative path")
+    return path
+
+
+async def _copy_upload_file(upload: UploadFile, destination: Path) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    with destination.open("wb") as handle:
+        while chunk := await upload.read(UPLOAD_CHUNK_BYTES):
+            handle.write(chunk)
+
+
+def _server_data_files(value: str | None) -> list[tuple[Path, Path]]:
+    files: list[tuple[Path, Path]] = []
+    for raw in (value or "").splitlines():
+        text = raw.strip()
+        if not text:
+            continue
+        source = Path(text).expanduser()
+        if not source.is_absolute():
+            raise ValueError(f"测试数据路径必须是绝对路径：{text}")
+        if not source.exists():
+            raise ValueError(f"测试数据路径不存在：{text}")
+        if source.is_file():
+            files.append((Path(source.name), source.resolve()))
+            continue
+        if not source.is_dir():
+            raise ValueError(f"测试数据路径不是普通文件或目录：{text}")
+        files.extend(
+            (item.relative_to(source), item.resolve())
+            for item in sorted(source.rglob("*"))
+            if item.is_file()
+        )
+    return files
+
+
+def _path_from_env(value: str, *, project_root: Path) -> Path:
+    path = Path(value).expanduser()
+    return path if path.is_absolute() else project_root / path
+
+
+@dataclass(frozen=True)
+class LightweightApiSettings:
+    project_root: Path
+    store_root: Path
+    input_root: Path
+    workspace_root: Path
+
+    @classmethod
+    def from_environment(
+        cls, *, environ: dict[str, str] | None = None, project_root: Path | None = None
+    ) -> "LightweightApiSettings":
+        env = os.environ if environ is None else environ
+        default_root = Path(__file__).resolve().parents[2]
+        root_value = str(
+            env.get("BBAV5_PROJECT_ROOT") or env.get("PROJECT_ROOT") or project_root or default_root
+        )
+        root = _path_from_env(root_value, project_root=default_root).resolve()
+        return cls(
+            project_root=root,
+            store_root=_path_from_env(
+                str(env.get("BBAV5_LIGHTWEIGHT_EXTENSION_STORE") or "extension_stages_lightweight"),
+                project_root=root,
+            ),
+            input_root=_path_from_env(
+                str(env.get("BBAV5_LIGHTWEIGHT_INPUT") or "input"), project_root=root
+            ),
+            workspace_root=_path_from_env(
+                str(env.get("BBAV5_LIGHTWEIGHT_WORKSPACE") or "workspace"), project_root=root
+            ),
+        )
+
+
+def _runtime_input_path(
+    settings: LightweightApiSettings, run_job_id: str, value: str
+) -> Path:
+    path = Path(value).expanduser()
+    if path.is_absolute():
+        return path
+    parts = path.parts
+    if len(parts) >= 3 and parts[1] == run_job_id:
+        if parts[0] == "input":
+            return settings.input_root / run_job_id / Path(*parts[2:])
+        if parts[0] == "workspace":
+            return settings.workspace_root / run_job_id / Path(*parts[2:])
+    return path
+
+
+class _TokenRequest(BaseModel):
+    operation_token: str
+
+
+class _ReviseRequest(_TokenRequest):
+    feedback: str
+    revision_target: str
+
+
+class _RunRequest(_TokenRequest):
+    run_job_id: str
+    input_overrides: dict[str, str] = Field(default_factory=dict)
+    parameter_overrides: dict[str, Any] = Field(default_factory=dict)
+    explicit_prefix: str | None = None
+
+
+class _IntentRequest(BaseModel):
+    extension_id: str | None = None
+    message: str = ""
+
+
+def _receipt_path(settings: LightweightApiSettings, token: str) -> Path:
+    return settings.store_root / "operations" / f"{_safe_component(token, name='operation_token')}.json"
+
+
+def _read_json(path: Path) -> dict[str, Any] | None:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None
+
+
+@contextmanager
+def _token_lock(settings: LightweightApiSettings, token: str):
+    token = _safe_component(token, name="operation_token")
+    lock_path = settings.store_root / "operations" / ".locks" / f"{token}.lock"
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with lock_path.open("a+") as handle:
+        fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+
+def _write_json(path: Path, payload: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.NamedTemporaryFile(
+        mode="w", encoding="utf-8", dir=path.parent, prefix=".operation-", delete=False
+    ) as handle:
+        json.dump(payload, handle, ensure_ascii=False, indent=2, sort_keys=True)
+        handle.write("\n")
+        temporary = Path(handle.name)
+    temporary.replace(path)
+
+
+def _reserve_operation_locked(
+    settings: LightweightApiSettings, *, extension_id: str, action: str, token: str
+) -> tuple[dict[str, Any], bool]:
+    path = _receipt_path(settings, token)
+    existing = _read_json(path)
+    if existing is not None:
+        if existing.get("extension_id") != extension_id or existing.get("action") != action:
+            raise ValueError("operation_token is already bound to another action")
+        return existing, False
+    receipt = _queued_receipt(extension_id=extension_id, action=action, token=token)
+    _write_json(path, receipt)
+    return receipt, True
+
+
+def _queued_receipt(*, extension_id: str, action: str, token: str) -> dict[str, Any]:
+    return {
+        "operation_id": token,
+        "operation_token": token,
+        "extension_id": extension_id,
+        "action": action,
+        "state": "queued",
+        "status": "queued",
+    }
+
+
+def _reserve_operation(
+    settings: LightweightApiSettings, *, extension_id: str, action: str, token: str
+) -> tuple[dict[str, Any], bool]:
+    with _token_lock(settings, token):
+        return _reserve_operation_locked(
+            settings, extension_id=extension_id, action=action, token=token
+        )
+
+
+def _set_receipt_locked(
+    settings: LightweightApiSettings, token: str, **changes: Any
+) -> dict[str, Any]:
+    path = _receipt_path(settings, token)
+    receipt = _read_json(path)
+    if receipt is None:
+        raise ValueError("operation does not exist")
+    receipt.update(changes)
+    _write_json(path, receipt)
+    return receipt
+
+
+def _set_receipt(settings: LightweightApiSettings, token: str, **changes: Any) -> dict[str, Any]:
+    with _token_lock(settings, token):
+        return _set_receipt_locked(settings, token, **changes)
+
+
+def _service_for(settings: LightweightApiSettings) -> LightweightExtensionService:
+    return LightweightExtensionService(settings.store_root)
+
+
+def _logs_for(record: dict[str, Any], token: str) -> list[str]:
+    operation = (record.get("operations") or {}).get(token) or {}
+    run_id = operation.get("run_id")
+    baseline_action = str(operation.get("action") or "") in {"upload", "rebuild"}
+    candidates: list[dict[str, Any]] = []
+    baseline = record.get("baseline")
+    if (
+        baseline_action
+        and isinstance(baseline, dict)
+        and Path(str(baseline.get("run_dir") or "")).name == run_id
+    ):
+        candidates.append(baseline)
+    else:
+        candidates.extend(item for item in record.get("validation_runs", []) if isinstance(item, dict))
+        candidates.extend(item for item in record.get("runtime_runs", []) if isinstance(item, dict))
+    logs: set[str] = set()
+    for item in candidates:
+        if run_id and not baseline_action and item.get("run_id") != run_id:
+            continue
+        for value in (item.get("logs") or {}).values():
+            if value:
+                logs.add(str(value))
+    return sorted(logs)
+
+
+def _operation_run(record: dict[str, Any], operation: dict[str, Any]) -> tuple[dict[str, Any] | None, str]:
+    run_id = operation.get("run_id") or (operation.get("response") or {}).get("run_id")
+    action = str(operation.get("action") or "")
+    if action in {"upload", "rebuild"}:
+        baseline = record.get("baseline")
+        if not isinstance(baseline, dict) or Path(str(baseline.get("run_dir") or "")).name != run_id:
+            return None, "baseline"
+        return baseline, "baseline"
+    collection_name = "runtime_runs" if action == "run" else "validation_runs"
+    for run in record.get(collection_name, []):
+        if isinstance(run, dict) and run.get("run_id") == run_id:
+            return run, "runtime" if action == "run" else "validation"
+    return None, "runtime" if action == "run" else "validation"
+
+
+def _run_error(record: dict[str, Any], token: str, run: dict[str, Any], phase: str) -> dict[str, Any]:
+    details = run.get("error") if isinstance(run.get("error"), dict) else {}
+    binding = run.get("binding") if isinstance(run.get("binding"), dict) else {}
+    binding_error = binding.get("error") if isinstance(binding.get("error"), dict) else {}
+    message = (
+        details.get("message")
+        or binding_error.get("message")
+        or ("runtime binding was not resolved" if binding.get("status") != "resolved" else "execution did not satisfy the output contract")
+    )
+    return _error(str(details.get("phase") or phase), message, logs=_logs_for(record, token))
+
+
+def _current_operation_error(
+    service: LightweightExtensionService, *, extension_id: str, token: str, result: dict[str, Any]
+) -> dict[str, Any] | None:
+    record = service.get(extension_id)
+    operation = (record.get("operations") or {}).get(token)
+    error = record.get("error")
+    if not isinstance(operation, dict) or not isinstance(error, dict):
+        return None
+    operation_status = (operation.get("response") or {}).get("status") or record.get("status")
+    if operation_status != result.get("status"):
+        return None
+    return _error(
+        str(error.get("phase") or operation.get("action") or "operation"),
+        str(error.get("message") or "operation failed"),
+        logs=_logs_for(record, token),
+    )
+
+
+def _operation_view(
+    settings: LightweightApiSettings, *, token: str, service_factory: Callable[[LightweightApiSettings], LightweightExtensionService]
+) -> dict[str, Any]:
+    receipt = _read_json(_receipt_path(settings, token))
+    if receipt is None:
+        raise ValueError("operation does not exist")
+    result = dict(receipt)
+    try:
+        record = service_factory(settings).get(str(receipt["extension_id"]))
+    except ValueError:
+        return result
+    operation = (record.get("operations") or {}).get(token)
+    if isinstance(operation, dict):
+        result.update(operation.get("response") or {})
+        result["state"] = operation.get("state", result.get("state"))
+        result["status"] = (
+            (operation.get("response") or {}).get("status")
+            or record.get("status")
+            or result.get("status")
+        )
+        result["extension_status"] = record.get("status")
+        run, phase = _operation_run(record, operation)
+        if isinstance(run, dict) and (
+            run.get("success") is False or run.get("contract_passed") is False
+        ):
+            result["outcome"] = "failed"
+            result["error"] = _run_error(record, token, run, phase)
+            result["logs"] = result["error"]["logs"]
+        elif isinstance(run, dict):
+            result["outcome"] = "succeeded"
+        elif result.get("error"):
+            result["outcome"] = "failed"
+            result["logs"] = list((result.get("error") or {}).get("logs") or [])
+        elif operation.get("action") not in {"upload", "rebuild"} and record.get("error"):
+            result["outcome"] = "failed"
+            result["error"] = record["error"]
+            result["logs"] = _logs_for(record, token)
+    return result
+
+
+def _error(phase: str, exc: BaseException | str, *, logs: list[str] | None = None) -> dict[str, Any]:
+    return {"phase": phase, "message": str(exc), "logs": logs or []}
+
+
+def _http_error(status_code: int, phase: str, exc: BaseException | str) -> HTTPException:
+    return HTTPException(status_code=status_code, detail=_error(phase, exc))
+
+
+def execute_queued_operation(payload: dict[str, Any]) -> dict[str, Any]:
+    """Worker entrypoint. It intentionally owns no Celery configuration."""
+
+    settings = LightweightApiSettings.from_environment()
+    action = str(payload["action"])
+    extension_id = _safe_component(str(payload["extension_id"]), name="extension_id")
+    token = _safe_component(str(payload["operation_token"]), name="operation_token")
+    _set_receipt(settings, token, state="running", status="running")
+    service = _service_for(settings)
+    try:
+        if action == "upload":
+            stage = settings.store_root / "staging" / token
+            result = service.upload(
+                extension_id=extension_id,
+                raw_code=stage / "raw_code",
+                raw_data=stage / "raw_test_data",
+                original_command=str(payload["original_command"]),
+                operation_token=token,
+            )
+        elif action == "rebuild":
+            result = service.rebuild(extension_id, operation_token=token)
+        elif action == "retry_semantic":
+            result = service.retry_semantic(extension_id, operation_token=token)
+        elif action == "revise":
+            result = service.revise(
+                extension_id,
+                feedback=str(payload["feedback"]),
+                revision_target=str(payload["revision_target"]),
+                operation_token=token,
+            )
+        elif action == "confirm":
+            result = service.confirm(extension_id, operation_token=token)
+        elif action == "validate":
+            result = service.validate(extension_id, operation_token=token)
+        elif action == "review":
+            result = service.review_result(extension_id, operation_token=token)
+        elif action == "publish":
+            result = service.publish(extension_id, operation_token=token)
+        elif action == "run":
+            result = service.run(
+                extension_id,
+                input_overrides={
+                    key: _runtime_input_path(settings, str(payload["run_job_id"]), value)
+                    for key, value in payload.get("input_overrides", {}).items()
+                },
+                run_job_id=str(payload["run_job_id"]),
+                input_root=settings.input_root,
+                workspace_root=settings.workspace_root,
+                parameter_overrides=payload.get("parameter_overrides") or {},
+                explicit_prefix=payload.get("explicit_prefix"),
+                operation_token=token,
+            )
+        else:
+            raise ValueError(f"unsupported lightweight operation: {action}")
+    except BaseException as exc:
+        receipt = _set_receipt(
+            settings, token, state="failed", status="failed", error=_error(action, exc)
+        )
+        return receipt
+    changes: dict[str, Any] = {
+        "state": "completed",
+        "status": result.get("status"),
+        "result": result,
+    }
+    try:
+        current_error = _current_operation_error(
+            service, extension_id=extension_id, token=token, result=result
+        )
+    except ValueError:
+        current_error = None
+    if current_error is not None:
+        changes["error"] = current_error
+    receipt = _set_receipt(settings, token, **changes)
+    return receipt
+
+
+def _default_enqueue(payload: dict[str, Any]) -> str:
+    from tasks import execute_lightweight_extension_operation
+
+    return str(execute_lightweight_extension_operation.apply_async(args=[payload]).id)
+
+
+def create_lightweight_extension_router(
+    *,
+    settings: LightweightApiSettings | None = None,
+    service_factory: Callable[[LightweightApiSettings], LightweightExtensionService] = _service_for,
+    enqueue: Callable[[dict[str, Any]], str] = _default_enqueue,
+) -> APIRouter:
+    settings = settings or LightweightApiSettings.from_environment()
+    router = APIRouter(prefix="/api/lightweight-extension-stages", tags=["lightweight-extension-stages"])
+
+    def submit(extension_id: str, action: str, token: str, **payload: Any) -> dict[str, Any]:
+        extension_id = _safe_component(extension_id, name="extension_id")
+        token = _safe_component(token, name="operation_token")
+        receipt, created = _reserve_operation(
+            settings, extension_id=extension_id, action=action, token=token
+        )
+        if created:
+            try:
+                celery_task_id = enqueue(
+                    {
+                        "extension_id": extension_id,
+                        "action": action,
+                        "operation_token": token,
+                        **payload,
+                    }
+                )
+            except BaseException as exc:
+                receipt = _set_receipt(
+                    settings, token, state="failed", status="failed", error=_error("queue", exc)
+                )
+            else:
+                receipt = _set_receipt(settings, token, celery_task_id=celery_task_id)
+        return receipt
+
+    @router.post("/upload", status_code=202)
+    async def upload(
+        extension_id: str = Form(...),
+        original_command: str | None = Form(None),
+        operation_token: str = Form(...),
+        raw_code_files: list[UploadFile] | None = File(None),
+        raw_data_files: list[UploadFile] | None = File(None),
+        raw_data_paths: str | None = Form(None),
+    ) -> dict[str, Any]:
+        temporary_stage: Path | None = None
+        try:
+            token = _safe_component(operation_token, name="operation_token")
+            safe_id = _safe_component(extension_id, name="extension_id")
+            staged_files = [
+                ("raw_code", _relative_path(item.filename or ""), item)
+                for item in (raw_code_files or [])
+            ] + [
+                ("raw_test_data", _relative_path(item.filename or ""), item)
+                for item in (raw_data_files or [])
+            ]
+            server_data_files = _server_data_files(raw_data_paths)
+            data_destinations = {
+                relative.as_posix()
+                for kind, relative, _item in staged_files
+                if kind == "raw_test_data"
+            }
+            for relative, _source in server_data_files:
+                key = relative.as_posix()
+                if key in data_destinations:
+                    raise ValueError(f"测试数据文件名冲突：{key}")
+                data_destinations.add(key)
+            if not data_destinations:
+                raise ValueError("请上传测试数据或填写测试数据服务器路径")
+            staging_root = settings.store_root / "staging"
+            staging_root.mkdir(parents=True, exist_ok=True)
+            temporary_stage = Path(
+                tempfile.mkdtemp(prefix=f".{token}-{uuid4().hex}-", dir=staging_root)
+            )
+            raw_code = temporary_stage / "raw_code"
+            raw_data = temporary_stage / "raw_test_data"
+            raw_code.mkdir()
+            raw_data.mkdir()
+            for kind, relative, item in staged_files:
+                destination = temporary_stage / kind / relative
+                await _copy_upload_file(item, destination)
+            for relative, source in server_data_files:
+                destination = raw_data / relative
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                destination.symlink_to(source)
+            normalized_entry = normalize_raw_package(
+                explicit_command=original_command or "",
+                raw_code=raw_code,
+                raw_data=raw_data,
+                saved_code=sorted(path for path in raw_code.rglob("*") if path.is_file()),
+            )
+            if normalized_entry["requires_user_confirmation"]:
+                warnings = "; ".join(normalized_entry["normalization_warnings"])
+                scripts = ", ".join(normalized_entry["detected_scripts"])
+                detail = warnings or "uploaded code has no unambiguous entry command"
+                if scripts:
+                    detail += f"; detected scripts: {scripts}"
+                raise ValueError(f"{detail}; provide original_command")
+            normalized_command = str(normalized_entry["entry_command"]).strip()
+            with _token_lock(settings, token):
+                existing = _read_json(_receipt_path(settings, token))
+                if existing is not None:
+                    if existing.get("extension_id") != safe_id or existing.get("action") != "upload":
+                        raise ValueError("operation_token is already bound to another action")
+                    receipt = existing
+                else:
+                    stage = staging_root / token
+                    if stage.exists():
+                        shutil.rmtree(stage)
+                    temporary_stage.replace(stage)
+                    temporary_stage = None
+                    receipt = _queued_receipt(extension_id=safe_id, action="upload", token=token)
+                    _write_json(_receipt_path(settings, token), receipt)
+                    try:
+                        celery_task_id = enqueue(
+                            {
+                                "extension_id": safe_id,
+                                "action": "upload",
+                                "operation_token": token,
+                                "original_command": normalized_command,
+                            }
+                        )
+                    except BaseException as exc:
+                        receipt = _set_receipt_locked(
+                            settings, token, state="failed", status="failed", error=_error("queue", exc)
+                        )
+                    else:
+                        receipt = _set_receipt_locked(settings, token, celery_task_id=celery_task_id)
+            return receipt
+        except ValueError as exc:
+            raise _http_error(400, "upload", exc) from exc
+        finally:
+            if temporary_stage is not None:
+                shutil.rmtree(temporary_stage, ignore_errors=True)
+
+    @router.get("/")
+    async def list_extensions() -> dict[str, Any]:
+        extensions: list[dict[str, str]] = []
+        for record_path in sorted((settings.store_root / "extensions").glob("*/extension.json")):
+            record = _read_json(record_path)
+            if isinstance(record, dict) and record.get("extension_id"):
+                extensions.append(
+                    {
+                        "extension_id": str(record["extension_id"]),
+                        "status": str(record.get("status") or ""),
+                    }
+                )
+        return {"extensions": extensions}
+
+    @router.post("/{extension_id}/rebuild", status_code=202)
+    async def rebuild(extension_id: str, req: _TokenRequest) -> dict[str, Any]:
+        return _submit_response(submit, extension_id, "rebuild", req.operation_token)
+
+    @router.post("/{extension_id}/retry-semantic", status_code=202)
+    async def retry_semantic(extension_id: str, req: _TokenRequest) -> dict[str, Any]:
+        return _submit_response(
+            submit, extension_id, "retry_semantic", req.operation_token
+        )
+
+    @router.post("/{extension_id}/revise", status_code=202)
+    async def revise(extension_id: str, req: _ReviseRequest) -> dict[str, Any]:
+        return _submit_response(
+            submit, extension_id, "revise", req.operation_token,
+            feedback=req.feedback, revision_target=req.revision_target,
+        )
+
+    @router.post("/{extension_id}/confirm", status_code=202)
+    async def confirm(extension_id: str, req: _TokenRequest) -> dict[str, Any]:
+        return _submit_response(submit, extension_id, "confirm", req.operation_token)
+
+    @router.post("/{extension_id}/validate", status_code=202)
+    async def validate(extension_id: str, req: _TokenRequest) -> dict[str, Any]:
+        return _submit_response(submit, extension_id, "validate", req.operation_token)
+
+    @router.post("/{extension_id}/review", status_code=202)
+    async def review(extension_id: str, req: _TokenRequest) -> dict[str, Any]:
+        return _submit_response(submit, extension_id, "review", req.operation_token)
+
+    @router.post("/{extension_id}/publish", status_code=202)
+    async def publish(extension_id: str, req: _TokenRequest) -> dict[str, Any]:
+        return _submit_response(submit, extension_id, "publish", req.operation_token)
+
+    @router.post("/{extension_id}/run", status_code=202)
+    async def run(extension_id: str, req: _RunRequest) -> dict[str, Any]:
+        return _submit_response(
+            submit, extension_id, "run", req.operation_token, run_job_id=req.run_job_id,
+            input_overrides=req.input_overrides, parameter_overrides=req.parameter_overrides,
+            explicit_prefix=req.explicit_prefix,
+        )
+
+    @router.get("/{extension_id}/help")
+    async def help(extension_id: str) -> dict[str, Any]:
+        try:
+            return service_factory(settings).help(_safe_component(extension_id, name="extension_id"))
+        except ValueError as exc:
+            raise _http_error(404, "help", exc) from exc
+
+    @router.post("/intent")
+    async def intent(req: _IntentRequest) -> dict[str, Any]:
+        if not req.extension_id:
+            return {
+                "intent": req.message,
+                "usage": "上传可执行代码、测试数据和原始命令，核对识别出的输入与参数；验证结果后授权发布。发布后可用自然语言指定已发布拓展分析、输入文件和原命令已有参数来运行，也可随时询问某个工具的帮助。",
+            }
+        try:
+            return {"intent": req.message, "help": service_factory(settings).help(req.extension_id)}
+        except ValueError as exc:
+            raise _http_error(404, "intent", exc) from exc
+
+    @router.get("/operations/{operation_token}")
+    async def operation(operation_token: str) -> dict[str, Any]:
+        try:
+            return _operation_view(settings, token=_safe_component(operation_token, name="operation_token"), service_factory=service_factory)
+        except ValueError as exc:
+            raise _http_error(404, "operation", exc) from exc
+
+    @router.post("/{extension_id}/operations/{operation_token}/stop")
+    async def stop(extension_id: str, operation_token: str) -> dict[str, Any]:
+        try:
+            result = service_factory(settings).stop(
+                _safe_component(extension_id, name="extension_id"),
+                operation_token=_safe_component(operation_token, name="operation_token"),
+            )
+            return result
+        except ValueError as exc:
+            raise _http_error(400, "stop", exc) from exc
+
+    @router.get("/{extension_id}/results")
+    async def results(extension_id: str) -> dict[str, Any]:
+        try:
+            record = service_factory(settings).get(_safe_component(extension_id, name="extension_id"))
+            return {
+                "extension_id": extension_id,
+                "validation_runs": record.get("validation_runs", []),
+                "runtime_runs": record.get("runtime_runs", []),
+            }
+        except ValueError as exc:
+            raise _http_error(404, "results", exc) from exc
+
+    @router.get("/{extension_id}/files")
+    async def result_file(extension_id: str, run_id: str, path: str):
+        try:
+            if _relative_path(path).as_posix() != path:
+                raise ValueError("path must be a safe relative output path")
+            safe_id = _safe_component(extension_id, name="extension_id")
+            safe_run = _safe_component(run_id, name="run_id")
+            record = service_factory(settings).get(safe_id)
+            run = next((item for item in record.get("validation_runs", []) if item.get("run_id") == safe_run), None)
+            kind = "validation"
+            if run is None:
+                run = next((item for item in record.get("runtime_runs", []) if item.get("run_id") == safe_run), None)
+                kind = "runtime"
+            if not isinstance(run, dict):
+                raise ValueError("run does not exist")
+            selected = next(
+                (item for item in (run.get("projection") or {}).get("files", []) if item.get("path") == path),
+                None,
+            )
+            if not isinstance(selected, dict):
+                raise ValueError("file is not a listed result output")
+            output = Path(str(selected.get("absolute_path") or "")).resolve()
+            if kind == "validation":
+                output_root = (
+                    settings.store_root / "extensions" / safe_id / "runs" / safe_run / "outputs"
+                ).resolve()
+            else:
+                relative = output.relative_to(settings.workspace_root.resolve())
+                if len(relative.parts) < 6:
+                    raise ValueError("runtime result file is outside its run output directory")
+                job_id, marker, found_id, found_run, outputs, *suffix = relative.parts
+                if (
+                    marker != "extension_runs"
+                    or found_id != safe_id
+                    or found_run != safe_run
+                    or outputs != "outputs"
+                    or not suffix
+                ):
+                    raise ValueError("runtime result file is outside its run output directory")
+                output_root = (
+                    settings.workspace_root
+                    / _safe_component(job_id, name="run_job_id")
+                    / marker
+                    / safe_id
+                    / safe_run
+                    / outputs
+                ).resolve()
+            if output != output_root / path or not output.is_file():
+                raise ValueError("result file does not exist")
+            return FileResponse(str(output), filename=output.name)
+        except ValueError as exc:
+            raise _http_error(400, "files", exc) from exc
+
+    return router
+
+
+def _submit_response(
+    submit: Callable[..., dict[str, Any]], extension_id: str, action: str, token: str, **payload: Any
+) -> dict[str, Any]:
+    try:
+        return submit(extension_id, action, token, **payload)
+    except ValueError as exc:
+        raise _http_error(400, action, exc) from exc
diff --git a/gfa_core/extension_stage_lightweight/command_model.py b/gfa_core/extension_stage_lightweight/command_model.py
new file mode 100644
index 000000000..36e729652
--- /dev/null
+++ b/gfa_core/extension_stage_lightweight/command_model.py
@@ -0,0 +1,454 @@
+"""Build a command model from tokens and observed execution files only."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import re
+import shlex
+from typing import Any
+
+
+_REDIRECTS = {">", ">>", "1>", "1>>", "2>", "2>>"}
+_CONTROL_TOKENS = _REDIRECTS | {"<", "<<", "|", "||", "&&", ";"}
+_SHELL_CONTROL_WORDS = {
+    "case",
+    "do",
+    "done",
+    "elif",
+    "else",
+    "esac",
+    "exit",
+    "fi",
+    "for",
+    "if",
+    "set",
+    "then",
+    "while",
+}
+
+
+def _normalise_path(value: str, work_dir: Path) -> str:
+    path = Path(value)
+    if path.is_absolute():
+        try:
+            return path.resolve().relative_to(work_dir.resolve()).as_posix()
+        except ValueError:
+            return path.as_posix()
+    normalised = path.as_posix()
+    while normalised.startswith("./"):
+        normalised = normalised[2:]
+    return normalised
+
+
+def _logical_shell_commands(text: str) -> list[str]:
+    commands: list[str] = []
+    pending = ""
+    for raw_line in text.splitlines():
+        stripped = raw_line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.endswith("\\"):
+            pending += stripped[:-1].rstrip() + " "
+            continue
+        logical = (pending + stripped).strip()
+        pending = ""
+        if logical:
+            commands.append(logical)
+    if pending.strip():
+        commands.append(pending.strip())
+    return commands
+
+
+def _split_shell_chain(command: str) -> list[str]:
+    segments: list[str] = []
+    buffer: list[str] = []
+    quote: str | None = None
+    escaped = False
+    i = 0
+    while i < len(command):
+        char = command[i]
+        if escaped:
+            buffer.append(char)
+            escaped = False
+            i += 1
+            continue
+        if char == "\\":
+            buffer.append(char)
+            escaped = True
+            i += 1
+            continue
+        if quote:
+            buffer.append(char)
+            if char == quote:
+                quote = None
+            i += 1
+            continue
+        if char in {"'", '"'}:
+            quote = char
+            buffer.append(char)
+            i += 1
+            continue
+        is_boundary = char == ";" or (
+            char in {"|", "&"}
+            and i + 1 < len(command)
+            and (char == "|" or command[i + 1] == char)
+        )
+        if is_boundary:
+            segment = "".join(buffer).strip()
+            if segment:
+                segments.append(segment)
+            buffer = []
+            if i + 1 < len(command) and command[i + 1] == char:
+                i += 1
+            i += 1
+            continue
+        buffer.append(char)
+        i += 1
+    segment = "".join(buffer).strip()
+    if segment:
+        segments.append(segment)
+    return segments or [command]
+
+
+def _substitute_shell_variables(command: str, variables: dict[str, str]) -> str:
+    result: list[str] = []
+    in_single_quote = False
+    i = 0
+    while i < len(command):
+        char = command[i]
+        if char == "'":
+            in_single_quote = not in_single_quote
+            result.append(char)
+            i += 1
+            continue
+        if char != "$" or in_single_quote:
+            result.append(char)
+            i += 1
+            continue
+        if i + 1 < len(command) and command[i + 1] == "{":
+            end = command.find("}", i + 2)
+            if end != -1:
+                key = command[i + 2 : end]
+                if key in variables:
+                    result.append(variables[key])
+                    i = end + 1
+                    continue
+        match = re.match(r"[A-Za-z_][A-Za-z0-9_]*|[0-9]+", command[i + 1 :])
+        if match:
+            key = match.group(0)
+            if key in variables:
+                result.append(variables[key])
+                i += len(key) + 1
+                continue
+        result.append(char)
+        i += 1
+    return "".join(result)
+
+
+def _prepare_script_commands(text: str, positional_args: list[str]) -> list[str]:
+    variables = {str(index): value for index, value in enumerate(positional_args, 1)}
+    commands: list[str] = []
+    for logical in _logical_shell_commands(text):
+        for segment in _split_shell_chain(logical):
+            expanded = _substitute_shell_variables(segment, variables)
+            assignment = re.fullmatch(r"([A-Za-z_][A-Za-z0-9_]*)=(.*)", expanded)
+            if assignment:
+                values = shlex.split(assignment.group(2))
+                variables[assignment.group(1)] = values[0] if values else ""
+                continue
+            try:
+                segment_tokens = shlex.split(expanded)
+            except ValueError:
+                commands.append(expanded)
+                continue
+            if not segment_tokens or segment_tokens[0] in _SHELL_CONTROL_WORDS:
+                continue
+            commands.append(expanded)
+    return commands
+
+
+def _entry_commands(
+    command: str, work_dir: Path, code_files: set[str]
+) -> tuple[list[str], list[str]]:
+    try:
+        tokens = shlex.split(command)
+    except ValueError:
+        return [command], []
+    for source_index, token in enumerate(tokens):
+        relative = _normalise_path(token, work_dir)
+        if relative not in code_files:
+            continue
+        path = work_dir / relative
+        if path.suffix in {".sh", ".bash"} or tokens[0] in {"bash", "sh"}:
+            script_commands = _prepare_script_commands(
+                path.read_text(encoding="utf-8", errors="replace"),
+                tokens[source_index + 1 :],
+            )
+            return script_commands, [relative]
+    return _split_shell_chain(command), []
+
+
+def _matching_outputs(value: str, outputs: set[str], work_dir: Path) -> list[str]:
+    relative = _normalise_path(value, work_dir)
+    if relative in outputs:
+        return [relative]
+    return sorted(
+        output for output in outputs if output.startswith(relative + ".")
+    )
+
+
+def _append_unique(items: list[dict[str, Any]], item: dict[str, Any]) -> None:
+    identity = (item.get("path"), item.get("flag"), item.get("token_index"))
+    if all(
+        (existing.get("path"), existing.get("flag"), existing.get("token_index"))
+        != identity
+        for existing in items
+    ):
+        items.append(item)
+
+
+def _outer_quoted_token_indexes(command: str, tokens: list[str]) -> set[int]:
+    """Return fully quoted token indexes when POSIX/non-POSIX splits align."""
+
+    try:
+        source_tokens = shlex.split(command, posix=False)
+    except ValueError:
+        return set()
+    if len(source_tokens) != len(tokens):
+        return set()
+    for source_token, token in zip(source_tokens, tokens):
+        try:
+            if shlex.split(source_token, posix=True) != [token]:
+                return set()
+        except ValueError:
+            return set()
+    return {
+        index
+        for index, source_token in enumerate(source_tokens)
+        if len(source_token) >= 2
+        and source_token[0] in {"'", '"'}
+        and source_token[-1] == source_token[0]
+    }
+
+
+def build_command_model(
+    *,
+    command: str,
+    work_dir: Path,
+    before_files: dict[str, dict[str, object]],
+    output_files: list[str],
+    code_files: list[str],
+) -> dict[str, Any]:
+    """Classify explicit tokens using baseline file evidence.
+
+    No executable name or biological file format is used to make the decision.
+    """
+
+    work_dir = Path(work_dir)
+    before = set(before_files)
+    outputs = set(output_files)
+    code = set(code_files)
+    commands, source_scripts = _entry_commands(command, work_dir, code)
+    models: list[dict[str, Any]] = []
+    assigned_outputs: set[str] = set()
+    produced_references: set[str] = set()
+
+    for index, logical_command in enumerate(commands, start=1):
+        try:
+            tokens = shlex.split(logical_command)
+        except ValueError as exc:
+            models.append(
+                {
+                    "index": index,
+                    "command": logical_command,
+                    "tool": None,
+                    "parse_error": str(exc),
+                    "source_files": [],
+                    "inputs": [],
+                    "arguments": [],
+                    "parameters": [],
+                    "outputs": [],
+                }
+            )
+            continue
+        if not tokens:
+            continue
+
+        model: dict[str, Any] = {
+            "index": index,
+            "command": logical_command,
+            "tool": tokens[0],
+            "source_files": [],
+            "inputs": [],
+            "arguments": [],
+            "parameters": [],
+            "outputs": [],
+        }
+        command_outputs: set[str] = set()
+        outer_quoted_indexes = _outer_quoted_token_indexes(logical_command, tokens)
+        ambiguous_positional_indexes: set[int] = set()
+        i = 1
+        positional_index = 0
+        while i < len(tokens):
+            token = tokens[i]
+            if token in _REDIRECTS and i + 1 < len(tokens):
+                value = _normalise_path(tokens[i + 1], work_dir)
+                matched = _matching_outputs(value, outputs, work_dir)
+                command_outputs.update(matched or ([value] if value in outputs else []))
+                produced_references.add(value)
+                i += 2
+                continue
+            if token in _CONTROL_TOKENS:
+                i += 1
+                continue
+
+            if token.startswith("-") and token != "-":
+                if (
+                    "=" not in token
+                    and i + 1 in outer_quoted_indexes
+                    and i + 2 < len(tokens)
+                ):
+                    candidate = _normalise_path(tokens[i + 1], work_dir)
+                    candidate_is_reference = (
+                        candidate in before
+                        or candidate in code
+                        or candidate in produced_references
+                        or bool(_matching_outputs(candidate, outputs, work_dir))
+                    )
+                    later_has_input_evidence = any(
+                        (
+                            _normalise_path(later, work_dir) in before
+                            and _normalise_path(later, work_dir) not in code
+                        )
+                        or _normalise_path(later, work_dir) in produced_references
+                        for later in tokens[i + 2 :]
+                    )
+                    if not candidate_is_reference and later_has_input_evidence:
+                        argument = {
+                            "kind": "switch",
+                            "flag": token,
+                            "value": token,
+                            "token_index": i,
+                            "grouping_confidence": "ambiguous",
+                        }
+                        model["arguments"].append(argument)
+                        model["parameters"].append(dict(argument))
+                        ambiguous_positional_indexes.add(i + 1)
+                        i += 1
+                        continue
+                if "=" in token:
+                    flag, raw_value = token.split("=", 1)
+                    value_index = i
+                elif i + 1 < len(tokens) and not tokens[i + 1].startswith("-") and tokens[i + 1] not in _CONTROL_TOKENS:
+                    flag, raw_value = token, tokens[i + 1]
+                    value_index = i + 1
+                else:
+                    argument = {
+                        "kind": "switch",
+                        "flag": token,
+                        "value": token,
+                        "token_index": i,
+                    }
+                    model["arguments"].append(argument)
+                    model["parameters"].append(dict(argument))
+                    i += 1
+                    continue
+
+                value = _normalise_path(raw_value, work_dir)
+                value_role = "value"
+                if value in before and value not in code:
+                    value_role = "input"
+                    _append_unique(
+                        model["inputs"],
+                        {
+                            "path": value,
+                            "source": "baseline_input",
+                            "flag": flag,
+                            "token_index": value_index,
+                        },
+                    )
+                elif value in produced_references:
+                    value_role = "input"
+                    _append_unique(
+                        model["inputs"],
+                        {
+                            "path": value,
+                            "source": "generated_input",
+                            "flag": flag,
+                            "token_index": value_index,
+                        },
+                    )
+                else:
+                    matched = _matching_outputs(value, outputs, work_dir)
+                    if matched:
+                        value_role = "output_reference"
+                        command_outputs.update(matched)
+                        produced_references.add(value)
+
+                argument = {
+                    "kind": "flag_value",
+                    "flag": flag,
+                    "value": raw_value,
+                    "token_index": i,
+                    "value_role": value_role,
+                }
+                model["arguments"].append(argument)
+                if value_role != "input":
+                    model["parameters"].append(dict(argument))
+                i += 1 if "=" in token else 2
+                continue
+
+            relative = _normalise_path(token, work_dir)
+            if relative in code:
+                if relative not in model["source_files"]:
+                    model["source_files"].append(relative)
+            elif relative in before:
+                _append_unique(
+                    model["inputs"],
+                    {
+                        "path": relative,
+                        "source": "baseline_input",
+                        "flag": None,
+                        "token_index": i,
+                    },
+                )
+            elif relative in produced_references:
+                _append_unique(
+                    model["inputs"],
+                    {
+                        "path": relative,
+                        "source": "generated_input",
+                        "flag": None,
+                        "token_index": i,
+                    },
+                )
+            else:
+                matched = _matching_outputs(relative, outputs, work_dir)
+                value_role = "output_reference" if matched else "value"
+                command_outputs.update(matched)
+                if matched:
+                    produced_references.add(relative)
+                parameter = {
+                    "kind": "positional",
+                    "flag": None,
+                    "value": token,
+                    "token_index": i,
+                    "position": positional_index,
+                    "value_role": value_role,
+                }
+                if i in ambiguous_positional_indexes:
+                    parameter["grouping_confidence"] = "ambiguous"
+                model["parameters"].append(parameter)
+                positional_index += 1
+            i += 1
+
+        model["outputs"] = sorted(command_outputs)
+        assigned_outputs.update(command_outputs)
+        models.append(model)
+
+    return {
+        "entry_command": command,
+        "source_scripts": source_scripts,
+        "commands": models,
+        "unmatched_outputs": sorted(outputs - assigned_outputs),
+    }
diff --git a/gfa_core/extension_stage_lightweight/confirmation.py b/gfa_core/extension_stage_lightweight/confirmation.py
new file mode 100644
index 000000000..325825fc0
--- /dev/null
+++ b/gfa_core/extension_stage_lightweight/confirmation.py
@@ -0,0 +1,181 @@
+"""Bind user confirmation to one locked fact set and semantic candidate."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+import hashlib
+import json
+from typing import Any
+
+from .semantic_model import SemanticCandidateError, validate_semantic_candidate
+
+
+SEMANTIC_REVISION_TARGETS = {
+    "semantic",
+    "function_summary",
+    "inputs.role",
+    "inputs.description",
+    "inputs.replaceability",
+    "parameters.display_name",
+    "parameters.description",
+    "outputs.description",
+    "outputs.result_role",
+}
+FACT_DISPUTE_TARGETS = {
+    "execution_facts.original_command",
+    "execution_facts.command",
+    "execution_facts.path",
+    "execution_facts.flag",
+    "execution_facts.value",
+    "execution_facts.default_value",
+    "execution_facts.observed_output",
+}
+
+
+def _sha256_json(value: Any) -> str:
+    encoded = json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _applied_revision_diff(
+    repair_history: list[dict[str, Any]] | None,
+) -> list[dict[str, Any]]:
+    return [
+        deepcopy(change)
+        for attempt in repair_history or []
+        if attempt.get("status") == "success"
+        for change in attempt.get("diff", [])
+    ]
+
+
+def create_confirmation(
+    *,
+    execution_facts: dict[str, Any],
+    candidate: dict[str, Any],
+    repair_history: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Create a pending decision bound to the current facts and candidate."""
+
+    errors = validate_semantic_candidate(execution_facts, candidate)
+    if errors:
+        raise SemanticCandidateError(errors)
+    facts_sha256 = execution_facts["facts_sha256"]
+    candidate_sha256 = _sha256_json(candidate)
+    binding_sha256 = _sha256_json(
+        {
+            "facts_sha256": facts_sha256,
+            "candidate_sha256": candidate_sha256,
+        }
+    )
+    return {
+        "confirmation_id": f"confirmation_{binding_sha256[:16]}",
+        "status": "pending",
+        "accepted": False,
+        "facts_sha256": facts_sha256,
+        "candidate_sha256": candidate_sha256,
+        "candidate_version": f"semantic_{candidate_sha256[:16]}",
+        "summary": {
+            "function_summary": candidate["function_summary"],
+            "input_count": len(candidate["inputs"]),
+            "parameter_count": len(candidate["parameters"]),
+            "output_count": len(candidate["outputs"]),
+            "revision_diff": _applied_revision_diff(repair_history),
+        },
+    }
+
+
+def _stale_reason(
+    *,
+    confirmation: dict[str, Any],
+    execution_facts: dict[str, Any],
+    candidate: dict[str, Any],
+) -> str | None:
+    if confirmation.get("facts_sha256") != execution_facts.get("facts_sha256"):
+        return "facts_changed"
+    if confirmation.get("candidate_sha256") != _sha256_json(candidate):
+        return "candidate_changed"
+    return None
+
+
+def apply_confirmation_action(
+    *,
+    confirmation: dict[str, Any],
+    action: str,
+    execution_facts: dict[str, Any],
+    candidate: dict[str, Any],
+    feedback: str | None = None,
+    revision_target: str | None = None,
+) -> dict[str, Any]:
+    """Apply one user decision without mutating the supplied confirmation."""
+
+    result = deepcopy(confirmation)
+    result["accepted"] = False
+    stale_reason = _stale_reason(
+        confirmation=confirmation,
+        execution_facts=execution_facts,
+        candidate=candidate,
+    )
+    if stale_reason:
+        result["status"] = "stale"
+        result["stale_reason"] = stale_reason
+        return result
+
+    if action == "confirm":
+        result["status"] = "confirmed"
+        result["accepted"] = True
+        return result
+    if action == "cancel":
+        result["status"] = "cancelled"
+        return result
+    if action != "revise":
+        raise ValueError(f"unknown confirmation action: {action}")
+
+    normalized_feedback = (feedback or "").strip()
+    if not normalized_feedback:
+        raise ValueError("revise requires non-empty feedback")
+    if revision_target in SEMANTIC_REVISION_TARGETS:
+        result.update(
+            {
+                "status": "revision_requested",
+                "route": "semantic_repair",
+                "feedback": normalized_feedback,
+                "revision_target": revision_target,
+            }
+        )
+        return result
+    if revision_target in FACT_DISPUTE_TARGETS:
+        result.update(
+            {
+                "status": "fact_dispute",
+                "route": "recollect_execution_evidence",
+                "feedback": normalized_feedback,
+                "revision_target": revision_target,
+            }
+        )
+        return result
+    raise ValueError(f"unknown revision target: {revision_target}")
+
+
+def is_candidate_accepted(
+    *,
+    confirmation: dict[str, Any],
+    execution_facts: dict[str, Any],
+    candidate: dict[str, Any],
+) -> bool:
+    """Return true only for a confirmed decision with an unchanged binding."""
+
+    return (
+        confirmation.get("status") == "confirmed"
+        and confirmation.get("accepted") is True
+        and _stale_reason(
+            confirmation=confirmation,
+            execution_facts=execution_facts,
+            candidate=candidate,
+        )
+        is None
+    )
diff --git a/gfa_core/extension_stage_lightweight/converter.py b/gfa_core/extension_stage_lightweight/converter.py
new file mode 100644
index 000000000..77ac916bc
--- /dev/null
+++ b/gfa_core/extension_stage_lightweight/converter.py
@@ -0,0 +1,207 @@
+"""Create and replay a minimal deterministic extension specification."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+import hashlib
+import json
+from pathlib import Path
+import shlex
+from typing import Any
+
+from .command_model import build_command_model
+from .evidence import run_raw_baseline
+
+
+def _output_files(evidence: dict[str, Any]) -> list[str]:
+    return sorted(
+        set(evidence["outputs"]["new_files"])
+        | set(evidence["outputs"]["modified_files"])
+    )
+
+
+def _fact_id(step_id: str, kind: str, item: dict[str, Any]) -> str:
+    token_index = item.get("token_index")
+    if not isinstance(token_index, int):
+        raise ValueError(f"{kind} fact is missing token_index in {step_id}")
+    return f"{step_id}:{kind}:{token_index:03d}"
+
+
+def _facts_sha256(facts: dict[str, Any]) -> str:
+    payload = json.dumps(
+        facts,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()
+
+
+def build_execution_facts(evidence: dict[str, Any]) -> dict[str, Any]:
+    """Build an immutable, ID-addressable view of observed execution facts."""
+
+    output_files = _output_files(evidence)
+    command_model = build_command_model(
+        command=evidence["command"],
+        work_dir=Path(evidence["work_dir"]),
+        before_files=evidence["before_files"],
+        output_files=output_files,
+        code_files=evidence["staged"]["code_files"],
+    )
+
+    code_files = list(evidence["staged"]["code_files"])
+    data_files = list(evidence["staged"]["data_files"])
+    inventory: dict[str, dict[str, Any]] = {}
+    for source, paths in (("raw_code", code_files), ("raw_test_data", data_files)):
+        for path in paths:
+            inventory[path] = {
+                **deepcopy(evidence["before_files"][path]),
+                "source": source,
+            }
+
+    commands = deepcopy(command_model["commands"])
+    producers: dict[str, list[str]] = {path: [] for path in output_files}
+    for command in commands:
+        step_id = f"step_{command['index']:03d}"
+        command["step_id"] = step_id
+        for item in command["inputs"]:
+            item["fact_id"] = _fact_id(step_id, "input", item)
+        for item in command["parameters"]:
+            item["fact_id"] = _fact_id(step_id, "parameter", item)
+        for path in command["outputs"]:
+            if path in producers:
+                producers[path].append(step_id)
+
+    file_facts = [
+        {
+            "fact_id": f"output:file:{index:03d}",
+            "path": path,
+            "producer_step_ids": producers[path],
+        }
+        for index, path in enumerate(output_files, start=1)
+    ]
+    output_ids = {item["path"]: item["fact_id"] for item in file_facts}
+    stdout = deepcopy(evidence["outputs"]["stdout"])
+    if stdout.get("present"):
+        stdout["fact_id"] = "output:stdout"
+
+    facts: dict[str, Any] = {
+        "original_command": evidence["command"],
+        "package": {
+            "code_files": code_files,
+            "data_files": data_files,
+            "inventory": inventory,
+        },
+        "source_scripts": list(command_model["source_scripts"]),
+        "commands": commands,
+        "outputs": {
+            "files": file_facts,
+            "stdout": stdout,
+        },
+        "unmatched_output_fact_ids": [
+            output_ids[path] for path in command_model["unmatched_outputs"]
+        ],
+        "baseline": {
+            "success": evidence["success"],
+            "returncode": evidence["returncode"],
+            "logs": deepcopy(evidence["logs"]),
+        },
+    }
+    facts["facts_sha256"] = _facts_sha256(facts)
+    return facts
+
+
+def build_spec(evidence: dict[str, Any]) -> dict[str, Any]:
+    output_files = _output_files(evidence)
+    command_model = build_command_model(
+        command=evidence["command"],
+        work_dir=Path(evidence["work_dir"]),
+        before_files=evidence["before_files"],
+        output_files=output_files,
+        code_files=evidence["staged"]["code_files"],
+    )
+    return {
+        "schema_version": "lightweight-extension/v1",
+        "original_command": evidence["command"],
+        "source_scripts": command_model["source_scripts"],
+        "commands": command_model["commands"],
+        "unmatched_outputs": command_model["unmatched_outputs"],
+        "outputs": {
+            "files": output_files,
+            "stdout": dict(evidence["outputs"]["stdout"]),
+        },
+        "baseline": {
+            "success": evidence["success"],
+            "returncode": evidence["returncode"],
+            "logs": dict(evidence["logs"]),
+        },
+    }
+
+
+def write_spec(spec: dict[str, Any], destination: Path) -> Path:
+    destination = Path(destination)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    destination.write_text(
+        json.dumps(spec, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return destination
+
+
+def write_wrapper(spec: dict[str, Any], destination: Path) -> Path:
+    destination = Path(destination)
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    quoted_command = shlex.quote(spec["original_command"])
+    destination.write_text(
+        "#!/usr/bin/env bash\nset -euo pipefail\nexec bash -c "
+        + quoted_command
+        + "\n",
+        encoding="utf-8",
+    )
+    destination.chmod(0o755)
+    return destination
+
+
+def _baseline_input_paths(spec: dict[str, Any]) -> set[str]:
+    return {
+        item["path"]
+        for command in spec["commands"]
+        for item in command["inputs"]
+        if item["source"] == "baseline_input"
+    }
+
+
+def replay(
+    *,
+    spec: dict[str, Any],
+    raw_code: Path,
+    raw_data: Path,
+    run_dir: Path,
+    input_overrides: dict[str, Path] | None = None,
+    env: dict[str, str] | None = None,
+) -> dict[str, Any]:
+    overrides = input_overrides or {}
+    unknown = sorted(set(overrides) - _baseline_input_paths(spec))
+    if unknown:
+        raise ValueError(f"Unknown input override: {', '.join(unknown)}")
+
+    evidence = run_raw_baseline(
+        command=spec["original_command"],
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=run_dir,
+        env=env,
+        input_overrides=overrides,
+    )
+    actual_files = set(evidence["outputs"]["new_files"]) | set(
+        evidence["outputs"]["modified_files"]
+    )
+    expected_files = set(spec["outputs"]["files"])
+    missing_outputs = sorted(expected_files - actual_files)
+    expected_stdout = bool(spec["outputs"]["stdout"]["present"])
+    stdout_ok = not expected_stdout or evidence["outputs"]["stdout"]["present"]
+    evidence["missing_outputs"] = missing_outputs
+    evidence["contract_passed"] = bool(
+        evidence["success"] and not missing_outputs and stdout_ok
+    )
+    return evidence
diff --git a/gfa_core/extension_stage_lightweight/deepseek_semantics.py b/gfa_core/extension_stage_lightweight/deepseek_semantics.py
new file mode 100644
index 000000000..0eaf843e2
--- /dev/null
+++ b/gfa_core/extension_stage_lightweight/deepseek_semantics.py
@@ -0,0 +1,397 @@
+"""Generate semantic-only candidates with an OpenAI-compatible DeepSeek API."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+import hashlib
+import json
+import os
+from pathlib import Path
+from typing import Any, Callable, Mapping
+
+from .semantic_model import bind_fact_derived_semantics, validate_semantic_candidate
+
+
+DEFAULT_BASE_URL = "https://api.deepseek.com"
+DEFAULT_MODEL = "deepseek-chat"
+MAX_FILE_BYTES = 32 * 1024
+MAX_TOTAL_BYTES = 128 * 1024
+
+SYSTEM_PROMPT = """You describe already-runnable bioinformatics code as a natural-language tool.
+Return one strict JSON object and no markdown. You must not return or modify execution facts,
+commands, paths, flags, values, observed outputs, or wrapper logic. Reference only fact_id values
+present in the supplied execution facts. Provide exactly one entry for every supplied input, parameter, and output fact_id, with no omissions, duplicates, or extras. Fill only function_summary and the allowed semantic fields.
+For result_role, final means a user-facing analysis result; intermediate means a temporary or
+supporting artifact used to produce or render another result; log means diagnostic execution output.
+Use unknown only when the supplied code and execution evidence cannot distinguish these roles.
+"""
+
+REPAIR_SYSTEM_PROMPT = """Return only a semantic patch as one strict JSON object and no markdown.
+Change only the supplied allowed_targets. Never return or modify commands, paths, flags, values,
+observed outputs, code, wrapper logic, or unknown fact_id values.
+"""
+
+
+@dataclass(frozen=True)
+class DeepSeekConfig:
+    env_file: Path
+    api_key: str
+    api_key_alias: str
+    base_url: str
+    model: str
+
+
+class DeepSeekSemanticError(RuntimeError):
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: str,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.code = code
+        self.metadata = deepcopy(metadata or {})
+
+
+def _read_env_file(path: Path) -> dict[str, str]:
+    values: dict[str, str] = {}
+    for raw_line in path.read_text(encoding="utf-8", errors="ignore").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].strip()
+        key, value = line.split("=", 1)
+        key = key.strip()
+        if key:
+            values[key] = value.strip().strip("\"'")
+    return values
+
+
+def load_deepseek_config(
+    environ: Mapping[str, str] | None = None,
+) -> DeepSeekConfig:
+    source = os.environ if environ is None else environ
+    configured_path = source.get("BBAV5_PROJECT_ENV_FILE", "").strip()
+    if not configured_path:
+        raise DeepSeekSemanticError(
+            "BBAV5_PROJECT_ENV_FILE is required for DeepSeek semantic conversion",
+            code="configuration_error",
+        )
+    env_file = Path(configured_path).expanduser().resolve()
+    if not env_file.is_file():
+        raise DeepSeekSemanticError(
+            f"Configured project environment file does not exist: {env_file}",
+            code="configuration_error",
+        )
+
+    values = _read_env_file(env_file)
+    api_key_alias = "NEW_API_KEY" if values.get("NEW_API_KEY", "").strip() else "DEEPSEEK_API_KEY"
+    api_key = values.get(api_key_alias, "").strip()
+    if not api_key:
+        raise DeepSeekSemanticError(
+            f"DeepSeek API key is missing from configured environment file: {env_file}",
+            code="configuration_error",
+        )
+    base_url = (
+        values.get("NEW_API_BASE_URL", "").strip()
+        or values.get("DEEPSEEK_BASE_URL", "").strip()
+        or DEFAULT_BASE_URL
+    )
+    model = (
+        values.get("NEW_API_MODEL", "").strip()
+        or values.get("DEEPSEEK_MODEL", "").strip()
+        or DEFAULT_MODEL
+    )
+    return DeepSeekConfig(
+        env_file=env_file,
+        api_key=api_key,
+        api_key_alias=api_key_alias,
+        base_url=base_url,
+        model=model,
+    )
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def build_code_preview(raw_code: Path) -> dict[str, Any]:
+    root = Path(raw_code).resolve()
+    files: list[dict[str, Any]] = []
+    truncated_files: list[str] = []
+    remaining = MAX_TOTAL_BYTES
+    for path in sorted(item for item in root.rglob("*") if item.is_file()):
+        relative = path.relative_to(root).as_posix()
+        size = path.stat().st_size
+        base = {"path": relative, "size": size, "sha256": _sha256(path)}
+        with path.open("rb") as handle:
+            sample = handle.read(4096)
+        try:
+            sample.decode("utf-8")
+            is_binary = b"\x00" in sample
+        except UnicodeDecodeError:
+            is_binary = True
+        if is_binary:
+            files.append({**base, "kind": "binary"})
+            continue
+
+        limit = min(MAX_FILE_BYTES, remaining)
+        with path.open("rb") as handle:
+            content_bytes = handle.read(limit)
+        truncated = size > limit
+        files.append(
+            {
+                **base,
+                "kind": "text",
+                "content": content_bytes.decode("utf-8", errors="replace"),
+                "truncated": truncated,
+            }
+        )
+        remaining -= len(content_bytes)
+        if truncated:
+            truncated_files.append(relative)
+    return {"files": files, "truncated_files": truncated_files}
+
+
+def _default_client(config: DeepSeekConfig) -> Any:
+    try:
+        from openai import OpenAI
+    except Exception as exc:  # pragma: no cover - environment dependent
+        raise DeepSeekSemanticError(
+            f"OpenAI-compatible client is unavailable: {exc}",
+            code="configuration_error",
+        ) from exc
+    return OpenAI(
+        api_key=config.api_key,
+        base_url=config.base_url,
+        timeout=90,
+        max_retries=0,
+    )
+
+
+def _metadata(
+    config: DeepSeekConfig,
+    *,
+    attempt: int,
+    preview: dict[str, Any],
+) -> dict[str, Any]:
+    return {
+        "env_file": str(config.env_file),
+        "base_url": config.base_url,
+        "model": config.model,
+        "api_key_alias": config.api_key_alias,
+        "attempt": attempt,
+        "request_id": None,
+        "usage": {},
+        "raw_response": "",
+        "code_preview": {
+            "truncated_files": list(preview["truncated_files"]),
+            "binary_files": [
+                item["path"] for item in preview["files"] if item["kind"] == "binary"
+            ],
+        },
+    }
+
+
+def _response_usage(response: Any) -> dict[str, int]:
+    usage = getattr(response, "usage", None)
+    if usage is None:
+        return {}
+    return {
+        "prompt_tokens": int(getattr(usage, "prompt_tokens", 0) or 0),
+        "completion_tokens": int(getattr(usage, "completion_tokens", 0) or 0),
+        "total_tokens": int(getattr(usage, "total_tokens", 0) or 0),
+    }
+
+
+def generate_semantic_candidate(
+    *,
+    execution_facts: dict[str, Any],
+    raw_code: Path,
+    environ: Mapping[str, str] | None = None,
+    client_factory: Callable[[DeepSeekConfig], Any] | None = None,
+    attempt: int = 1,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    config = load_deepseek_config(environ)
+    preview = build_code_preview(raw_code)
+    metadata = _metadata(config, attempt=attempt, preview=preview)
+    payload = {
+        "execution_facts": execution_facts,
+        "raw_code_preview": preview,
+        "required_candidate_shape": {
+            "function_summary": "one sentence",
+            "inputs": [
+                {
+                    "fact_id": "existing input fact_id",
+                    "role": "semantic role",
+                    "description": "plain-language description",
+                    "replaceability": (
+                        "generated when execution_facts source is generated_input; "
+                        "otherwise replaceable or fixed_resource"
+                    ),
+                }
+            ],
+            "parameters": [
+                {
+                    "fact_id": "existing parameter fact_id",
+                    "display_name": "human-readable name",
+                    "description": "plain-language description",
+                }
+            ],
+            "outputs": [
+                {
+                    "fact_id": "existing output fact_id",
+                    "description": "plain-language description",
+                    "result_role": "final, intermediate, log, or unknown",
+                }
+            ],
+        },
+    }
+    client = (client_factory or _default_client)(config)
+    try:
+        response = client.chat.completions.create(
+            model=config.model,
+            messages=[
+                {"role": "system", "content": SYSTEM_PROMPT},
+                {
+                    "role": "user",
+                    "content": json.dumps(payload, ensure_ascii=False, sort_keys=True),
+                },
+            ],
+            temperature=0,
+            max_tokens=32000,
+            response_format={"type": "json_object"},
+            extra_body={"thinking": {"type": "enabled"}},
+        )
+    except DeepSeekSemanticError:
+        raise
+    except Exception as exc:
+        message = str(exc).replace(config.api_key, "[REDACTED]")
+        raise DeepSeekSemanticError(
+            f"DeepSeek API request failed: {message}",
+            code="api_request_failed",
+            metadata=metadata,
+        ) from exc
+
+    content = (response.choices[0].message.content or "").strip()
+    metadata["request_id"] = getattr(response, "id", None)
+    metadata["usage"] = _response_usage(response)
+    metadata["finish_reason"] = getattr(response.choices[0], "finish_reason", None)
+    metadata["raw_response"] = content
+    try:
+        candidate = json.loads(content)
+    except json.JSONDecodeError as exc:
+        raise DeepSeekSemanticError(
+            f"DeepSeek response is not valid JSON: {exc.msg}",
+            code="invalid_json",
+            metadata=metadata,
+        ) from exc
+    if not isinstance(candidate, dict):
+        raise DeepSeekSemanticError(
+            "DeepSeek response must be one JSON object",
+            code="invalid_json",
+            metadata=metadata,
+        )
+    if "facts_sha256" in candidate:
+        metadata["discarded_fact_fields"] = ["facts_sha256"]
+        candidate.pop("facts_sha256")
+    candidate["facts_sha256"] = execution_facts["facts_sha256"]
+    candidate, binding_audit = bind_fact_derived_semantics(
+        execution_facts, candidate
+    )
+    if binding_audit:
+        metadata["fact_derived_semantic_bindings"] = binding_audit
+
+    validation_errors = validate_semantic_candidate(execution_facts, candidate)
+    if validation_errors:
+        metadata["validation_errors"] = validation_errors
+        metadata["system_bound_candidate"] = deepcopy(candidate)
+        raise DeepSeekSemanticError(
+            "DeepSeek semantic candidate failed the locked-fact gate",
+            code="semantic_candidate_invalid",
+            metadata=metadata,
+        )
+    return candidate, metadata
+
+
+def generate_semantic_patch(
+    *,
+    repair_context: dict[str, Any],
+    raw_code: Path,
+    environ: Mapping[str, str] | None = None,
+    client_factory: Callable[[DeepSeekConfig], Any] | None = None,
+    attempt: int = 1,
+) -> tuple[dict[str, Any], dict[str, Any]]:
+    """Ask DeepSeek for one semantic-only patch; validation stays in the repair gate."""
+
+    config = load_deepseek_config(environ)
+    preview = build_code_preview(raw_code)
+    metadata = _metadata(config, attempt=attempt, preview=preview)
+    payload = {
+        **deepcopy(repair_context),
+        "raw_code_preview": preview,
+        "required_patch_shape": {
+            "changes": [
+                {
+                    "section": "root, inputs, parameters, or outputs",
+                    "fact_id": "existing fact_id, or null for root",
+                    "fields": {"allowed semantic field": "new string value"},
+                }
+            ],
+        },
+    }
+    client = (client_factory or _default_client)(config)
+    try:
+        response = client.chat.completions.create(
+            model=config.model,
+            messages=[
+                {"role": "system", "content": REPAIR_SYSTEM_PROMPT},
+                {
+                    "role": "user",
+                    "content": json.dumps(payload, ensure_ascii=False, sort_keys=True),
+                },
+            ],
+            temperature=0,
+            max_tokens=6000,
+            response_format={"type": "json_object"},
+        )
+    except DeepSeekSemanticError:
+        raise
+    except Exception as exc:
+        message = str(exc).replace(config.api_key, "[REDACTED]")
+        raise DeepSeekSemanticError(
+            f"DeepSeek API repair request failed: {message}",
+            code="api_request_failed",
+            metadata=metadata,
+        ) from exc
+
+    content = (response.choices[0].message.content or "").strip()
+    metadata["request_id"] = getattr(response, "id", None)
+    metadata["usage"] = _response_usage(response)
+    metadata["raw_response"] = content
+    try:
+        patch = json.loads(content)
+    except json.JSONDecodeError as exc:
+        raise DeepSeekSemanticError(
+            f"DeepSeek repair response is not valid JSON: {exc.msg}",
+            code="invalid_json",
+            metadata=metadata,
+        ) from exc
+    if not isinstance(patch, dict):
+        raise DeepSeekSemanticError(
+            "DeepSeek repair response must be one JSON object",
+            code="invalid_json",
+            metadata=metadata,
+        )
+    if "facts_sha256" in patch:
+        metadata["discarded_fact_fields"] = ["facts_sha256"]
+        patch.pop("facts_sha256")
+    patch["facts_sha256"] = repair_context["execution_facts"]["facts_sha256"]
+    return patch, metadata
diff --git a/gfa_core/extension_stage_lightweight/evidence.py b/gfa_core/extension_stage_lightweight/evidence.py
new file mode 100644
index 000000000..d5249b749
--- /dev/null
+++ b/gfa_core/extension_stage_lightweight/evidence.py
@@ -0,0 +1,176 @@
+"""Collect execution facts without interpreting scientific semantics."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from pathlib import Path
+import shutil
+from typing import Any, Callable
+
+from .process_control import ProcessIdentity, start_managed_process, stop_process_group
+
+
+def _files_below(root: Path) -> dict[str, Path]:
+    if not root.exists():
+        return {}
+    return {
+        path.relative_to(root).as_posix(): path
+        for path in sorted(root.rglob("*"))
+        if path.is_file()
+    }
+
+
+def _sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def inventory_files(root: Path) -> dict[str, dict[str, Any]]:
+    """Return a JSON-ready snapshot of every file visible below ``root``."""
+
+    inventory: dict[str, dict[str, Any]] = {}
+    for relative, path in _files_below(root).items():
+        inventory[relative] = {
+            "kind": "symlink" if path.is_symlink() else "file",
+            "size": path.stat().st_size,
+            "sha256": _sha256(path),
+        }
+    return inventory
+
+
+def stage_package(*, raw_code: Path, raw_data: Path, work_dir: Path) -> dict[str, list[str]]:
+    """Merge code and data into one work directory without changing the sources."""
+
+    raw_code = Path(raw_code).resolve()
+    raw_data = Path(raw_data).resolve()
+    code_files = _files_below(raw_code)
+    data_files = _files_below(raw_data)
+    collisions = sorted(set(code_files) & set(data_files))
+    if collisions:
+        raise ValueError(f"Code/data path collision: {', '.join(collisions)}")
+
+    work_dir = Path(work_dir)
+    work_dir.mkdir(parents=True, exist_ok=True)
+    for relative, source in code_files.items():
+        destination = work_dir / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        if destination.exists() or destination.is_symlink():
+            raise ValueError(f"Work directory path already exists: {relative}")
+        shutil.copy2(source, destination)
+
+    for relative, source in data_files.items():
+        destination = work_dir / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        if destination.exists() or destination.is_symlink():
+            raise ValueError(f"Work directory path already exists: {relative}")
+        destination.symlink_to(source)
+
+    return {
+        "code_files": sorted(code_files),
+        "data_files": sorted(data_files),
+    }
+
+
+def _stdout_fact(stdout_path: Path) -> dict[str, Any]:
+    size = stdout_path.stat().st_size
+    if not size:
+        return {"present": False, "path": str(stdout_path), "size": 0, "preview": ""}
+    text = stdout_path.read_text(encoding="utf-8", errors="replace").strip()
+    return {
+        "present": True,
+        "path": str(stdout_path),
+        "size": size,
+        "preview": text[-4000:],
+    }
+
+
+def run_raw_baseline(
+    *,
+    command: str,
+    raw_code: Path,
+    raw_data: Path,
+    run_dir: Path,
+    env: dict[str, str] | None = None,
+    input_overrides: dict[str, Path] | None = None,
+    on_process_start: Callable[[ProcessIdentity], None] | None = None,
+) -> dict[str, Any]:
+    """Run the exact entry command once and capture before/after evidence.
+
+    Deliberately no timeout is supplied: long-running bioinformatics processes are
+    not failures merely because they exceed an arbitrary wall-clock duration.
+    """
+
+    run_dir = Path(run_dir)
+    work_dir = run_dir / "work"
+    logs_dir = run_dir / "logs"
+    logs_dir.mkdir(parents=True, exist_ok=True)
+    staged = stage_package(raw_code=raw_code, raw_data=raw_data, work_dir=work_dir)
+    rebound: dict[str, str] = {}
+    for relative, source in sorted((input_overrides or {}).items()):
+        source = Path(source).resolve()
+        if not source.is_file():
+            raise ValueError(f"Input override does not exist: {source}")
+        destination = work_dir / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        if destination.is_dir() and not destination.is_symlink():
+            raise ValueError(f"Input override destination is a directory: {relative}")
+        if destination.exists() or destination.is_symlink():
+            destination.unlink()
+        destination.symlink_to(source)
+        rebound[relative] = str(source)
+    staged["input_overrides"] = rebound
+    before = inventory_files(work_dir)
+
+    stdout_path = logs_dir / "stdout.log"
+    stderr_path = logs_dir / "stderr.log"
+    process_env = os.environ.copy()
+    if env:
+        process_env.update(env)
+    with stdout_path.open("wb") as stdout_handle, stderr_path.open("wb") as stderr_handle:
+        process, process_identity = start_managed_process(
+            ["bash", "-c", command],
+            cwd=work_dir,
+            env=process_env,
+            stdout=stdout_handle,
+            stderr=stderr_handle,
+        )
+        try:
+            if on_process_start is not None:
+                on_process_start(dict(process_identity))
+        except BaseException:
+            stop_process_group(process_identity)
+            process.wait()
+            raise
+        returncode = process.wait()
+
+    after = inventory_files(work_dir)
+    new_files = sorted(set(after) - set(before))
+    modified_files = sorted(
+        relative
+        for relative in set(after) & set(before)
+        if after[relative]["sha256"] != before[relative]["sha256"]
+    )
+    return {
+        "command": command,
+        "returncode": returncode,
+        "success": returncode == 0,
+        "process": process_identity,
+        "run_dir": str(run_dir),
+        "work_dir": str(work_dir),
+        "staged": staged,
+        "before_files": before,
+        "after_files": after,
+        "outputs": {
+            "new_files": new_files,
+            "modified_files": modified_files,
+            "stdout": _stdout_fact(stdout_path),
+        },
+        "logs": {
+            "stdout": str(stdout_path),
+            "stderr": str(stderr_path),
+        },
+    }
diff --git a/gfa_core/extension_stage_lightweight/process_control.py b/gfa_core/extension_stage_lightweight/process_control.py
new file mode 100644
index 000000000..d03d97faf
--- /dev/null
+++ b/gfa_core/extension_stage_lightweight/process_control.py
@@ -0,0 +1,389 @@
+"""Launch and explicitly stop extension commands under a stable supervisor."""
+
+from __future__ import annotations
+
+import ctypes
+import os
+from pathlib import Path
+import secrets
+import signal
+import subprocess
+import sys
+import time
+from typing import Any, Sequence, TypeAlias
+
+
+ProcessIdentity: TypeAlias = dict[str, int | str]
+
+CANCELLATION_GRACE_SECONDS = 0.2
+_PROC_READ_ATTEMPTS = 3
+_PROC_READ_RETRY_SECONDS = 0.005
+_SUPERVISOR_MARKER = "--bbav5-managed-supervisor-v1"
+_PR_SET_CHILD_SUBREAPER = 36
+_ALLOWED_POPEN_OPTIONS = {"cwd", "env", "stdin", "stdout", "stderr"}
+_PROC_UNCERTAIN = object()
+
+
+def _read_proc_stat(pid: int) -> tuple[str, int, int, int] | object | None:
+    """Return ``(state, pgrp, session, start_ticks)`` with race retries."""
+
+    path = Path(f"/proc/{pid}/stat")
+    for attempt in range(_PROC_READ_ATTEMPTS):
+        try:
+            text = path.read_text(encoding="utf-8")
+            fields = text.rsplit(")", 1)[1].split()
+            return fields[0], int(fields[2]), int(fields[3]), int(fields[19])
+        except (FileNotFoundError, ProcessLookupError):
+            if attempt + 1 < _PROC_READ_ATTEMPTS:
+                time.sleep(_PROC_READ_RETRY_SECONDS)
+        except (OSError, IndexError, ValueError):
+            return _PROC_UNCERTAIN
+    return None
+
+
+def _pid_start_time(pid: int) -> int | None:
+    stat = _read_proc_stat(pid)
+    return stat[3] if isinstance(stat, tuple) else None
+
+
+def _read_proc_cmdline(pid: int) -> list[str] | object | None:
+    path = Path(f"/proc/{pid}/cmdline")
+    for attempt in range(_PROC_READ_ATTEMPTS):
+        try:
+            return [
+                item.decode("utf-8", errors="surrogateescape")
+                for item in path.read_bytes().split(b"\0")
+                if item
+            ]
+        except (FileNotFoundError, ProcessLookupError):
+            if attempt + 1 < _PROC_READ_ATTEMPTS:
+                time.sleep(_PROC_READ_RETRY_SECONDS)
+        except OSError:
+            return _PROC_UNCERTAIN
+    return None
+
+
+def _is_matching_supervisor(
+    *, pid: int, pgid: int, start_time: int, token: str
+) -> bool:
+    stat = _read_proc_stat(pid)
+    if (
+        not isinstance(stat, tuple)
+        or stat[0] == "Z"
+        or stat[1:] != (pgid, pgid, start_time)
+    ):
+        return False
+    command = _read_proc_cmdline(pid)
+    if not isinstance(command, list) or len(command) < 7:
+        return False
+    try:
+        return bool(
+            Path(command[1]).resolve() == Path(__file__).resolve()
+            and command[2] == _SUPERVISOR_MARKER
+            and command[5] == token
+            and command[6] == "--"
+        )
+    except OSError:
+        return False
+
+
+def _set_child_subreaper() -> None:
+    libc = ctypes.CDLL(None, use_errno=True)
+    if libc.prctl(_PR_SET_CHILD_SUBREAPER, 1, 0, 0, 0) != 0:
+        error = ctypes.get_errno()
+        raise OSError(error, os.strerror(error))
+
+
+def _mirror_returncode(returncode: int) -> None:
+    if returncode < 0:
+        signum = -returncode
+        if signum != signal.SIGKILL:
+            signal.signal(signum, signal.SIG_DFL)
+        os.kill(os.getpid(), signum)
+        os._exit(128 + signum)
+    os._exit(returncode)
+
+
+def _supervise(command: Sequence[str], ready_fd: int, release_fd: int) -> None:
+    """Run the exact argv, then wait for every descendant as a subreaper."""
+
+    signal.signal(signal.SIGTERM, signal.SIG_IGN)
+    try:
+        _set_child_subreaper()
+        signal.signal(signal.SIGTERM, signal.SIG_DFL)
+        try:
+            child = subprocess.Popen(command)
+        finally:
+            signal.signal(signal.SIGTERM, signal.SIG_IGN)
+    except BaseException:
+        os.write(ready_fd, b"E")
+        os.close(ready_fd)
+        os.close(release_fd)
+        raise
+
+    os.write(ready_fd, b"1")
+    os.close(ready_fd)
+    os.read(release_fd, 1)
+    os.close(release_fd)
+
+    command_returncode: int | None = None
+    while True:
+        try:
+            reaped_pid, status = os.waitpid(-1, 0)
+        except ChildProcessError:
+            break
+        if reaped_pid == child.pid:
+            command_returncode = os.waitstatus_to_exitcode(status)
+            child.returncode = command_returncode
+
+    if command_returncode is None:
+        command_returncode = child.poll()
+    _mirror_returncode(command_returncode if command_returncode is not None else 1)
+
+
+def _supervisor_entry(argv: Sequence[str]) -> None:
+    if len(argv) < 6 or argv[0] != _SUPERVISOR_MARKER or argv[4] != "--":
+        raise SystemExit(2)
+    ready_fd = int(argv[1])
+    release_fd = int(argv[2])
+    _token = argv[3]
+    command = argv[5:]
+    if not command:
+        raise SystemExit(2)
+    _supervise(command, ready_fd, release_fd)
+
+
+def start_managed_process(
+    args: Sequence[str], **kwargs: Any
+) -> tuple[subprocess.Popen[bytes], ProcessIdentity]:
+    """Start ``args`` below a stable session/group supervisor anchor."""
+
+    if not args:
+        raise ValueError("Managed process command must not be empty")
+    unsupported = sorted(set(kwargs) - _ALLOWED_POPEN_OPTIONS)
+    if unsupported:
+        raise TypeError(f"Unsupported managed process option: {', '.join(unsupported)}")
+
+    ready_read, ready_write = os.pipe()
+    release_read, release_write = os.pipe()
+    token = secrets.token_hex(16)
+    supervisor_args = [
+        sys.executable,
+        str(Path(__file__).resolve()),
+        _SUPERVISOR_MARKER,
+        str(ready_write),
+        str(release_read),
+        token,
+        "--",
+        *(str(item) for item in args),
+    ]
+    try:
+        process = subprocess.Popen(
+            supervisor_args,
+            start_new_session=True,
+            pass_fds=(ready_write, release_read),
+            **kwargs,
+        )
+    except BaseException:
+        for file_descriptor in (ready_read, ready_write, release_read, release_write):
+            os.close(file_descriptor)
+        raise
+    os.close(ready_write)
+    os.close(release_read)
+
+    try:
+        ready = os.read(ready_read, 1)
+        if ready != b"1":
+            os.close(release_write)
+            process.wait()
+            raise RuntimeError("Managed supervisor could not launch the command")
+        pid = process.pid
+        pgid = os.getpgid(pid)
+        start_time = _pid_start_time(pid)
+        identity: ProcessIdentity = {
+            "pid": pid,
+            "pgid": pgid,
+            "pid_start_time": start_time or 0,
+            "supervisor_token": token,
+        }
+        if not _is_matching_supervisor(
+            pid=pid,
+            pgid=pgid,
+            start_time=start_time or 0,
+            token=token,
+        ):
+            os.kill(pid, signal.SIGKILL)
+            os.close(release_write)
+            process.wait()
+            raise RuntimeError("Managed supervisor identity could not be verified")
+        os.write(release_write, b"1")
+        return process, identity
+    finally:
+        os.close(ready_read)
+        try:
+            os.close(release_write)
+        except OSError:
+            pass
+
+
+def _group_membership(pgid: int, supervisor_pid: int) -> str:
+    uncertain = False
+    try:
+        for proc_path in Path("/proc").iterdir():
+            if not proc_path.name.isdigit() or int(proc_path.name) == supervisor_pid:
+                continue
+            stat = _read_proc_stat(int(proc_path.name))
+            if stat is _PROC_UNCERTAIN:
+                uncertain = True
+                continue
+            if stat is None:
+                try:
+                    uncertain = uncertain or proc_path.exists()
+                except OSError:
+                    uncertain = True
+                continue
+            if stat[0] != "Z" and stat[1] == pgid and stat[2] == pgid:
+                return "member"
+    except OSError:
+        return "uncertain"
+    return "uncertain" if uncertain else "empty"
+
+
+def _supervisor_state(
+    *,
+    pid: int,
+    pgid: int,
+    start_time: int,
+    token: str,
+    verify_absent_exit: bool = False,
+) -> str:
+    stat = _read_proc_stat(pid)
+    if stat is _PROC_UNCERTAIN:
+        return "lost"
+    if stat is None:
+        if verify_absent_exit:
+            try:
+                os.kill(pid, 0)
+            except ProcessLookupError:
+                return (
+                    "matching"
+                    if _group_membership(pgid, pid) != "empty"
+                    else "exited"
+                )
+            except OSError:
+                pass
+        return "lost"
+    if stat[1:] != (pgid, pgid, start_time):
+        return "lost"
+    if stat[0] == "Z":
+        if verify_absent_exit:
+            return "matching"
+        return "lost" if _group_membership(pgid, pid) != "empty" else "exited"
+    if _is_matching_supervisor(
+        pid=pid, pgid=pgid, start_time=start_time, token=token
+    ):
+        return "matching"
+    stat = _read_proc_stat(pid)
+    if (
+        isinstance(stat, tuple)
+        and stat[1:] == (pgid, pgid, start_time)
+        and stat[0] == "Z"
+    ):
+        if verify_absent_exit:
+            return "matching"
+        return "lost" if _group_membership(pgid, pid) != "empty" else "exited"
+    return "lost"
+
+
+def _wait_for_supervisor_state(
+    *,
+    pid: int,
+    pgid: int,
+    start_time: int,
+    token: str,
+    grace_seconds: float,
+    verify_absent_exit: bool = False,
+) -> str:
+    deadline = time.monotonic() + grace_seconds
+    while True:
+        state = _supervisor_state(
+            pid=pid,
+            pgid=pgid,
+            start_time=start_time,
+            token=token,
+            verify_absent_exit=verify_absent_exit,
+        )
+        if (
+            verify_absent_exit
+            and state == "lost"
+            and time.monotonic() < deadline
+        ):
+            time.sleep(0.01)
+            continue
+        if state != "matching":
+            return state
+        if time.monotonic() >= deadline:
+            return "running"
+        time.sleep(0.01)
+
+
+def stop_process_group(
+    identity: ProcessIdentity, *, grace_seconds: float = CANCELLATION_GRACE_SECONDS
+) -> bool:
+    """Stop only the group owned by the captured, persistent supervisor."""
+
+    try:
+        pid = int(identity["pid"])
+        pgid = int(identity["pgid"])
+        start_time = int(identity["pid_start_time"])
+        token = str(identity["supervisor_token"])
+    except (KeyError, TypeError, ValueError):
+        return False
+    if (
+        pid <= 0
+        or pgid <= 0
+        or pid != pgid
+        or start_time <= 0
+        or not token
+        or grace_seconds < 0
+    ):
+        return False
+    if not _is_matching_supervisor(
+        pid=pid, pgid=pgid, start_time=start_time, token=token
+    ):
+        return False
+    try:
+        os.killpg(pgid, signal.SIGTERM)
+    except ProcessLookupError:
+        return False
+    state = _wait_for_supervisor_state(
+        pid=pid,
+        pgid=pgid,
+        start_time=start_time,
+        token=token,
+        grace_seconds=grace_seconds,
+    )
+    if state == "exited":
+        return True
+    if state == "lost":
+        return False
+    if not _is_matching_supervisor(
+        pid=pid, pgid=pgid, start_time=start_time, token=token
+    ):
+        return False
+    try:
+        os.killpg(pgid, signal.SIGKILL)
+    except ProcessLookupError:
+        pass
+    return _wait_for_supervisor_state(
+        pid=pid,
+        pgid=pgid,
+        start_time=start_time,
+        token=token,
+        grace_seconds=grace_seconds,
+        verify_absent_exit=True,
+    ) == "exited"
+
+
+if __name__ == "__main__":
+    _supervisor_entry(sys.argv[1:])
diff --git a/gfa_core/extension_stage_lightweight/runtime_binding.py b/gfa_core/extension_stage_lightweight/runtime_binding.py
new file mode 100644
index 000000000..03abec7d7
--- /dev/null
+++ b/gfa_core/extension_stage_lightweight/runtime_binding.py
@@ -0,0 +1,2105 @@
+"""Build an evidence-owned contract for later runtime binding."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+from pathlib import PurePosixPath
+import re
+import shlex
+import shutil
+import tempfile
+from typing import Any, Callable
+
+from .command_model import _prepare_script_commands
+from .evidence import inventory_files
+from .process_control import ProcessIdentity, start_managed_process, stop_process_group
+
+
+SCHEMA_VERSION = "lightweight-runtime-binding/v1"
+
+
+class RuntimeBindingError(RuntimeError):
+    """A deterministic runtime binding could not be rendered safely."""
+
+    def __init__(self, code: str, message: str) -> None:
+        self.code = code
+        super().__init__(f"{code}: {message}")
+
+
+def _sha256_json(value: Any) -> str:
+    payload = json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()
+
+
+def _digest_without(value: dict[str, Any], field: str) -> str:
+    return _sha256_json({key: item for key, item in value.items() if key != field})
+
+
+def _sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _verify_raw_code(
+    inventory: dict[str, dict[str, Any]], raw_code: Path
+) -> None:
+    for relative, record in sorted(inventory.items()):
+        if record.get("source") != "raw_code":
+            continue
+        source = raw_code / relative
+        if not source.is_file():
+            raise ValueError(f"Code file is missing after baseline: {relative}")
+        if _sha256_file(source) != record.get("sha256"):
+            raise ValueError(f"Code file changed after baseline: {relative}")
+
+
+def _semantic_text_by_fact(
+    candidate: dict[str, Any], section: str, allowed_fields: set[str]
+) -> dict[str, dict[str, str]]:
+    projected: dict[str, dict[str, str]] = {}
+    entries = candidate.get(section, []) if isinstance(candidate, dict) else []
+    if not isinstance(entries, list):
+        return projected
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        fact_id = entry.get("fact_id")
+        if not isinstance(fact_id, str) or fact_id in projected:
+            continue
+        text = {
+            field: value.strip()
+            for field in allowed_fields
+            if isinstance((value := entry.get(field)), str) and value.strip()
+        }
+        projected[fact_id] = text
+    return projected
+
+
+def _source_scripts(
+    execution_facts: dict[str, Any], raw_code: Path
+) -> tuple[list[dict[str, Any]], dict[str, list[str]]]:
+    inventory = execution_facts["package"]["inventory"]
+    records: list[dict[str, Any]] = []
+    words_by_script: dict[str, list[str]] = {}
+    for relative in execution_facts.get("source_scripts", []):
+        package_record = inventory.get(relative)
+        if (
+            not isinstance(package_record, dict)
+            or package_record.get("source") != "raw_code"
+        ):
+            raise ValueError(f"Source script is not locked raw code: {relative}")
+        source = raw_code / relative
+        if not source.is_file():
+            raise ValueError(f"Source script does not exist in raw_code: {relative}")
+        actual_hash = _sha256_file(source)
+        records.append(
+            {"path": relative, "sha256": actual_hash, "locked": True}
+        )
+        lexer = shlex.shlex(
+            source.read_text(encoding="utf-8", errors="replace"),
+            posix=True,
+            punctuation_chars="|&;()<>",
+        )
+        lexer.whitespace_split = True
+        lexer.commenters = "#"
+        try:
+            words_by_script[relative] = list(lexer)
+        except ValueError:
+            words_by_script[relative] = []
+    return records, words_by_script
+
+
+def _package_files(
+    inventory: dict[str, dict[str, Any]], exposed_input_paths: set[str]
+) -> list[dict[str, Any]]:
+    return [
+        {
+            "path": path,
+            "source": record.get("source"),
+            "kind": record.get("kind"),
+            "size": record.get("size"),
+            "sha256": record.get("sha256"),
+            "locked": record.get("source") == "raw_code",
+            "exposed_as_input": path in exposed_input_paths,
+        }
+        for path, record in sorted(inventory.items())
+    ]
+
+
+def _command_anchor(command: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "step_id": command["step_id"],
+        "command_digest": hashlib.sha256(
+            command["command"].encode("utf-8")
+        ).hexdigest(),
+    }
+
+
+def _command_tokens(command: dict[str, Any]) -> list[str]:
+    try:
+        return shlex.split(command["command"])
+    except ValueError:
+        return []
+
+
+def _fact_anchor(
+    fact: dict[str, Any], command: dict[str, Any], token_index: int
+) -> dict[str, Any]:
+    return {
+        "fact_id": fact["fact_id"],
+        **_command_anchor(command),
+        "token_index": token_index,
+    }
+
+
+def _input_anchor(
+    fact: dict[str, Any], command: dict[str, Any]
+) -> tuple[dict[str, Any] | None, str | None]:
+    token_index = fact["token_index"]
+    tokens = _command_tokens(command)
+    if token_index >= len(tokens) or tokens[token_index] != fact["path"]:
+        return None, "input_reference_anchor_not_found"
+    return _fact_anchor(fact, command, token_index), None
+
+
+def _parameter_anchor(
+    fact: dict[str, Any], command: dict[str, Any]
+) -> tuple[dict[str, Any] | None, str | None]:
+    token_index = fact["token_index"]
+    tokens = _command_tokens(command)
+    if token_index >= len(tokens):
+        return None, "parameter_reference_anchor_not_found"
+    if fact["kind"] == "flag_value":
+        if "=" in tokens[token_index]:
+            return None, "inline_flag_value_not_supported"
+        token_index += 1
+    literal = fact["flag"] if fact["kind"] == "switch" else fact["value"]
+    if token_index >= len(tokens) or tokens[token_index] != literal:
+        return None, "parameter_reference_anchor_not_found"
+    return _fact_anchor(fact, command, token_index), None
+
+
+def _output_anchors(
+    output: dict[str, Any], commands_by_step: dict[str, dict[str, Any]]
+) -> tuple[list[dict[str, Any]], str | None]:
+    anchors: list[dict[str, Any]] = []
+    producer_step_ids = output.get("producer_step_ids", [])
+    if not producer_step_ids:
+        return [], "output_reference_anchor_not_found"
+    for step_id in producer_step_ids:
+        command = commands_by_step.get(step_id)
+        if command is None:
+            return [], "output_reference_anchor_not_found"
+        matching_indexes = [
+            index
+            for index, token in enumerate(_command_tokens(command))
+            if token == output["path"]
+        ]
+        if not matching_indexes:
+            return [], "output_reference_anchor_not_found"
+        if len(matching_indexes) != 1:
+            return [], "output_reference_anchor_ambiguous"
+        anchors.append(_fact_anchor(output, command, matching_indexes[0]))
+    return anchors, None
+
+
+def _patch_candidates(
+    commands: list[dict[str, Any]],
+    inputs: list[dict[str, Any]],
+    parameters: list[dict[str, Any]],
+    path_references: list[dict[str, Any]],
+    output_files: list[dict[str, Any]],
+) -> list[dict[str, Any]]:
+    commands_by_step = {command["step_id"]: command for command in commands}
+    path_members: dict[str, list[dict[str, Any]]] = {}
+    for item in inputs:
+        command = commands_by_step[item["step_id"]]
+        anchor, reason = _input_anchor(item, command)
+        path_members.setdefault(item["path"], []).append(
+            {
+                "fact_id": item["fact_id"],
+                "member_kind": (
+                    "input" if item["replaceable"] else "generated_input"
+                ),
+                "anchors": [anchor] if anchor else [],
+                "reason": reason,
+            }
+        )
+    for item in output_files:
+        anchors, reason = _output_anchors(item, commands_by_step)
+        path_members.setdefault(item["path"], []).append(
+            {
+                "fact_id": item["fact_id"],
+                "member_kind": "output",
+                "anchors": anchors,
+                "producer_step_ids": deepcopy(
+                    item.get("producer_step_ids", [])
+                ),
+                "reason": reason,
+            }
+        )
+
+    candidates: list[dict[str, Any]] = []
+    for path, members in path_members.items():
+        member_kinds = {member["member_kind"] for member in members}
+        reasons = [member["reason"] for member in members if member["reason"]]
+        if "generated_input" in member_kinds and "output" not in member_kinds:
+            reasons.append("generated_input_without_output_binding")
+        producer_step_ids = [
+            step_id
+            for member in members
+            for step_id in member.get("producer_step_ids", [])
+        ]
+        candidates.append(
+            {
+                "binding_key": f"path:{path}",
+                "fact_ids": [member["fact_id"] for member in members],
+                "anchors": [
+                    anchor
+                    for member in members
+                    for anchor in member["anchors"]
+                ],
+                "original_literal": path,
+                "patch_kind": (
+                    "output_path" if "output" in member_kinds else "input_path"
+                ),
+                **(
+                    {"producer_step_ids": producer_step_ids}
+                    if producer_step_ids
+                    else {}
+                ),
+                **({"_unpatchable_reason": reasons[0]} if reasons else {}),
+            }
+        )
+
+    for item in parameters:
+        command = commands_by_step[item["step_id"]]
+        anchor, reason = _parameter_anchor(item, command)
+        candidate = {
+            "binding_key": f"parameter:{item['fact_id']}",
+            "fact_ids": [item["fact_id"]],
+            "anchors": [anchor] if anchor else [],
+            "original_literal": (
+                item["flag"] if item["kind"] == "switch" else item["value"]
+            ),
+            "patch_kind": (
+                "parameter_switch"
+                if item["kind"] == "switch"
+                else "parameter_value"
+            ),
+        }
+        if reason:
+            candidate["_unpatchable_reason"] = reason
+        candidates.append(candidate)
+    for item in path_references:
+        command = commands_by_step[item["step_id"]]
+        anchor, reason = _parameter_anchor(item, command)
+        candidate = {
+            "binding_key": f"path_reference:{item['fact_id']}",
+            "fact_ids": [item["fact_id"]],
+            "anchors": [anchor] if anchor else [],
+            "original_literal": item["path"],
+            "patch_kind": "output_reference_path",
+        }
+        if reason:
+            candidate["_unpatchable_reason"] = reason
+        candidates.append(candidate)
+    return candidates
+
+
+def _locate_patch_targets(
+    candidates: list[dict[str, Any]],
+    source_scripts: list[dict[str, Any]],
+    words_by_script: dict[str, list[str]],
+) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    targets: list[dict[str, Any]] = []
+    unpatchable: list[dict[str, Any]] = []
+    for candidate in candidates:
+        reason = candidate.get("_unpatchable_reason")
+        source_matches = [
+            (
+                script,
+                words_by_script[script["path"]].count(
+                    candidate["original_literal"]
+                ),
+            )
+            for script in source_scripts
+            if candidate["original_literal"] in words_by_script[script["path"]]
+        ]
+        anchors = candidate["anchors"]
+        anchor_identities = {
+            (
+                anchor["step_id"],
+                anchor["token_index"],
+                anchor["command_digest"],
+            )
+            for anchor in anchors
+        }
+        if reason is None:
+            if len(source_matches) > 1 or len(anchor_identities) != len(anchors):
+                reason = "source_literal_ambiguous"
+            elif (
+                len(source_matches) == 1
+                and source_matches[0][1] != len(anchors)
+            ):
+                reason = "source_literal_ambiguous"
+            elif not source_matches:
+                reason = "source_literal_not_found_in_raw_shell"
+
+        clean_candidate = {
+            key: value
+            for key, value in candidate.items()
+            if key != "_unpatchable_reason"
+        }
+        if reason is not None:
+            unpatchable.append(
+                {
+                    **clean_candidate,
+                    "reason": reason,
+                }
+            )
+            continue
+        script, count = source_matches[0]
+        target = {
+            **clean_candidate,
+            "script_path": script["path"],
+            "script_hash": script["sha256"],
+            "expected_exact_match_count": count,
+        }
+        if len(anchors) == 1:
+            target.update(
+                {
+                    "step_id": anchors[0]["step_id"],
+                    "token_index": anchors[0]["token_index"],
+                    "command_digest": anchors[0]["command_digest"],
+                }
+            )
+        targets.append(target)
+    return targets, unpatchable
+
+
+def build_runtime_binding_contract(
+    execution_facts: dict[str, Any],
+    semantic_candidate: dict[str, Any],
+    raw_code: Path,
+) -> dict[str, Any]:
+    """Project locked execution facts into a runtime-binding contract.
+
+    Semantic data is optional display text. It never controls commands, paths,
+    values, ownership, or replaceability.
+    """
+
+    raw_code = Path(raw_code)
+    inventory = execution_facts["package"]["inventory"]
+    _verify_raw_code(inventory, raw_code)
+    input_text = _semantic_text_by_fact(
+        semantic_candidate, "inputs", {"role", "description"}
+    )
+    parameter_text = _semantic_text_by_fact(
+        semantic_candidate, "parameters", {"display_name", "description"}
+    )
+    output_text = _semantic_text_by_fact(
+        semantic_candidate, "outputs", {"description", "result_role"}
+    )
+
+    inputs: list[dict[str, Any]] = []
+    parameters: list[dict[str, Any]] = []
+    path_references: list[dict[str, Any]] = []
+    for command in execution_facts.get("commands", []):
+        step_id = command["step_id"]
+        for fact in command.get("inputs", []):
+            replaceable = fact.get("source") == "baseline_input"
+            inputs.append(
+                {
+                    **deepcopy(fact),
+                    "step_id": step_id,
+                    "replaceable": replaceable,
+                    "locked": not replaceable,
+                    **input_text.get(fact["fact_id"], {}),
+                }
+            )
+        for fact in command.get("parameters", []):
+            if fact.get("value_role") == "output_reference":
+                path_references.append(
+                    {
+                        **deepcopy(fact),
+                        "step_id": step_id,
+                        "path": fact["value"],
+                    }
+                )
+                continue
+            if fact.get("value_role") == "input":
+                continue
+            parameters.append(
+                {
+                    **deepcopy(fact),
+                    "step_id": step_id,
+                    **parameter_text.get(fact["fact_id"], {}),
+                }
+            )
+
+    output_files = [
+        {
+            **deepcopy(fact),
+            **output_text.get(fact["fact_id"], {}),
+        }
+        for fact in execution_facts.get("outputs", {}).get("files", [])
+    ]
+    stdout = deepcopy(execution_facts.get("outputs", {}).get("stdout", {}))
+    stdout_fact_id = stdout.get("fact_id")
+    if isinstance(stdout_fact_id, str):
+        stdout.update(output_text.get(stdout_fact_id, {}))
+
+    scripts, words_by_script = _source_scripts(execution_facts, raw_code)
+    patch_targets, unpatchable_targets = _locate_patch_targets(
+        _patch_candidates(
+            execution_facts.get("commands", []),
+            inputs,
+            parameters,
+            path_references,
+            output_files,
+        ),
+        scripts,
+        words_by_script,
+    )
+    exposed_input_paths = {
+        item["path"] for item in inputs if item["replaceable"]
+    }
+    contract = {
+        "schema_version": SCHEMA_VERSION,
+        "facts_sha256": execution_facts["facts_sha256"],
+        "package_digest": _sha256_json(inventory),
+        "original_command": execution_facts["original_command"],
+        "source_scripts": scripts,
+        "package_files": _package_files(inventory, exposed_input_paths),
+        "inputs": inputs,
+        "parameters": parameters,
+        "path_references": path_references,
+        "outputs": {"files": output_files, "stdout": stdout},
+        "patch_targets": patch_targets,
+        "unpatchable_targets": unpatchable_targets,
+    }
+    contract["contract_digest"] = _digest_without(contract, "contract_digest")
+    return contract
+
+
+_SWITCH_TOKEN = re.compile(r"-{1,2}[A-Za-z0-9][A-Za-z0-9_.:+-]*\Z")
+_PREFIX_TOKEN = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*\Z")
+_PREFIX_DELIMITERS = ".-_"
+
+
+def _resolved_result(
+    contract: dict[str, Any],
+    *,
+    status: str,
+    input_bindings: list[dict[str, Any]] | None = None,
+    parameter_bindings: list[dict[str, Any]] | None = None,
+    output_bindings: list[dict[str, Any]] | None = None,
+    prefix_binding: dict[str, Any] | None = None,
+    error: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    result = {
+        "status": status,
+        "facts_sha256": contract.get("facts_sha256"),
+        "package_digest": contract.get("package_digest"),
+        "contract_digest": contract.get("contract_digest"),
+        "input_bindings": input_bindings or [],
+        "parameter_bindings": parameter_bindings or [],
+        "output_bindings": output_bindings or [],
+        "prefix_binding": prefix_binding,
+        "error": error,
+    }
+    result["binding_digest"] = _digest_without(result, "binding_digest")
+    return result
+
+
+def _blocked_result(
+    contract: dict[str, Any],
+    code: str,
+    message: str,
+    *,
+    input_bindings: list[dict[str, Any]] | None = None,
+    parameter_bindings: list[dict[str, Any]] | None = None,
+    **details: Any,
+) -> dict[str, Any]:
+    return _resolved_result(
+        contract,
+        status="blocked",
+        input_bindings=input_bindings,
+        parameter_bindings=parameter_bindings,
+        error={"code": code, "message": message, **details},
+    )
+
+
+def _has_control(value: str) -> bool:
+    return any(ord(character) < 32 or ord(character) == 127 for character in value)
+
+
+def _input_groups(
+    contract: dict[str, Any],
+) -> tuple[dict[str, list[dict[str, Any]]], dict[str, str], set[str]]:
+    groups: dict[str, list[dict[str, Any]]] = {}
+    for item in contract.get("inputs", []):
+        if not isinstance(item, dict) or not item.get("replaceable"):
+            continue
+        path = item.get("path")
+        if isinstance(path, str) and path:
+            groups.setdefault(path, []).append(item)
+
+    aliases: dict[str, str] = {}
+    ambiguous: set[str] = set()
+    for path, items in groups.items():
+        for alias in [path, *(item.get("fact_id") for item in items)]:
+            if not isinstance(alias, str) or not alias:
+                continue
+            if alias in aliases and aliases[alias] != path:
+                ambiguous.add(alias)
+            else:
+                aliases[alias] = path
+    roles: dict[str, set[str]] = {}
+    for path, items in groups.items():
+        for item in items:
+            role = item.get("role")
+            if isinstance(role, str) and role:
+                roles.setdefault(role, set()).add(path)
+    for role, paths in roles.items():
+        if len(paths) == 1:
+            aliases[role] = next(iter(paths))
+        else:
+            ambiguous.add(role)
+    for alias in ambiguous:
+        aliases.pop(alias, None)
+    return groups, aliases, ambiguous
+
+
+def _resolve_inputs(
+    contract: dict[str, Any], input_overrides: dict[str, Any]
+) -> tuple[list[dict[str, Any]] | None, dict[str, Any] | None]:
+    groups, aliases, ambiguous = _input_groups(contract)
+    selected: dict[str, list[Path]] = {path: [] for path in groups}
+    for alias, value in input_overrides.items():
+        if alias in ambiguous:
+            return None, {
+                "code": "INPUT_BINDING_AMBIGUOUS",
+                "message": f"Input alias is not unique: {alias}",
+            }
+        original_path = aliases.get(alias)
+        if original_path is None:
+            return None, {
+                "code": "INPUT_NOT_DECLARED",
+                "message": f"Input is not declared by the contract: {alias}",
+                "available_fact_ids": sorted(
+                    item["fact_id"]
+                    for items in groups.values()
+                    for item in items
+                    if isinstance(item.get("fact_id"), str)
+                ),
+            }
+        try:
+            expanded = Path(value).expanduser()
+            selected[original_path].append(Path(os.path.abspath(expanded)))
+        except (TypeError, ValueError, OSError):
+            return None, {
+                "code": "INPUT_PATH_NOT_FOUND",
+                "message": f"Input path is invalid: {value}",
+            }
+
+    bindings: list[dict[str, Any]] = []
+    for original_path, items in sorted(groups.items()):
+        paths = selected[original_path]
+        if not paths:
+            return None, {
+                "code": "INPUT_BINDING_MISSING",
+                "message": f"Required input has no runtime binding: {original_path}",
+            }
+        distinct = {str(path) for path in paths}
+        if len(distinct) != 1:
+            return None, {
+                "code": "INPUT_BINDING_CONFLICT",
+                "message": f"Input has conflicting runtime bindings: {original_path}",
+            }
+        runtime_path = paths[0]
+        if not runtime_path.is_file():
+            return None, {
+                "code": "INPUT_PATH_NOT_FOUND",
+                "message": f"Runtime input file does not exist: {runtime_path}",
+            }
+        bindings.append(
+            {
+                "original_path": original_path,
+                "runtime_path": str(runtime_path),
+                "fact_ids": sorted(
+                    item["fact_id"]
+                    for item in items
+                    if isinstance(item.get("fact_id"), str)
+                ),
+            }
+        )
+    return bindings, None
+
+
+def _resolve_parameters(
+    contract: dict[str, Any], parameter_overrides: dict[str, Any]
+) -> tuple[list[dict[str, Any]] | None, dict[str, Any] | None]:
+    declared = {
+        item["fact_id"]: item
+        for item in contract.get("parameters", [])
+        if isinstance(item, dict) and isinstance(item.get("fact_id"), str)
+    }
+    unknown = sorted(set(parameter_overrides) - set(declared))
+    if unknown:
+        return None, {
+            "code": "PARAMETER_NOT_DECLARED",
+            "message": f"Parameter is not declared by the original command: {unknown[0]}",
+            "available_fact_ids": sorted(declared),
+        }
+
+    bindings: list[dict[str, Any]] = []
+    for fact_id, item in sorted(declared.items()):
+        original = item.get("value", item.get("flag", ""))
+        runtime = parameter_overrides.get(fact_id, original)
+        runtime_value = str(runtime)
+        if not runtime_value or _has_control(runtime_value):
+            return None, {
+                "code": "PARAMETER_VALUE_INVALID",
+                "message": f"Parameter contains an unsafe value: {fact_id}",
+            }
+        if item.get("kind") == "switch" and not _SWITCH_TOKEN.fullmatch(
+            runtime_value
+        ):
+            return None, {
+                "code": "PARAMETER_VALUE_INVALID",
+                "message": f"Switch must be one safe option token: {fact_id}",
+            }
+        bindings.append(
+            {
+                "fact_id": fact_id,
+                "kind": item.get("kind"),
+                "flag": item.get("flag"),
+                "original_value": str(original),
+                "runtime_value": runtime_value,
+                "changed": runtime_value != str(original),
+            }
+        )
+    return bindings, None
+
+
+def _validate_prefix(value: Any) -> bool:
+    return (
+        isinstance(value, str)
+        and ".." not in value
+        and _PREFIX_TOKEN.fullmatch(value) is not None
+    )
+
+
+def _output_has_prefix(output_path: str, prefix: str) -> bool:
+    name = PurePosixPath(output_path).name
+    return name.startswith(prefix) and (
+        len(name) == len(prefix)
+        or name[len(prefix)] in _PREFIX_DELIMITERS
+    )
+
+
+def _replace_output_prefix(output_path: str, old: str, new: str) -> str:
+    path = PurePosixPath(output_path)
+    name = new + path.name[len(old) :]
+    return name if str(path.parent) == "." else str(path.parent / name)
+
+
+def _shared_output_prefix(outputs: list[dict[str, Any]]) -> str | None:
+    """Return one delimiter-owned prefix from declared output filenames."""
+
+    names = [PurePosixPath(item["path"]).name for item in outputs]
+    if not names:
+        return None
+    if len(names) == 1:
+        suffix = PurePosixPath(names[0]).suffix
+        candidate = names[0][: -len(suffix)] if suffix else names[0]
+    else:
+        candidate = os.path.commonprefix(names).rstrip("._-")
+    if not _validate_prefix(candidate):
+        return None
+    if not all(_output_has_prefix(item["path"], candidate) for item in outputs):
+        return None
+    return candidate
+
+
+def _runtime_input_owned_output(
+    output_path: str,
+    runtime_by_original: dict[str, str],
+    *,
+    allow_sidecar: bool,
+) -> str | None:
+    """Preserve outputs that are the runtime input itself or its sidecar."""
+
+    candidates = set()
+    for original_input, runtime_input in runtime_by_original.items():
+        if output_path == original_input:
+            suffix = ""
+        elif allow_sidecar and output_path.startswith(original_input) and output_path[
+            len(original_input) : len(original_input) + 1
+        ] in _PREFIX_DELIMITERS:
+            suffix = output_path[len(original_input) :]
+        else:
+            continue
+        candidates.add(Path(runtime_input).name + suffix)
+    return next(iter(candidates)) if len(candidates) == 1 else None
+
+
+def _candidate_prefix_pairs(
+    original_input: str, runtime_input: str, output_path: str
+) -> tuple[set[tuple[str, str]], bool]:
+    """Return safe prefix substitutions supported by one input/output pair."""
+
+    original = PurePosixPath(original_input).name
+    runtime = Path(runtime_input).name
+    boundaries = [
+        index
+        for index, character in enumerate(original)
+        if character in _PREFIX_DELIMITERS and index > 0
+    ]
+    boundaries.append(len(original))
+    pairs: set[tuple[str, str]] = set()
+    invalid = False
+    for boundary in boundaries:
+        old_prefix = original[:boundary]
+        if not _output_has_prefix(output_path, old_prefix):
+            continue
+        suffix = original[boundary:]
+        if suffix and not runtime.endswith(suffix):
+            continue
+        new_prefix = runtime[: -len(suffix)] if suffix else runtime
+        if not _validate_prefix(old_prefix) or not _validate_prefix(new_prefix):
+            invalid = True
+            continue
+        pairs.add((old_prefix, new_prefix))
+    return pairs, invalid
+
+
+def _participant_paths(
+    contract: dict[str, Any],
+    output: dict[str, Any],
+    all_paths: set[str],
+) -> set[str]:
+    producer_steps = set(output.get("producer_step_ids", []))
+    same_step = {
+        item["path"]
+        for item in contract.get("inputs", [])
+        if isinstance(item, dict)
+        and item.get("replaceable")
+        and item.get("step_id") in producer_steps
+        and item.get("path") in all_paths
+    }
+    return same_step or all_paths
+
+
+def resolve_runtime_bindings(
+    contract: dict[str, Any],
+    input_overrides: dict[str, Any],
+    parameter_overrides: dict[str, Any],
+    explicit_prefix: str | None = None,
+) -> dict[str, Any]:
+    """Resolve runtime inputs and explicit parameters without changing inputs.
+
+    Output-prefix propagation is evidence based. The original output prefix is
+    taken from declared output paths; the runtime prefix defaults to ``output``.
+    """
+
+    if contract.get("schema_version") != SCHEMA_VERSION:
+        return _blocked_result(
+            contract,
+            "CONTRACT_SCHEMA_UNSUPPORTED",
+            "Runtime binding requires lightweight-runtime-binding/v1",
+        )
+    if explicit_prefix is not None and not _validate_prefix(explicit_prefix):
+        return _blocked_result(
+            contract,
+            "INVALID_PREFIX",
+            "Prefix must be one ASCII-safe filename prefix",
+        )
+
+    input_bindings, input_error = _resolve_inputs(contract, input_overrides)
+    if input_error:
+        return _blocked_result(contract, **input_error)
+    parameter_bindings, parameter_error = _resolve_parameters(
+        contract, parameter_overrides
+    )
+    if parameter_error:
+        return _blocked_result(
+            contract,
+            input_bindings=input_bindings,
+            **parameter_error,
+        )
+
+    output_files = [
+        item
+        for item in contract.get("outputs", {}).get("files", [])
+        if isinstance(item, dict)
+        and isinstance(item.get("fact_id"), str)
+        and isinstance(item.get("path"), str)
+    ]
+    if not output_files:
+        stdout = contract.get("outputs", {}).get("stdout", {})
+        if isinstance(stdout, dict) and stdout.get("present"):
+            return _resolved_result(
+                contract,
+                status="resolved",
+                input_bindings=input_bindings,
+                parameter_bindings=parameter_bindings,
+                output_bindings=[],
+                prefix_binding={"mode": "none"},
+                error=None,
+            )
+        return _blocked_result(
+            contract,
+            "OUTPUT_BINDING_AMBIGUOUS",
+            "No file output can be bound and stdout is not a declared result",
+            input_bindings=input_bindings,
+            parameter_bindings=parameter_bindings,
+        )
+
+    runtime_by_original = {
+        binding["original_path"]: binding["runtime_path"]
+        for binding in input_bindings or []
+    }
+    participant_options: list[set[tuple[str, str]]] = []
+    participating_paths: set[str] = set()
+    for output in output_files:
+        eligible_paths = _participant_paths(
+            contract, output, set(runtime_by_original)
+        )
+        options_for_output: list[tuple[str, set[tuple[str, str]]]] = []
+        invalid = False
+        for original_path in sorted(eligible_paths):
+            pairs, unsafe = _candidate_prefix_pairs(
+                original_path,
+                runtime_by_original[original_path],
+                output["path"],
+            )
+            invalid = invalid or unsafe
+            if pairs:
+                options_for_output.append((original_path, pairs))
+        if not options_for_output and eligible_paths != set(runtime_by_original):
+            for original_path in sorted(runtime_by_original):
+                pairs, unsafe = _candidate_prefix_pairs(
+                    original_path,
+                    runtime_by_original[original_path],
+                    output["path"],
+                )
+                invalid = invalid or unsafe
+                if pairs:
+                    options_for_output.append((original_path, pairs))
+        if invalid:
+            return _blocked_result(
+                contract,
+                "INVALID_PREFIX",
+                "An input-derived prefix is not an ASCII-safe filename prefix",
+                input_bindings=input_bindings,
+                parameter_bindings=parameter_bindings,
+            )
+        for original_path, pairs in options_for_output:
+            participating_paths.add(original_path)
+            participant_options.append(pairs)
+
+    common_pairs = (
+        set.intersection(*participant_options) if participant_options else set()
+    )
+    if common_pairs:
+        old_prefix = max(
+            common_pairs, key=lambda pair: (len(pair[0]), len(pair[1]), pair)
+        )[0]
+    elif participant_options:
+        common_old = set.intersection(
+            *[{old for old, _new in options} for options in participant_options]
+        )
+        if not common_old:
+            old_prefix = _shared_output_prefix(output_files)
+        else:
+            old_prefix = max(common_old, key=lambda value: (len(value), value))
+    else:
+        old_prefix = _shared_output_prefix(output_files)
+    if old_prefix is None:
+        return _blocked_result(
+            contract,
+            "OUTPUT_BINDING_AMBIGUOUS",
+            "Declared file outputs do not share one safe output prefix",
+            input_bindings=input_bindings,
+            parameter_bindings=parameter_bindings,
+        )
+    new_prefix = explicit_prefix or "output"
+    direct_output_fact_ids = {
+        fact_id
+        for target in contract.get("patch_targets", [])
+        if isinstance(target, dict)
+        and target.get("patch_kind") in {"output_path", "output_reference_path"}
+        for fact_id in target.get("fact_ids", [])
+        if isinstance(fact_id, str)
+    }
+    output_bindings = []
+    for output in output_files:
+        original_path = output["path"]
+        runtime_path = _runtime_input_owned_output(
+            original_path,
+            runtime_by_original,
+            allow_sidecar=output["fact_id"] not in direct_output_fact_ids,
+        )
+        if runtime_path is None:
+            runtime_path = (
+                _replace_output_prefix(original_path, old_prefix, new_prefix)
+                if _output_has_prefix(original_path, old_prefix)
+                else original_path
+            )
+        output_bindings.append(
+            {
+                "fact_id": output["fact_id"],
+                "original_path": original_path,
+                "runtime_path": runtime_path,
+                "transformed": runtime_path != original_path,
+            }
+        )
+    runtime_output_paths: dict[str, str] = {}
+    for binding in output_bindings:
+        runtime_path = binding["runtime_path"]
+        if runtime_path in runtime_output_paths:
+            return _blocked_result(
+                contract,
+                "OUTPUT_PATH_COLLISION",
+                "Two declared outputs resolve to the same runtime path",
+                input_bindings=input_bindings,
+                parameter_bindings=parameter_bindings,
+                runtime_path=runtime_path,
+                fact_ids=sorted(
+                    [runtime_output_paths[runtime_path], binding["fact_id"]]
+                ),
+            )
+        runtime_output_paths[runtime_path] = binding["fact_id"]
+    return _resolved_result(
+        contract,
+        status="resolved",
+        input_bindings=input_bindings,
+        parameter_bindings=parameter_bindings,
+        output_bindings=output_bindings,
+        prefix_binding={
+            "mode": "explicit" if explicit_prefix is not None else "default",
+            "old_prefix": old_prefix,
+            "new_prefix": new_prefix,
+            "participating_inputs": sorted(participating_paths),
+        },
+        error=None,
+    )
+
+
+_SHELL_WORD_EDGE = r"A-Za-z0-9_./:+-"
+
+
+def _safe_runtime_relative(value: Any, *, field: str) -> str:
+    if not isinstance(value, str) or not value or _has_control(value):
+        raise RuntimeBindingError(
+            "UNSAFE_RELATIVE_PATH", f"{field} must be a non-empty relative path"
+        )
+    path = PurePosixPath(value)
+    if path.is_absolute() or value.startswith("/") or ".." in path.parts:
+        raise RuntimeBindingError(
+            "UNSAFE_RELATIVE_PATH", f"{field} escapes the runtime directory: {value}"
+        )
+    if str(path) in {"", "."}:
+        raise RuntimeBindingError(
+            "UNSAFE_RELATIVE_PATH", f"{field} is not a file path: {value}"
+        )
+    return str(path)
+
+
+def _resolved_digest(resolved: dict[str, Any]) -> str:
+    return _digest_without(resolved, "binding_digest")
+
+
+def _package_inventory_from_contract(
+    contract: dict[str, Any],
+) -> dict[str, dict[str, Any]]:
+    inventory: dict[str, dict[str, Any]] = {}
+    for record in contract.get("package_files", []):
+        if not isinstance(record, dict):
+            raise RuntimeBindingError(
+                "PACKAGE_INVENTORY_INVALID", "package file record must be an object"
+            )
+        relative = _safe_runtime_relative(record.get("path"), field="package path")
+        if relative in inventory:
+            raise RuntimeBindingError(
+                "PACKAGE_INVENTORY_INVALID", f"duplicate package path: {relative}"
+            )
+        inventory[relative] = {
+            key: record.get(key)
+            for key in ("kind", "size", "sha256", "source")
+        }
+    return inventory
+
+
+def _validate_contract_digest(contract: dict[str, Any]) -> None:
+    if contract.get("contract_digest") != _digest_without(
+        contract, "contract_digest"
+    ):
+        raise RuntimeBindingError(
+            "CONTRACT_DIGEST_MISMATCH", "runtime binding contract was modified"
+        )
+    inventory = _package_inventory_from_contract(contract)
+    if contract.get("package_digest") != _sha256_json(inventory):
+        raise RuntimeBindingError(
+            "PACKAGE_DIGEST_MISMATCH",
+            "package digest does not match the locked package inventory",
+        )
+
+
+def _canonical_resolution(
+    contract: dict[str, Any], resolved: dict[str, Any]
+) -> dict[str, Any]:
+    input_overrides = {
+        str(item.get("original_path") or ""): item.get("runtime_path")
+        for item in resolved.get("input_bindings", [])
+        if isinstance(item, dict)
+    }
+    parameter_overrides = {
+        str(item.get("fact_id") or ""): item.get("runtime_value")
+        for item in resolved.get("parameter_bindings", [])
+        if isinstance(item, dict)
+    }
+    prefix = resolved.get("prefix_binding")
+    explicit_prefix = (
+        prefix.get("new_prefix")
+        if isinstance(prefix, dict) and prefix.get("mode") == "explicit"
+        else None
+    )
+    return resolve_runtime_bindings(
+        contract,
+        input_overrides,
+        parameter_overrides,
+        explicit_prefix=explicit_prefix,
+    )
+
+
+def _validate_render_inputs(
+    contract: dict[str, Any], raw_code: Path, resolved: dict[str, Any]
+) -> tuple[dict[str, dict[str, Any]], dict[str, str]]:
+    _validate_contract_digest(contract)
+    if resolved.get("status") != "resolved":
+        raise RuntimeBindingError(
+            "RESOLUTION_NOT_READY", "runtime bindings must have status=resolved"
+        )
+    for key in ("facts_sha256", "package_digest", "contract_digest"):
+        if resolved.get(key) != contract.get(key):
+            raise RuntimeBindingError(
+                "RESOLUTION_CONTRACT_MISMATCH",
+                f"resolved {key} does not match the binding contract",
+            )
+    if resolved.get("binding_digest") != _resolved_digest(resolved):
+        raise RuntimeBindingError(
+            "RESOLUTION_DIGEST_MISMATCH", "resolved binding digest is invalid"
+        )
+    if _canonical_resolution(contract, resolved) != resolved:
+        raise RuntimeBindingError(
+            "RESOLUTION_CANONICAL_MISMATCH",
+            "resolved bindings do not match deterministic resolution",
+        )
+
+    declared: dict[str, dict[str, Any]] = {}
+    for record in contract.get("package_files", []):
+        if not isinstance(record, dict) or record.get("source") != "raw_code":
+            continue
+        relative = _safe_runtime_relative(record.get("path"), field="code path")
+        if relative in declared:
+            raise RuntimeBindingError(
+                "SOURCE_INVENTORY_INVALID", f"duplicate code path: {relative}"
+            )
+        declared[relative] = record
+
+    raw_code = Path(raw_code)
+    actual = {
+        path.relative_to(raw_code).as_posix(): path
+        for path in sorted(raw_code.rglob("*"))
+        if path.is_file()
+    }
+    if set(actual) != set(declared):
+        raise RuntimeBindingError(
+            "SOURCE_INVENTORY_MISMATCH",
+            "raw_code file set no longer matches the locked package",
+        )
+    source_hashes: dict[str, str] = {}
+    raw_code_root = raw_code.resolve()
+    for relative, source in actual.items():
+        if source.is_symlink():
+            raise RuntimeBindingError(
+                "SOURCE_SYMLINK_UNSAFE", f"raw code must not be a symlink: {relative}"
+            )
+        try:
+            source.resolve().relative_to(raw_code_root)
+        except ValueError as exc:
+            raise RuntimeBindingError(
+                "SOURCE_PATH_ESCAPE", f"raw code escapes its package: {relative}"
+            ) from exc
+        digest = _sha256_file(source)
+        if digest != declared[relative].get("sha256"):
+            raise RuntimeBindingError(
+                "SOURCE_HASH_MISMATCH", f"raw code changed after baseline: {relative}"
+            )
+        source_hashes[relative] = digest
+    return declared, source_hashes
+
+
+def _binding_replacements(
+    contract: dict[str, Any], resolved: dict[str, Any]
+) -> tuple[dict[str, str], dict[str, dict[str, list[str]]]]:
+    requested: dict[str, str] = {}
+    patchable = {
+        target.get("binding_key")
+        for target in contract.get("patch_targets", [])
+        if isinstance(target, dict)
+    }
+    patched_path_roots: list[tuple[str, str]] = []
+
+    def add(binding_key: str, original: str, replacement: str) -> None:
+        if replacement == original:
+            return
+        previous = requested.get(binding_key)
+        if previous is not None and previous != replacement:
+            raise RuntimeBindingError(
+                "PATCH_REPLACEMENT_CONFLICT",
+                f"one binding resolves to different values: {binding_key}",
+            )
+        requested[binding_key] = replacement
+
+    for binding in resolved.get("input_bindings", []):
+        original = str(binding.get("original_path") or "")
+        runtime = Path(str(binding.get("runtime_path") or ""))
+        binding_key = f"path:{original}"
+        replacement = runtime.name
+        add(binding_key, original, replacement)
+        if replacement != original and binding_key in patchable:
+            patched_path_roots.append((original, replacement))
+
+    prefix = resolved.get("prefix_binding")
+    if isinstance(prefix, dict):
+        old_prefix = prefix.get("old_prefix")
+        new_prefix = prefix.get("new_prefix")
+        if isinstance(old_prefix, str) and isinstance(new_prefix, str):
+            for reference in contract.get("path_references", []):
+                if not isinstance(reference, dict):
+                    continue
+                fact_id = str(reference.get("fact_id") or "")
+                original = str(reference.get("path") or "")
+                if not fact_id or not _output_has_prefix(original, old_prefix):
+                    continue
+                replacement = _replace_output_prefix(
+                    original, old_prefix, new_prefix
+                )
+                binding_key = f"path_reference:{fact_id}"
+                add(binding_key, original, replacement)
+                if replacement != original and binding_key in patchable:
+                    patched_path_roots.append((original, replacement))
+
+    def covered_by_patched_root(original: str, runtime: str) -> bool:
+        for old_root, new_root in patched_path_roots:
+            if original == old_root:
+                suffix = ""
+            elif (
+                original.startswith(old_root)
+                and len(original) > len(old_root)
+                and original[len(old_root)] in _PREFIX_DELIMITERS
+            ):
+                suffix = original[len(old_root) :]
+            else:
+                continue
+            if runtime == new_root + suffix:
+                return True
+        return False
+
+    for binding in resolved.get("output_bindings", []):
+        original = str(binding.get("original_path") or "")
+        runtime = _safe_runtime_relative(
+            binding.get("runtime_path"), field="runtime output path"
+        )
+        binding_key = f"path:{original}"
+        if runtime == original:
+            continue
+        if binding_key in patchable:
+            add(binding_key, original, runtime)
+        elif covered_by_patched_root(original, runtime):
+            continue
+        else:
+            add(binding_key, original, runtime)
+    for binding in resolved.get("parameter_bindings", []):
+        fact_id = str(binding.get("fact_id") or "")
+        original = str(binding.get("original_value") or "")
+        runtime = str(binding.get("runtime_value") or "")
+        if not fact_id or not runtime or _has_control(runtime):
+            raise RuntimeBindingError(
+                "PARAMETER_VALUE_INVALID", f"unsafe runtime parameter: {fact_id}"
+            )
+        add(f"parameter:{fact_id}", original, runtime)
+
+    targets_by_key = {
+        str(target.get("binding_key") or ""): target
+        for section in ("patch_targets", "unpatchable_targets")
+        for target in contract.get(section, [])
+        if isinstance(target, dict) and target.get("binding_key")
+    }
+    patchable_by_literal: dict[str, list[str]] = {}
+    for target in contract.get("patch_targets", []):
+        if not isinstance(target, dict):
+            continue
+        key = str(target.get("binding_key") or "")
+        literal = str(target.get("original_literal") or "")
+        if key and literal:
+            patchable_by_literal.setdefault(literal, []).append(key)
+
+    alias_coverage: dict[str, dict[str, list[str]]] = {}
+    for binding_key in list(requested):
+        if binding_key not in patchable:
+            target = targets_by_key.get(binding_key, {})
+            literal = str(target.get("original_literal") or "")
+            candidates = [
+                key
+                for key in patchable_by_literal.get(literal, [])
+                if key in requested
+            ]
+            matching = [
+                key
+                for key in candidates
+                if requested[key] == requested[binding_key]
+            ]
+            if matching:
+                owner = sorted(matching)[0]
+                evidence = alias_coverage.setdefault(
+                    owner,
+                    {"covered_binding_keys": [], "covered_fact_ids": []},
+                )
+                evidence["covered_binding_keys"].append(binding_key)
+                evidence["covered_fact_ids"].extend(
+                    str(fact_id)
+                    for fact_id in target.get("fact_ids", [])
+                    if isinstance(fact_id, str)
+                )
+                del requested[binding_key]
+                continue
+            if candidates:
+                raise RuntimeBindingError(
+                    "PATCH_REPLACEMENT_CONFLICT",
+                    f"same literal resolves to different values: {literal}",
+                )
+            raise RuntimeBindingError(
+                "PATCH_TARGET_UNAVAILABLE",
+                f"changed binding has no safe shell patch target: {binding_key}",
+            )
+    for evidence in alias_coverage.values():
+        evidence["covered_binding_keys"] = sorted(
+            set(evidence["covered_binding_keys"])
+        )
+        evidence["covered_fact_ids"] = sorted(set(evidence["covered_fact_ids"]))
+    return requested, alias_coverage
+
+
+def _shell_word_pattern(literal: str) -> re.Pattern[str]:
+    return re.compile(
+        rf"(?<![{_SHELL_WORD_EDGE}])"
+        rf"(?P<quote>['\"]?){re.escape(literal)}(?P=quote)"
+        rf"(?![{_SHELL_WORD_EDGE}])"
+    )
+
+
+def _script_positional_args(contract: dict[str, Any], script: str) -> list[str]:
+    try:
+        tokens = shlex.split(str(contract.get("original_command") or ""))
+    except ValueError as exc:
+        raise RuntimeBindingError(
+            "PATCH_ANCHOR_MISMATCH", "entry command cannot be tokenized"
+        ) from exc
+    normalized_script = str(PurePosixPath(script))
+    for index, token in enumerate(tokens):
+        normalized_token = str(PurePosixPath(token))
+        while normalized_token.startswith("./"):
+            normalized_token = normalized_token[2:]
+        if normalized_token == normalized_script:
+            return tokens[index + 1 :]
+    raise RuntimeBindingError(
+        "PATCH_ANCHOR_MISMATCH",
+        f"patch script is not the locked entry script: {script}",
+    )
+
+
+def _anchor_command(
+    commands: list[str], anchor: dict[str, Any], literal: str
+) -> tuple[int, int]:
+    step_id = anchor.get("step_id")
+    match = re.fullmatch(r"step_(\d+)", str(step_id or ""))
+    if match is None:
+        raise RuntimeBindingError(
+            "PATCH_ANCHOR_MISMATCH", f"invalid patch step: {step_id}"
+        )
+    step_index = int(match.group(1)) - 1
+    if step_index < 0 or step_index >= len(commands):
+        raise RuntimeBindingError(
+            "PATCH_ANCHOR_MISMATCH", f"patch step is missing: {step_id}"
+        )
+    command = commands[step_index]
+    digest = hashlib.sha256(command.encode("utf-8")).hexdigest()
+    if digest != anchor.get("command_digest"):
+        raise RuntimeBindingError(
+            "PATCH_ANCHOR_MISMATCH", f"patch command changed: {step_id}"
+        )
+    try:
+        token_index = int(anchor.get("token_index"))
+        tokens = shlex.split(command)
+    except (TypeError, ValueError) as exc:
+        raise RuntimeBindingError(
+            "PATCH_ANCHOR_MISMATCH", f"patch token is invalid: {step_id}"
+        ) from exc
+    if token_index < 0 or token_index >= len(tokens) or tokens[token_index] != literal:
+        raise RuntimeBindingError(
+            "PATCH_ANCHOR_MISMATCH",
+            f"patch literal is not at its locked token: {step_id}:{token_index}",
+        )
+    return step_index, token_index
+
+
+def _validate_patch_anchors_before(
+    commands: list[str], targets: list[dict[str, Any]]
+) -> None:
+    for target in targets:
+        literal = str(target.get("original_literal") or "")
+        anchors = target.get("anchors")
+        if not isinstance(anchors, list) or not anchors:
+            raise RuntimeBindingError(
+                "PATCH_ANCHOR_MISMATCH",
+                f"patch target has no command anchor: {literal}",
+            )
+        for anchor in anchors:
+            if not isinstance(anchor, dict):
+                raise RuntimeBindingError(
+                    "PATCH_ANCHOR_MISMATCH", f"invalid patch anchor: {literal}"
+                )
+            _anchor_command(commands, anchor, literal)
+
+
+def _validate_patch_anchors_after(
+    before: list[str],
+    after: list[str],
+    targets: list[dict[str, Any]],
+    replacements: dict[str, str],
+) -> None:
+    if len(after) != len(before):
+        raise RuntimeBindingError(
+            "PATCH_ANCHOR_MISMATCH", "patch changed the logical command count"
+        )
+    for target in targets:
+        replacement = replacements[str(target["binding_key"])]
+        for anchor in target["anchors"]:
+            match = re.fullmatch(r"step_(\d+)", str(anchor.get("step_id") or ""))
+            if match is None:
+                raise RuntimeBindingError(
+                    "PATCH_ANCHOR_MISMATCH", "invalid post-patch step"
+                )
+            step_index = int(match.group(1)) - 1
+            token_index = int(anchor.get("token_index"))
+            try:
+                tokens = shlex.split(after[step_index])
+            except (IndexError, ValueError) as exc:
+                raise RuntimeBindingError(
+                    "PATCH_ANCHOR_MISMATCH", "post-patch command cannot be tokenized"
+                ) from exc
+            if token_index >= len(tokens) or tokens[token_index] != replacement:
+                raise RuntimeBindingError(
+                    "PATCH_ANCHOR_MISMATCH",
+                    "patched value is not at the locked command token",
+                )
+
+
+def _render_script_updates(
+    contract: dict[str, Any],
+    raw_code: Path,
+    replacements: dict[str, str],
+    alias_coverage: dict[str, dict[str, list[str]]],
+) -> tuple[dict[str, str], list[dict[str, Any]]]:
+    selected = [
+        target
+        for target in contract.get("patch_targets", [])
+        if isinstance(target, dict)
+        and target.get("binding_key") in replacements
+    ]
+    by_literal: dict[str, str] = {}
+    for target in selected:
+        literal = str(target.get("original_literal") or "")
+        replacement = replacements[str(target["binding_key"])]
+        previous = by_literal.get(literal)
+        if previous is not None and previous != replacement:
+            raise RuntimeBindingError(
+                "PATCH_REPLACEMENT_CONFLICT",
+                f"literal has conflicting runtime values: {literal}",
+            )
+        by_literal[literal] = replacement
+
+    grouped: dict[str, list[dict[str, Any]]] = {}
+    for target in selected:
+        script = _safe_runtime_relative(
+            target.get("script_path"), field="patch script path"
+        )
+        grouped.setdefault(script, []).append(target)
+
+    rendered: dict[str, str] = {}
+    patch_diff: list[dict[str, Any]] = []
+    for script, targets in sorted(grouped.items()):
+        source = raw_code / script
+        if not source.is_file():
+            raise RuntimeBindingError(
+                "PATCH_TARGET_MISSING", f"patch script does not exist: {script}"
+            )
+        source_hash = _sha256_file(source)
+        if any(target.get("script_hash") != source_hash for target in targets):
+            raise RuntimeBindingError(
+                "SOURCE_HASH_MISMATCH", f"patch script hash changed: {script}"
+            )
+        text = source.read_text(encoding="utf-8", errors="replace")
+        positional_args = _script_positional_args(contract, script)
+        before_commands = _prepare_script_commands(text, positional_args)
+        _validate_patch_anchors_before(before_commands, targets)
+        seen: set[tuple[str, str]] = set()
+        for target in targets:
+            literal = str(target.get("original_literal") or "")
+            replacement = replacements[str(target["binding_key"])]
+            identity = (literal, replacement)
+            if identity in seen:
+                continue
+            seen.add(identity)
+            try:
+                expected = int(target.get("expected_exact_match_count"))
+            except (TypeError, ValueError) as exc:
+                raise RuntimeBindingError(
+                    "PATCH_TARGET_INVALID", f"invalid match count for {literal}"
+                ) from exc
+            if expected < 1:
+                raise RuntimeBindingError(
+                    "PATCH_TARGET_INVALID", f"invalid match count for {literal}"
+                )
+            updated, count = _shell_word_pattern(literal).subn(
+                shlex.quote(replacement), text
+            )
+            if count != expected:
+                raise RuntimeBindingError(
+                    "PATCH_MATCH_COUNT_MISMATCH",
+                    f"expected {expected} exact matches for {literal} in {script}, found {count}",
+                )
+            text = updated
+            binding_key = str(target["binding_key"])
+            patch_diff.append(
+                {
+                    "script_path": script,
+                    "binding_key": binding_key,
+                    "patch_kind": target.get("patch_kind"),
+                    "original_literal": literal,
+                    "runtime_literal": replacement,
+                    "replacement_count": count,
+                    **alias_coverage.get(binding_key, {}),
+                }
+            )
+        after_commands = _prepare_script_commands(text, positional_args)
+        _validate_patch_anchors_after(
+            before_commands, after_commands, targets, replacements
+        )
+        rendered[script] = text
+    return rendered, patch_diff
+
+
+def _input_materialization_plan(
+    contract: dict[str, Any], resolved: dict[str, Any], code_paths: set[str]
+) -> list[dict[str, Any]]:
+    modified_originals = {
+        str(binding.get("original_path") or "")
+        for binding in resolved.get("output_bindings", [])
+    }
+    used: set[str] = set()
+    plan: list[dict[str, Any]] = []
+    for binding in resolved.get("input_bindings", []):
+        original = str(binding.get("original_path") or "")
+        lexical_source = Path(str(binding.get("runtime_path") or ""))
+        source = lexical_source.resolve()
+        if not source.is_file():
+            raise RuntimeBindingError(
+                "INPUT_PATH_NOT_FOUND", f"runtime input does not exist: {source}"
+            )
+        destination = lexical_source.name
+        _safe_runtime_relative(destination, field="materialized input path")
+        if destination in {".", ".."} or destination.startswith("-"):
+            raise RuntimeBindingError(
+                "UNSAFE_INPUT_BASENAME",
+                f"runtime input basename is unsafe as a shell word: {destination}",
+            )
+        if destination in used or destination in code_paths:
+            raise RuntimeBindingError(
+                "RUNTIME_PATH_COLLISION",
+                f"runtime input basename collides in work directory: {destination}",
+            )
+        used.add(destination)
+        plan.append(
+            {
+                "original_path": original,
+                "runtime_path": str(lexical_source),
+                "materialized_path": destination,
+                "method": "copy" if original in modified_originals else "symlink",
+                "sha256": _sha256_file(source),
+            }
+        )
+    return plan
+
+
+def render_runtime_package(
+    contract: dict[str, Any],
+    raw_code: Path,
+    resolved: dict[str, Any],
+    run_dir: Path,
+) -> dict[str, Any]:
+    """Render a resolved binding into a job-local package without executing it."""
+
+    raw_code = Path(raw_code)
+    _declared, source_hashes = _validate_render_inputs(
+        contract, raw_code, resolved
+    )
+    materialization = _input_materialization_plan(
+        contract, resolved, set(source_hashes)
+    )
+    replacements, alias_coverage = _binding_replacements(contract, resolved)
+    script_updates, patch_diff = _render_script_updates(
+        contract, raw_code, replacements, alias_coverage
+    )
+
+    expected_outputs: list[dict[str, Any]] = []
+    materialized_by_original = {
+        item["original_path"]: item["materialized_path"]
+        for item in materialization
+    }
+    for binding in resolved.get("output_bindings", []):
+        runtime_path = _safe_runtime_relative(
+            binding.get("runtime_path"), field="runtime output path"
+        )
+        if runtime_path in source_hashes:
+            raise RuntimeBindingError(
+                "RUNTIME_PATH_COLLISION",
+                f"runtime output collides with code: {runtime_path}",
+            )
+        original_path = str(binding.get("original_path") or "")
+        input_path = materialized_by_original.get(original_path)
+        if runtime_path in set(materialized_by_original.values()) and runtime_path != input_path:
+            raise RuntimeBindingError(
+                "RUNTIME_PATH_COLLISION",
+                f"runtime output collides with another input: {runtime_path}",
+            )
+        expected_outputs.append(
+            {
+                "fact_id": binding.get("fact_id"),
+                "original_path": original_path,
+                "runtime_path": runtime_path,
+            }
+        )
+
+    command = contract.get("original_command")
+    if (
+        not isinstance(command, str)
+        or not command.strip()
+        or _has_control(command.replace("\n", ""))
+    ):
+        raise RuntimeBindingError(
+            "ENTRY_COMMAND_INVALID", "binding contract has no executable command"
+        )
+    run_dir = Path(run_dir)
+    if run_dir.exists() and any(run_dir.iterdir()):
+        raise RuntimeBindingError(
+            "RUN_DIRECTORY_NOT_EMPTY", f"runtime directory is not empty: {run_dir}"
+        )
+    work_dir = run_dir / "work"
+    work_dir.mkdir(parents=True, exist_ok=True)
+    for relative in sorted(source_hashes):
+        destination = work_dir / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(raw_code / relative, destination)
+        if _sha256_file(destination) != source_hashes[relative]:
+            raise RuntimeBindingError(
+                "SOURCE_COPY_HASH_MISMATCH",
+                f"copied code does not match its locked source: {relative}",
+            )
+    for script, text in script_updates.items():
+        (work_dir / script).write_text(text, encoding="utf-8")
+    for item in materialization:
+        destination = work_dir / item["materialized_path"]
+        source = Path(item["runtime_path"])
+        if item["method"] == "copy":
+            shutil.copy2(source, destination)
+        else:
+            destination.symlink_to(source)
+
+    locked_work_hashes = {
+        relative: _sha256_file(work_dir / relative)
+        for relative in sorted(source_hashes)
+    }
+
+    record = {
+        "schema_version": "lightweight-runtime-package/v1",
+        "status": "rendered",
+        "facts_sha256": contract.get("facts_sha256"),
+        "package_digest": contract.get("package_digest"),
+        "binding_digest": resolved.get("binding_digest"),
+        "original_command": command,
+        "actual_command": command,
+        "run_dir": str(run_dir.resolve()),
+        "work_dir": str(work_dir.resolve()),
+        "source_hashes": source_hashes,
+        "locked_work_hashes": locked_work_hashes,
+        "render_work_tree": _work_tree_manifest(work_dir),
+        "input_materialization": materialization,
+        "patch_diff": patch_diff,
+        "expected_outputs": expected_outputs,
+        "stdout_contract": deepcopy(
+            contract.get("outputs", {}).get("stdout", {})
+        ),
+    }
+    record["record_digest"] = _digest_without(record, "record_digest")
+    record_path = run_dir / "runtime_binding_record.json"
+    record_path.write_text(
+        json.dumps(record, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return record
+
+
+def _event(event: str, **details: Any) -> dict[str, Any]:
+    return {
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "event": event,
+        **details,
+    }
+
+
+_UNSAFE_ENV_KEYS = {
+    "BASH_ENV",
+    "ENV",
+    "SHELLOPTS",
+    "BASHOPTS",
+    "CDPATH",
+    "GLOBIGNORE",
+    "PS4",
+    "PROMPT_COMMAND",
+    "LD_PRELOAD",
+    "LD_AUDIT",
+}
+
+
+def _unsafe_env_key(key: str) -> bool:
+    return key in _UNSAFE_ENV_KEYS or key.startswith("BASH_FUNC_")
+
+
+def _validate_tool_path(value: str, *, filter_invalid: bool) -> list[str]:
+    entries: list[str] = []
+    for raw_entry in value.split(os.pathsep):
+        valid = bool(raw_entry) and not _has_control(raw_entry)
+        path = Path(raw_entry) if valid else None
+        valid = bool(path is not None and path.is_absolute())
+        try:
+            resolved = path.resolve(strict=True) if valid and path is not None else None
+        except OSError:
+            resolved = None
+        valid = bool(resolved is not None and resolved.is_dir())
+        if not valid:
+            if filter_invalid:
+                continue
+            raise RuntimeBindingError(
+                "UNSAFE_TOOL_PATH",
+                f"PATH entry must be one existing absolute directory: {raw_entry!r}",
+            )
+        canonical = str(resolved)
+        if canonical not in entries:
+            entries.append(canonical)
+    if not entries:
+        raise RuntimeBindingError(
+            "UNSAFE_TOOL_PATH", "PATH contains no valid absolute tool directory"
+        )
+    return entries
+
+
+def _process_environment(
+    env: dict[str, str] | None,
+) -> tuple[dict[str, str], list[str], str]:
+    supplied = {str(key): str(value) for key, value in (env or {}).items()}
+    unsafe = sorted(key for key in supplied if _unsafe_env_key(key))
+    if unsafe:
+        raise RuntimeBindingError(
+            "UNSAFE_ENVIRONMENT",
+            f"runtime environment contains a shell injection key: {unsafe[0]}",
+        )
+    process_env = {
+        key: value for key, value in os.environ.items() if not _unsafe_env_key(key)
+    }
+    explicit_tool_path = "PATH" in supplied
+    tool_path_entries = _validate_tool_path(
+        supplied.get("PATH", process_env.get("PATH", "")),
+        filter_invalid=not explicit_tool_path,
+    )
+    process_env.update({key: value for key, value in supplied.items() if key != "PATH"})
+    process_env["PATH"] = os.pathsep.join(tool_path_entries)
+    return process_env, tool_path_entries, _sha256_json(tool_path_entries)
+
+
+def _trusted_bash() -> Path:
+    for candidate in (Path("/usr/bin/bash"), Path("/bin/bash")):
+        try:
+            resolved = candidate.resolve(strict=True)
+        except OSError:
+            continue
+        if (
+            resolved.is_file()
+            and os.access(resolved, os.X_OK)
+            and resolved.parent in {Path("/usr/bin"), Path("/bin")}
+        ):
+            return resolved
+    raise RuntimeBindingError(
+        "TRUSTED_BASH_NOT_FOUND", "no trusted absolute system Bash is available"
+    )
+
+
+def _absolute_entry_bash(command: str, bash_path: Path) -> str:
+    return re.sub(
+        r"^\s*(?:bash|/bin/bash|/usr/bin/bash)(?=\s)",
+        shlex.quote(str(bash_path)),
+        command,
+        count=1,
+    )
+
+
+def _work_tree_manifest(root: Path) -> dict[str, dict[str, Any]]:
+    manifest: dict[str, dict[str, Any]] = {}
+    for path in sorted(root.rglob("*")):
+        relative = path.relative_to(root).as_posix()
+        _safe_runtime_relative(relative, field="work tree path")
+        if path.is_symlink():
+            manifest[relative] = {
+                "type": "symlink",
+                "target": os.readlink(path),
+            }
+        elif path.is_dir():
+            manifest[relative] = {"type": "directory"}
+        elif path.is_file():
+            manifest[relative] = {
+                "type": "regular",
+                "sha256": _sha256_file(path),
+            }
+        else:
+            raise RuntimeBindingError(
+                "WORK_TREE_UNSUPPORTED",
+                f"unsupported work tree entry: {relative}",
+            )
+    return manifest
+
+
+def _verify_render_work_tree(
+    rendered_package: dict[str, Any], work_dir: Path
+) -> None:
+    if _work_tree_manifest(work_dir) != rendered_package.get("render_work_tree"):
+        raise RuntimeBindingError(
+            "WORK_TREE_CHANGED",
+            "runtime work tree changed after package rendering",
+        )
+
+
+def _load_and_validate_render_record(
+    rendered_package: dict[str, Any],
+) -> tuple[Path, Path]:
+    if (
+        rendered_package.get("schema_version")
+        != "lightweight-runtime-package/v1"
+        or rendered_package.get("status") != "rendered"
+    ):
+        raise RuntimeBindingError(
+            "RENDERED_PACKAGE_INVALID", "runtime package is not ready to execute"
+        )
+    run_dir = Path(str(rendered_package.get("run_dir") or ""))
+    work_dir = Path(str(rendered_package.get("work_dir") or ""))
+    if (
+        not work_dir.is_dir()
+        or work_dir.resolve() != (run_dir.resolve() / "work")
+    ):
+        raise RuntimeBindingError(
+            "RENDERED_PACKAGE_INVALID", "work directory is missing or detached"
+        )
+    record_path = run_dir / "runtime_binding_record.json"
+    try:
+        disk_record = json.loads(record_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        raise RuntimeBindingError(
+            "RECORD_MISSING", "runtime binding record cannot be loaded"
+        ) from exc
+    if disk_record.get("record_digest") != _digest_without(
+        disk_record, "record_digest"
+    ):
+        raise RuntimeBindingError(
+            "RECORD_DIGEST_MISMATCH", "runtime binding record was modified"
+        )
+    if rendered_package.get("record_digest") != _digest_without(
+        rendered_package, "record_digest"
+    ):
+        raise RuntimeBindingError(
+            "RECORD_DIGEST_MISMATCH", "in-memory runtime binding record is invalid"
+        )
+    if disk_record != rendered_package:
+        raise RuntimeBindingError(
+            "RECORD_MISMATCH", "disk and in-memory runtime binding records differ"
+        )
+    if rendered_package.get("actual_command") != rendered_package.get(
+        "original_command"
+    ):
+        raise RuntimeBindingError(
+            "ENTRY_COMMAND_CHANGED", "actual command differs from the locked entry command"
+        )
+    return run_dir, work_dir
+
+
+def _verify_locked_work(rendered_package: dict[str, Any], work_dir: Path) -> None:
+    for relative, expected in rendered_package.get("locked_work_hashes", {}).items():
+        safe = _safe_runtime_relative(relative, field="locked work path")
+        path = work_dir / safe
+        if not path.is_file() or path.is_symlink() or _sha256_file(path) != expected:
+            raise RuntimeBindingError(
+                "WORK_PACKAGE_CHANGED", f"locked work file changed: {safe}"
+            )
+
+
+def _verify_runtime_inputs(
+    rendered_package: dict[str, Any], work_dir: Path, *, after: bool
+) -> None:
+    for item in rendered_package.get("input_materialization", []):
+        source = Path(str(item.get("runtime_path") or ""))
+        materialized = work_dir / _safe_runtime_relative(
+            item.get("materialized_path"), field="materialized input path"
+        )
+        expected = item.get("sha256")
+        if not source.is_file() or _sha256_file(source) != expected:
+            raise RuntimeBindingError(
+                "INPUT_CONTENT_CHANGED",
+                f"runtime input content changed: {source}",
+            )
+        if after:
+            continue
+        if not materialized.is_file() or _sha256_file(materialized) != expected:
+            raise RuntimeBindingError(
+                "INPUT_CONTENT_CHANGED",
+                f"materialized input content changed: {materialized}",
+            )
+
+
+def _isolate_runtime_inputs(
+    rendered_package: dict[str, Any], work_dir: Path
+) -> list[dict[str, str]]:
+    execution_inputs: list[dict[str, str]] = []
+    for item in rendered_package.get("input_materialization", []):
+        source = Path(str(item.get("runtime_path") or ""))
+        relative = _safe_runtime_relative(
+            item.get("materialized_path"), field="materialized input path"
+        )
+        destination = work_dir / relative
+        if item.get("method") == "symlink":
+            file_descriptor, temporary_name = tempfile.mkstemp(
+                prefix=".bbav5-input-", dir=destination.parent
+            )
+            os.close(file_descriptor)
+            temporary = Path(temporary_name)
+            try:
+                shutil.copy2(source, temporary)
+                if _sha256_file(temporary) != item.get("sha256"):
+                    raise RuntimeBindingError(
+                        "INPUT_CONTENT_CHANGED",
+                        f"isolated input copy does not match source: {source}",
+                    )
+                os.replace(temporary, destination)
+            finally:
+                if temporary.exists():
+                    temporary.unlink()
+        elif item.get("method") != "copy":
+            raise RuntimeBindingError(
+                "RENDERED_PACKAGE_INVALID",
+                f"unknown input materialization method: {item.get('method')}",
+            )
+        if not destination.is_file() or destination.is_symlink():
+            raise RuntimeBindingError(
+                "INPUT_ISOLATION_FAILED", f"input is not an isolated copy: {relative}"
+            )
+        execution_inputs.append(
+            {
+                "materialized_path": relative,
+                "mode": "isolated_copy",
+                "source_path": str(source),
+            }
+        )
+    return execution_inputs
+
+
+def replay_runtime_binding(
+    rendered_package: dict[str, Any],
+    env: dict[str, str] | None = None,
+    on_process_start: Callable[[ProcessIdentity], None] | None = None,
+) -> dict[str, Any]:
+    """Execute one rendered package and validate only its declared results."""
+
+    run_dir, work_dir = _load_and_validate_render_record(rendered_package)
+    command = rendered_package.get("actual_command")
+    if not isinstance(command, str) or not command.strip():
+        raise RuntimeBindingError(
+            "ENTRY_COMMAND_INVALID", "rendered package has no actual command"
+        )
+    process_env, tool_path_entries, tool_path_digest = _process_environment(env)
+    bash_path = _trusted_bash()
+    execution_command = _absolute_entry_bash(command, bash_path)
+    _verify_locked_work(rendered_package, work_dir)
+    _verify_render_work_tree(rendered_package, work_dir)
+    _verify_runtime_inputs(rendered_package, work_dir, after=False)
+    execution_inputs = _isolate_runtime_inputs(rendered_package, work_dir)
+    _verify_runtime_inputs(rendered_package, work_dir, after=True)
+    execution_work_tree = _work_tree_manifest(work_dir)
+
+    before = inventory_files(work_dir)
+    logs_dir = run_dir / "logs"
+    logs_dir.mkdir(parents=True, exist_ok=True)
+    stdout_path = logs_dir / "stdout.log"
+    stderr_path = logs_dir / "stderr.log"
+    events_path = logs_dir / "execution_events.jsonl"
+    event_start = _event(
+        "start",
+        command=execution_command,
+        bash_path=str(bash_path),
+        tool_path_digest=tool_path_digest,
+        tool_path_entries=tool_path_entries,
+        execution_inputs=execution_inputs,
+        execution_work_tree=execution_work_tree,
+    )
+    with stdout_path.open("wb") as stdout_handle, stderr_path.open("wb") as stderr_handle:
+        process, process_identity = start_managed_process(
+            [str(bash_path), "-c", execution_command],
+            cwd=work_dir,
+            env=process_env,
+            stdout=stdout_handle,
+            stderr=stderr_handle,
+        )
+        event_start["process"] = process_identity
+        events_path.write_text(
+            json.dumps(event_start, ensure_ascii=False) + "\n", encoding="utf-8"
+        )
+        try:
+            if on_process_start is not None:
+                on_process_start(dict(process_identity))
+        except BaseException:
+            stop_process_group(process_identity)
+            process.wait()
+            raise
+        returncode = process.wait()
+    after = inventory_files(work_dir)
+    missing_outputs: list[str] = []
+    outputs: list[dict[str, Any]] = []
+    for expected in rendered_package.get("expected_outputs", []):
+        relative = _safe_runtime_relative(
+            expected.get("runtime_path"), field="expected output path"
+        )
+        record = after.get(relative)
+        if record is None or (
+            relative in before
+            and before[relative].get("sha256") == record.get("sha256")
+        ):
+            missing_outputs.append(relative)
+            continue
+        outputs.append(
+            {
+                "fact_id": expected.get("fact_id"),
+                "runtime_path": relative,
+                "status": "modified" if relative in before else "new",
+                "size": record["size"],
+                "sha256": record["sha256"],
+            }
+        )
+    stdout_required = bool(
+        rendered_package.get("stdout_contract", {}).get("present")
+    )
+    stdout_ok = not stdout_required or stdout_path.stat().st_size > 0
+    success = returncode == 0
+    post_input_error: RuntimeBindingError | None = None
+    try:
+        _verify_runtime_inputs(rendered_package, work_dir, after=True)
+    except RuntimeBindingError as exc:
+        post_input_error = exc
+    contract_passed = bool(
+        success and not missing_outputs and stdout_ok and post_input_error is None
+    )
+    if post_input_error is not None:
+        failure_type = post_input_error.code
+    elif not success:
+        failure_type = "execution_failed"
+    elif missing_outputs:
+        failure_type = "missing_outputs"
+    elif not stdout_ok:
+        failure_type = "stdout_missing"
+    else:
+        failure_type = None
+    result_path = run_dir / "runtime_execution_result.json"
+    result = {
+        "success": success,
+        "returncode": returncode,
+        "process": process_identity,
+        "contract_passed": contract_passed,
+        "missing_outputs": missing_outputs,
+        "outputs": outputs,
+        "stdout_contract_passed": stdout_ok,
+        "failure_type": failure_type,
+        "bash_path": str(bash_path),
+        "execution_command": execution_command,
+        "tool_path_digest": tool_path_digest,
+        "tool_path_entries": tool_path_entries,
+        "execution_inputs": execution_inputs,
+        "execution_work_tree": execution_work_tree,
+        "before_files": before,
+        "after_files": after,
+        "logs": {
+            "stdout": str(stdout_path),
+            "stderr": str(stderr_path),
+            "events": str(events_path),
+            "result": str(result_path),
+        },
+    }
+    result_path.write_text(
+        json.dumps(result, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    with events_path.open("a", encoding="utf-8") as handle:
+        handle.write(
+            json.dumps(
+                _event(
+                    "finish",
+                    returncode=returncode,
+                    contract_passed=contract_passed,
+                    missing_outputs=missing_outputs,
+                    failure_type=failure_type,
+                    bash_path=str(bash_path),
+                    tool_path_digest=tool_path_digest,
+                    tool_path_entries=tool_path_entries,
+                    execution_inputs=execution_inputs,
+                    execution_work_tree=execution_work_tree,
+                ),
+                ensure_ascii=False,
+            )
+            + "\n"
+        )
+    if post_input_error is not None:
+        raise post_input_error
+    return result
diff --git a/gfa_core/extension_stage_lightweight/semantic_model.py b/gfa_core/extension_stage_lightweight/semantic_model.py
new file mode 100644
index 000000000..325826fa1
--- /dev/null
+++ b/gfa_core/extension_stage_lightweight/semantic_model.py
@@ -0,0 +1,410 @@
+"""Validate semantic annotations without allowing execution-fact rewrites."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+
+_TOP_LEVEL_FIELDS = {
+    "facts_sha256",
+    "function_summary",
+    "inputs",
+    "parameters",
+    "outputs",
+}
+_SECTION_FIELDS = {
+    "inputs": {
+        "fact_id",
+        "role",
+        "description",
+        "replaceability",
+    },
+    "parameters": {
+        "fact_id",
+        "display_name",
+        "description",
+    },
+    "outputs": {
+        "fact_id",
+        "description",
+        "result_role",
+    },
+}
+_ENUMS = {
+    ("inputs", "replaceability"): {
+        "replaceable",
+        "fixed_resource",
+        "generated",
+    },
+    ("outputs", "result_role"): {"final", "intermediate", "log", "unknown"},
+}
+
+
+class SemanticCandidateError(ValueError):
+    """Raised when a semantic candidate does not satisfy its fact contract."""
+
+    def __init__(self, errors: list[dict[str, str]]) -> None:
+        self.errors = deepcopy(errors)
+        summary = "; ".join(error["message"] for error in errors)
+        super().__init__(f"Invalid semantic candidate: {summary}")
+
+
+def _error(field: str, code: str, message: str) -> dict[str, str]:
+    return {"field": field, "code": code, "message": message}
+
+
+def _expected_fact_ids(facts: dict[str, Any]) -> dict[str, set[str]]:
+    expected = {"inputs": set(), "parameters": set(), "outputs": set()}
+    for command in facts.get("commands", []):
+        expected["inputs"].update(
+            item["fact_id"] for item in command.get("inputs", [])
+        )
+        expected["parameters"].update(
+            item["fact_id"] for item in command.get("parameters", [])
+        )
+    expected["outputs"].update(
+        item["fact_id"] for item in facts.get("outputs", {}).get("files", [])
+    )
+    stdout = facts.get("outputs", {}).get("stdout", {})
+    if stdout.get("present"):
+        expected["outputs"].add(stdout["fact_id"])
+    return expected
+
+
+def _fact_records_by_section(facts: dict[str, Any]) -> dict[str, list[dict[str, Any]]]:
+    records = {
+        "inputs": [
+            item
+            for command in facts.get("commands", [])
+            for item in command.get("inputs", [])
+        ],
+        "parameters": [
+            item
+            for command in facts.get("commands", [])
+            for item in command.get("parameters", [])
+        ],
+        "outputs": list(facts.get("outputs", {}).get("files", [])),
+    }
+    stdout = facts.get("outputs", {}).get("stdout", {})
+    if stdout.get("present"):
+        records["outputs"].append(stdout)
+    return records
+
+
+def _missing_semantic_row(section: str, fact: dict[str, Any]) -> dict[str, str]:
+    fact_id = fact["fact_id"]
+    if section == "inputs":
+        path = fact.get("path", fact_id)
+        return {
+            "fact_id": fact_id,
+            "role": f"Locked input: {path}.",
+            "description": f"Observed input file: {path}.",
+            "replaceability": (
+                "generated"
+                if fact.get("source") == "generated_input"
+                else "replaceable"
+            ),
+        }
+    if section == "parameters":
+        value = fact.get("value", fact_id)
+        return {
+            "fact_id": fact_id,
+            "display_name": f"Locked parameter: {value}.",
+            "description": f"Observed command parameter: {value}.",
+        }
+    if "path" in fact:
+        description = f"Observed output file: {fact['path']}."
+    else:
+        description = "Observed standard output."
+    return {
+        "fact_id": fact_id,
+        "description": description,
+        "result_role": "unknown",
+    }
+
+
+def bind_fact_derived_semantics(
+    facts: dict[str, Any], candidate: dict[str, Any]
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    """Bind facts the model cannot decide and discard unrepairable references."""
+
+    bound = deepcopy(candidate)
+    audit: list[dict[str, Any]] = []
+    expected = _expected_fact_ids(facts)
+    records_by_section = _fact_records_by_section(facts)
+    input_sources = {
+        item["fact_id"]: item.get("source")
+        for command in facts.get("commands", [])
+        for item in command.get("inputs", [])
+    }
+    for section in ("inputs", "parameters", "outputs"):
+        entries = bound.get(section)
+        if not isinstance(entries, list):
+            continue
+        kept: list[Any] = []
+        seen: set[str] = set()
+        discarded_reference = False
+        for entry in entries:
+            if not isinstance(entry, dict):
+                kept.append(entry)
+                continue
+            fact_id = entry.get("fact_id")
+            if isinstance(fact_id, str) and fact_id not in expected[section]:
+                discarded_reference = True
+                audit.append(
+                    {
+                        "action": "discard_unknown_reference",
+                        "section": section,
+                        "fact_id": fact_id,
+                    }
+                )
+                continue
+            if isinstance(fact_id, str) and fact_id in seen:
+                discarded_reference = True
+                audit.append(
+                    {
+                        "action": "discard_duplicate_reference",
+                        "section": section,
+                        "fact_id": fact_id,
+                    }
+                )
+                continue
+            if isinstance(fact_id, str):
+                seen.add(fact_id)
+            if (
+                section == "inputs"
+                and isinstance(fact_id, str)
+                and not str(entry.get("replaceability") or "").strip()
+            ):
+                bound_value = (
+                    "generated"
+                    if input_sources.get(fact_id) == "generated_input"
+                    else "replaceable"
+                )
+                audit.append(
+                    {
+                        "action": "bind_missing_input_replaceability",
+                        "section": section,
+                        "fact_id": fact_id,
+                        "field": "replaceability",
+                        "bound_value": bound_value,
+                    }
+                )
+                entry["replaceability"] = bound_value
+            if (
+                section == "inputs"
+                and input_sources.get(fact_id) == "generated_input"
+                and entry.get("replaceability") != "generated"
+            ):
+                audit.append(
+                    {
+                        "action": "bind_generated_input",
+                        "section": section,
+                        "fact_id": fact_id,
+                        "field": "replaceability",
+                        "discarded_value": entry.get("replaceability"),
+                    }
+                )
+                entry["replaceability"] = "generated"
+            kept.append(entry)
+        if not discarded_reference:
+            for fact in records_by_section[section]:
+                fact_id = fact["fact_id"]
+                if fact_id in seen:
+                    continue
+                kept.append(_missing_semantic_row(section, fact))
+                audit.append(
+                    {
+                        "action": "complete_missing_semantic_row",
+                        "section": section,
+                        "fact_id": fact_id,
+                    }
+                )
+        bound[section] = kept
+    return bound, audit
+
+
+def _validate_text_field(
+    *,
+    item: dict[str, Any],
+    field: str,
+    path: str,
+    errors: list[dict[str, str]],
+) -> None:
+    value = item.get(field)
+    if not isinstance(value, str) or not value.strip():
+        errors.append(
+            _error(
+                f"{path}.{field}",
+                "invalid_value",
+                f"{path}.{field} must be a non-empty string",
+            )
+        )
+
+
+def validate_semantic_candidate(
+    facts: dict[str, Any], candidate: dict[str, Any]
+) -> list[dict[str, str]]:
+    """Return deterministic field errors for a semantic-only candidate."""
+
+    errors: list[dict[str, str]] = []
+    if not isinstance(candidate, dict):
+        return [
+            _error("candidate", "invalid_type", "candidate must be an object")
+        ]
+
+    for field in sorted(set(candidate) - _TOP_LEVEL_FIELDS):
+        errors.append(
+            _error(field, "unknown_field", f"candidate field is not allowed: {field}")
+        )
+    for field in sorted(_TOP_LEVEL_FIELDS - set(candidate)):
+        errors.append(
+            _error(field, "required_field", f"candidate field is required: {field}")
+        )
+
+    if candidate.get("facts_sha256") != facts.get("facts_sha256"):
+        errors.append(
+            _error(
+                "facts_sha256",
+                "facts_mismatch",
+                "candidate facts_sha256 does not match locked execution facts",
+            )
+        )
+    summary = candidate.get("function_summary")
+    if not isinstance(summary, str) or not summary.strip():
+        errors.append(
+            _error(
+                "function_summary",
+                "invalid_value",
+                "function_summary must be a non-empty string",
+            )
+        )
+
+    expected_by_section = _expected_fact_ids(facts)
+    input_sources = {
+        item["fact_id"]: item.get("source")
+        for command in facts.get("commands", [])
+        for item in command.get("inputs", [])
+    }
+    for section, allowed_fields in _SECTION_FIELDS.items():
+        entries = candidate.get(section)
+        if not isinstance(entries, list):
+            errors.append(
+                _error(section, "invalid_type", f"{section} must be an array")
+            )
+            continue
+
+        seen: set[str] = set()
+        for index, entry in enumerate(entries):
+            path = f"{section}[{index}]"
+            if not isinstance(entry, dict):
+                errors.append(
+                    _error(path, "invalid_type", f"{path} must be an object")
+                )
+                continue
+            for field in sorted(set(entry) - allowed_fields):
+                errors.append(
+                    _error(
+                        f"{path}.{field}",
+                        "unknown_field",
+                        f"{path}.{field} is not allowed",
+                    )
+                )
+            for field in sorted(allowed_fields - set(entry)):
+                errors.append(
+                    _error(
+                        f"{path}.{field}",
+                        "required_field",
+                        f"{path}.{field} is required",
+                    )
+                )
+
+            fact_id = entry.get("fact_id")
+            if isinstance(fact_id, str) and fact_id:
+                if fact_id in seen:
+                    errors.append(
+                        _error(
+                            f"{path}.fact_id",
+                            "duplicate_fact_id",
+                            f"duplicate {section} fact_id: {fact_id}",
+                        )
+                    )
+                else:
+                    seen.add(fact_id)
+                if fact_id not in expected_by_section[section]:
+                    errors.append(
+                        _error(
+                            f"{path}.fact_id",
+                            "unknown_fact_id",
+                            f"unknown {section} fact_id: {fact_id}",
+                        )
+                    )
+            else:
+                errors.append(
+                    _error(
+                        f"{path}.fact_id",
+                        "invalid_value",
+                        f"{path}.fact_id must be a non-empty string",
+                    )
+                )
+
+            for field in allowed_fields - {"fact_id"}:
+                _validate_text_field(
+                    item=entry,
+                    field=field,
+                    path=path,
+                    errors=errors,
+                )
+                allowed_values = _ENUMS.get((section, field))
+                if allowed_values is not None and entry.get(field) not in allowed_values:
+                    errors.append(
+                        _error(
+                            f"{path}.{field}",
+                            "invalid_value",
+                            f"{path}.{field} must be one of: "
+                            + ", ".join(sorted(allowed_values)),
+                        )
+                    )
+
+            if fact_id in input_sources:
+                replaceability = entry.get("replaceability")
+                source = input_sources[fact_id]
+                source_mismatch = (
+                    source == "generated_input" and replaceability != "generated"
+                ) or (
+                    source != "generated_input" and replaceability == "generated"
+                )
+                if source_mismatch:
+                    errors.append(
+                        _error(
+                            f"{path}.replaceability",
+                            "input_source_mismatch",
+                            f"{path}.replaceability conflicts with locked input source: "
+                            f"{source}",
+                        )
+                    )
+
+        for fact_id in sorted(expected_by_section[section] - seen):
+            errors.append(
+                _error(
+                    section,
+                    "missing_fact_id",
+                    f"missing {section} fact_id: {fact_id}",
+                )
+            )
+    return errors
+
+
+def merge_semantics(
+    facts: dict[str, Any], candidate: dict[str, Any]
+) -> dict[str, Any]:
+    """Combine validated semantics with an untouched copy of execution facts."""
+
+    errors = validate_semantic_candidate(facts, candidate)
+    if errors:
+        raise SemanticCandidateError(errors)
+    return {
+        "execution_facts": deepcopy(facts),
+        "semantics": deepcopy(candidate),
+    }
diff --git a/gfa_core/extension_stage_lightweight/semantic_repair.py b/gfa_core/extension_stage_lightweight/semantic_repair.py
new file mode 100644
index 000000000..dba045ede
--- /dev/null
+++ b/gfa_core/extension_stage_lightweight/semantic_repair.py
@@ -0,0 +1,376 @@
+"""Apply bounded semantic patches without changing execution facts."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+import re
+from typing import Any, Callable, Mapping
+
+from .deepseek_semantics import (
+    DeepSeekConfig,
+    DeepSeekSemanticError,
+    generate_semantic_patch,
+)
+from .semantic_model import bind_fact_derived_semantics, validate_semantic_candidate
+
+
+MAX_REPAIR_ATTEMPTS = 20
+_FIELDS = {
+    "root": {"function_summary"},
+    "inputs": {"role", "description", "replaceability"},
+    "parameters": {"display_name", "description"},
+    "outputs": {"description", "result_role"},
+}
+_ERROR_PATH = re.compile(
+    r"^(inputs|parameters|outputs)\[(\d+)\]\.([A-Za-z_][A-Za-z0-9_]*)$"
+)
+
+
+def _error(field: str, code: str, message: str) -> dict[str, str]:
+    return {"field": field, "code": code, "message": message}
+
+
+def _expected_ids(facts: dict[str, Any]) -> dict[str, set[str]]:
+    expected = {"inputs": set(), "parameters": set(), "outputs": set()}
+    for command in facts["commands"]:
+        expected["inputs"].update(item["fact_id"] for item in command["inputs"])
+        expected["parameters"].update(
+            item["fact_id"] for item in command["parameters"]
+        )
+    expected["outputs"].update(
+        item["fact_id"] for item in facts["outputs"]["files"]
+    )
+    if facts["outputs"]["stdout"].get("present"):
+        expected["outputs"].add(facts["outputs"]["stdout"]["fact_id"])
+    return expected
+
+
+def _all_targets(facts: dict[str, Any]) -> set[tuple[str, str | None, str]]:
+    targets = {("root", None, "function_summary")}
+    for section, fact_ids in _expected_ids(facts).items():
+        targets.update(
+            (section, fact_id, field)
+            for fact_id in fact_ids
+            for field in _FIELDS[section]
+        )
+    return targets
+
+
+def _automatic_targets(
+    facts: dict[str, Any],
+    candidate: dict[str, Any],
+    errors: list[dict[str, str]],
+) -> set[tuple[str, str | None, str]]:
+    targets: set[tuple[str, str | None, str]] = set()
+    if any(error["field"] == "function_summary" for error in errors):
+        targets.add(("root", None, "function_summary"))
+
+    for error in errors:
+        match = _ERROR_PATH.match(error["field"])
+        if not match:
+            continue
+        section, raw_index, field = match.groups()
+        entries = candidate.get(section, [])
+        index = int(raw_index)
+        if index < len(entries) and field in _FIELDS[section]:
+            fact_id = entries[index].get("fact_id")
+            if isinstance(fact_id, str):
+                targets.add((section, fact_id, field))
+
+    expected = _expected_ids(facts)
+    for section, fact_ids in expected.items():
+        present = {
+            item.get("fact_id")
+            for item in candidate.get(section, [])
+            if isinstance(item, dict)
+        }
+        for fact_id in fact_ids - present:
+            targets.update(
+                (section, fact_id, field) for field in _FIELDS[section]
+            )
+    return targets
+
+
+def _targets_as_records(
+    targets: set[tuple[str, str | None, str]],
+) -> list[dict[str, str | None]]:
+    return [
+        {"section": section, "fact_id": fact_id, "field": field}
+        for section, fact_id, field in sorted(
+            targets, key=lambda item: (item[0], item[1] or "", item[2])
+        )
+    ]
+
+
+def _validate_patch(
+    *,
+    facts: dict[str, Any],
+    patch: Any,
+    allowed_targets: set[tuple[str, str | None, str]],
+) -> list[dict[str, str]]:
+    errors: list[dict[str, str]] = []
+    if not isinstance(patch, dict):
+        return [_error("patch", "invalid_type", "repair patch must be an object")]
+    required = {"facts_sha256", "changes"}
+    for field in sorted(set(patch) - required):
+        errors.append(
+            _error(field, "unknown_field", f"repair patch field is not allowed: {field}")
+        )
+    for field in sorted(required - set(patch)):
+        errors.append(_error(field, "required_field", f"repair patch requires {field}"))
+    if patch.get("facts_sha256") != facts["facts_sha256"]:
+        errors.append(
+            _error(
+                "facts_sha256",
+                "facts_mismatch",
+                "repair patch facts_sha256 does not match locked execution facts",
+            )
+        )
+    changes = patch.get("changes")
+    if not isinstance(changes, list):
+        errors.append(_error("changes", "invalid_type", "changes must be an array"))
+        return errors
+
+    expected = _expected_ids(facts)
+    seen: set[tuple[str, str | None, str]] = set()
+    for index, change in enumerate(changes):
+        path = f"changes[{index}]"
+        if not isinstance(change, dict):
+            errors.append(_error(path, "invalid_type", f"{path} must be an object"))
+            continue
+        allowed_keys = {"section", "fact_id", "fields"}
+        for field in sorted(set(change) - allowed_keys):
+            errors.append(
+                _error(
+                    f"{path}.{field}",
+                    "unknown_field",
+                    f"{path}.{field} is not allowed",
+                )
+            )
+        if set(change) != allowed_keys:
+            for field in sorted(allowed_keys - set(change)):
+                errors.append(
+                    _error(
+                        f"{path}.{field}",
+                        "required_field",
+                        f"{path}.{field} is required",
+                    )
+                )
+            continue
+
+        section = change["section"]
+        fact_id = change["fact_id"]
+        fields = change["fields"]
+        if section not in _FIELDS:
+            errors.append(
+                _error(f"{path}.section", "invalid_value", f"unknown section: {section}")
+            )
+            continue
+        if section == "root":
+            if fact_id is not None:
+                errors.append(
+                    _error(
+                        f"{path}.fact_id",
+                        "invalid_value",
+                        "root patch fact_id must be null",
+                    )
+                )
+        elif not isinstance(fact_id, str) or fact_id not in expected[section]:
+            errors.append(
+                _error(
+                    f"{path}.fact_id",
+                    "unknown_fact_id",
+                    f"unknown {section} fact_id: {fact_id}",
+                )
+            )
+        if not isinstance(fields, dict) or not fields:
+            errors.append(
+                _error(f"{path}.fields", "invalid_type", "fields must be an object")
+            )
+            continue
+        for field, value in fields.items():
+            target = (section, fact_id, field)
+            if field not in _FIELDS[section]:
+                errors.append(
+                    _error(
+                        f"{path}.fields.{field}",
+                        "unknown_field",
+                        f"semantic repair field is not allowed: {field}",
+                    )
+                )
+            elif target not in allowed_targets:
+                errors.append(
+                    _error(
+                        f"{path}.fields.{field}",
+                        "target_not_allowed",
+                        f"semantic repair target is not allowed: {section}/{fact_id}/{field}",
+                    )
+                )
+            elif target in seen:
+                errors.append(
+                    _error(
+                        f"{path}.fields.{field}",
+                        "duplicate_target",
+                        f"duplicate semantic repair target: {section}/{fact_id}/{field}",
+                    )
+                )
+            elif not isinstance(value, str) or not value.strip():
+                errors.append(
+                    _error(
+                        f"{path}.fields.{field}",
+                        "invalid_value",
+                        f"semantic repair value must be a non-empty string: {field}",
+                    )
+                )
+            else:
+                seen.add(target)
+    return errors
+
+
+def _apply_patch(
+    candidate: dict[str, Any], patch: dict[str, Any]
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    proposed = deepcopy(candidate)
+    diff: list[dict[str, Any]] = []
+    for change in patch["changes"]:
+        section = change["section"]
+        fact_id = change["fact_id"]
+        if section == "root":
+            target = proposed
+        else:
+            entries = proposed.setdefault(section, [])
+            target = next(
+                (item for item in entries if item.get("fact_id") == fact_id), None
+            )
+            if target is None:
+                target = {"fact_id": fact_id}
+                entries.append(target)
+        for field, value in sorted(change["fields"].items()):
+            before = target.get(field)
+            target[field] = value
+            if before != value:
+                diff.append(
+                    {
+                        "section": section,
+                        "fact_id": fact_id,
+                        "field": field,
+                        "before": before,
+                        "after": value,
+                    }
+                )
+    return proposed, diff
+
+
+PatchGenerator = Callable[
+    [dict[str, Any], int], tuple[dict[str, Any], dict[str, Any]]
+]
+
+
+def repair_semantic_candidate(
+    *,
+    execution_facts: dict[str, Any],
+    candidate: dict[str, Any],
+    validation_errors: list[dict[str, str]] | None = None,
+    user_feedback: str | None = None,
+    patch_generator: PatchGenerator | None = None,
+    raw_code: Path | None = None,
+    environ: Mapping[str, str] | None = None,
+    client_factory: Callable[[DeepSeekConfig], Any] | None = None,
+    max_attempts: int = MAX_REPAIR_ATTEMPTS,
+) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+    """Repair semantic fields while preserving the supplied candidate until success."""
+
+    original = deepcopy(candidate)
+    errors = (
+        deepcopy(validation_errors)
+        if validation_errors is not None
+        else validate_semantic_candidate(execution_facts, candidate)
+    )
+    feedback = (user_feedback or "").strip()
+    if not errors and not feedback:
+        return original, []
+    mode = "user_feedback" if feedback else "automatic"
+    allowed_targets = (
+        _all_targets(execution_facts)
+        if feedback
+        else _automatic_targets(execution_facts, candidate, errors)
+    )
+    context = {
+        "execution_facts": execution_facts,
+        "candidate": original,
+        "validation_errors": errors,
+        "user_feedback": feedback or None,
+        "allowed_targets": _targets_as_records(allowed_targets),
+    }
+    if patch_generator is None:
+        if raw_code is None:
+            raise ValueError("raw_code is required for DeepSeek semantic repair")
+
+        def patch_generator(
+            repair_context: dict[str, Any], attempt: int
+        ) -> tuple[dict[str, Any], dict[str, Any]]:
+            return generate_semantic_patch(
+                repair_context=repair_context,
+                raw_code=raw_code,
+                environ=environ,
+                client_factory=client_factory,
+                attempt=attempt,
+            )
+
+    history: list[dict[str, Any]] = []
+    limit = min(MAX_REPAIR_ATTEMPTS, max(1, int(max_attempts)))
+    for attempt in range(1, limit + 1):
+        metadata: dict[str, Any] = {}
+        patch_errors: list[dict[str, str]] = []
+        diff: list[dict[str, Any]] = []
+        try:
+            patch, metadata = patch_generator(deepcopy(context), attempt)
+            patch_errors = _validate_patch(
+                facts=execution_facts,
+                patch=patch,
+                allowed_targets=allowed_targets,
+            )
+            if not patch_errors:
+                proposed, diff = _apply_patch(original, patch)
+                if mode == "automatic":
+                    proposed, binding_audit = bind_fact_derived_semantics(
+                        execution_facts, proposed
+                    )
+                    if binding_audit:
+                        metadata["fact_derived_semantic_bindings"] = binding_audit
+                patch_errors = validate_semantic_candidate(
+                    execution_facts, proposed
+                )
+                if not patch_errors:
+                    history.append(
+                        {
+                            "attempt": attempt,
+                            "mode": mode,
+                            "status": "success",
+                            "diff": diff,
+                            "metadata": deepcopy(metadata),
+                            "errors": [],
+                        }
+                    )
+                    return proposed, history
+        except DeepSeekSemanticError as exc:
+            metadata = deepcopy(exc.metadata)
+            patch_errors = [_error("repair", exc.code, str(exc))]
+        except Exception as exc:
+            patch_errors = [
+                _error("repair", "patch_generation_failed", str(exc))
+            ]
+
+        status = "needs_user_confirmation" if attempt == limit else "rejected"
+        history.append(
+            {
+                "attempt": attempt,
+                "mode": mode,
+                "status": status,
+                "diff": diff,
+                "metadata": deepcopy(metadata),
+                "errors": patch_errors,
+            }
+        )
+    return original, history
diff --git a/gfa_core/extension_stage_lightweight/service.py b/gfa_core/extension_stage_lightweight/service.py
new file mode 100644
index 000000000..8c457dae5
--- /dev/null
+++ b/gfa_core/extension_stage_lightweight/service.py
@@ -0,0 +1,795 @@
+"""Persistent Phase-B orchestration for the lightweight extension core only."""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from copy import deepcopy
+import fcntl
+import json
+import os
+from pathlib import Path
+import shutil
+import tempfile
+from typing import Any, Callable, Iterator
+from uuid import uuid4
+
+from .confirmation import apply_confirmation_action, create_confirmation, is_candidate_accepted
+from .converter import build_execution_facts
+from .deepseek_semantics import generate_semantic_candidate
+from .evidence import run_raw_baseline
+from .process_control import ProcessIdentity, stop_process_group
+from .runtime_binding import (
+    build_runtime_binding_contract,
+    render_runtime_package,
+    replay_runtime_binding,
+    resolve_runtime_bindings,
+)
+from .semantic_repair import repair_semantic_candidate
+
+
+SemanticGenerator = Callable[[dict[str, Any], Path], tuple[dict[str, Any], dict[str, Any]]]
+PatchGenerator = Callable[[dict[str, Any], int], tuple[dict[str, Any], dict[str, Any]]]
+
+
+class LifecycleStateError(ValueError):
+    """The requested lifecycle action is not allowed in the current state."""
+
+
+def _copy_tree(source: Path, destination: Path) -> None:
+    if destination.exists():
+        raise ValueError(f"destination already exists: {destination}")
+    shutil.copytree(source, destination, symlinks=True)
+
+
+class LightweightExtensionService:
+    """A small state machine that delegates all conversion/runtime facts to Phase A."""
+
+    def __init__(
+        self,
+        store_root: Path,
+        *,
+        semantic_generator: SemanticGenerator | None = None,
+        patch_generator: PatchGenerator | None = None,
+        environment: dict[str, str] | None = None,
+    ) -> None:
+        self.store_root = Path(store_root)
+        self.extensions_root = self.store_root / "extensions"
+        self.semantic_generator = semantic_generator or self._deepseek_candidate
+        self.patch_generator = patch_generator
+        self.environment = environment
+
+    def extension_dir(self, extension_id: str) -> Path:
+        if (
+            not extension_id
+            or "/" in extension_id
+            or "\\" in extension_id
+            or extension_id in {".", ".."}
+        ):
+            raise ValueError("extension_id must be one safe path component")
+        return self.extensions_root / extension_id
+
+    def _record_path(self, extension_id: str) -> Path:
+        return self.extension_dir(extension_id) / "extension.json"
+
+    @contextmanager
+    def _lock(self, extension_id: str) -> Iterator[None]:
+        locks = self.store_root / ".locks"
+        locks.mkdir(parents=True, exist_ok=True)
+        with (locks / f"{extension_id}.lock").open("a+") as handle:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+            try:
+                yield
+            finally:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+
+    def _read_record(self, extension_id: str) -> dict[str, Any]:
+        try:
+            return json.loads(self._record_path(extension_id).read_text(encoding="utf-8"))
+        except FileNotFoundError as exc:
+            raise ValueError(f"extension does not exist: {extension_id}") from exc
+
+    def _write_record(self, extension_id: str, record: dict[str, Any]) -> None:
+        path = self._record_path(extension_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        payload = json.dumps(record, ensure_ascii=False, indent=2, sort_keys=True) + "\n"
+        with tempfile.NamedTemporaryFile(
+            mode="w", encoding="utf-8", dir=path.parent, prefix=".extension-", delete=False
+        ) as handle:
+            handle.write(payload)
+            handle.flush()
+            os.fsync(handle.fileno())
+            temporary = Path(handle.name)
+        temporary.replace(path)
+        directory_fd = os.open(path.parent, os.O_RDONLY | os.O_DIRECTORY)
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
+
+    def get(self, extension_id: str) -> dict[str, Any]:
+        return self._read_record(extension_id)
+
+    def _deepseek_candidate(self, facts: dict[str, Any], raw_code: Path) -> tuple[dict[str, Any], dict[str, Any]]:
+        return generate_semantic_candidate(
+            execution_facts=facts, raw_code=raw_code, environ=self.environment
+        )
+
+    @staticmethod
+    def _state(record: dict[str, Any], *allowed: str) -> None:
+        if record.get("status") not in allowed:
+            raise LifecycleStateError(
+                f"action requires status in {', '.join(allowed)}, got {record.get('status')}"
+            )
+
+    @staticmethod
+    def _response(
+        record: dict[str, Any], *, token: str, action: str, state: str, run_id: str | None = None
+    ) -> dict[str, Any]:
+        result = {
+            "extension_id": record["extension_id"],
+            "operation_token": token,
+            "action": action,
+            "state": state,
+            "status": record["status"],
+        }
+        if run_id is not None:
+            result["run_id"] = run_id
+        return result
+
+    def _existing_operation(
+        self, record: dict[str, Any], *, token: str, action: str
+    ) -> dict[str, Any] | None:
+        existing = record.setdefault("operations", {}).get(token)
+        if existing is None:
+            return None
+        if existing.get("action") != action:
+            raise ValueError("operation_token is already bound to another action")
+        return deepcopy(existing["response"])
+
+    def _short_operation(
+        self,
+        extension_id: str,
+        *,
+        token: str,
+        action: str,
+        mutate: Callable[[dict[str, Any]], None],
+    ) -> dict[str, Any]:
+        if not token.strip():
+            raise ValueError("operation_token is required")
+        with self._lock(extension_id):
+            record = self._read_record(extension_id)
+            previous = self._existing_operation(record, token=token, action=action)
+            if previous is not None:
+                return previous
+            mutate(record)
+            response = self._response(record, token=token, action=action, state="completed")
+            record["operations"][token] = {
+                "action": action,
+                "state": "completed",
+                "response": response,
+            }
+            self._write_record(extension_id, record)
+            return deepcopy(response)
+
+    def _begin_long_operation(
+        self,
+        extension_id: str,
+        *,
+        token: str,
+        action: str,
+        running_status: str,
+        allowed: tuple[str, ...],
+        run_id: str,
+    ) -> tuple[dict[str, Any] | None, dict[str, Any]]:
+        if not token.strip():
+            raise ValueError("operation_token is required")
+        with self._lock(extension_id):
+            record = self._read_record(extension_id)
+            previous = self._existing_operation(record, token=token, action=action)
+            if previous is not None:
+                return None, previous
+            self._state(record, *allowed)
+            record["status"] = running_status
+            record["active_process"] = None
+            response = self._response(
+                record, token=token, action=action, state="running", run_id=run_id
+            )
+            record["operations"][token] = {
+                "action": action,
+                "state": "running",
+                "run_id": run_id,
+                "response": response,
+            }
+            self._write_record(extension_id, record)
+            return record, deepcopy(response)
+
+    def _mark_process(
+        self,
+        extension_id: str,
+        *,
+        token: str,
+        phase: str,
+        identity: ProcessIdentity,
+    ) -> None:
+        stop_after_recording = False
+        with self._lock(extension_id):
+            record = self._read_record(extension_id)
+            operation = record.get("operations", {}).get(token)
+            if operation is None or operation.get("state") != "running":
+                return
+            record["active_process"] = {
+                "operation_token": token,
+                "phase": phase,
+                "identity": dict(identity),
+            }
+            stop_after_recording = operation.get("stop_requested") is True
+            self._write_record(extension_id, record)
+        if not stop_after_recording:
+            return
+        stopped = stop_process_group(identity, grace_seconds=1.0)
+        with self._lock(extension_id):
+            record = self._read_record(extension_id)
+            active = record.get("active_process")
+            if isinstance(active, dict) and active.get("operation_token") == token:
+                active["stop_result"] = stopped
+                self._write_record(extension_id, record)
+
+    def _finish_long_operation(
+        self,
+        extension_id: str,
+        *,
+        token: str,
+        action: str,
+        run_id: str,
+        mutate: Callable[[dict[str, Any]], None],
+    ) -> dict[str, Any]:
+        with self._lock(extension_id):
+            record = self._read_record(extension_id)
+            operation = record.get("operations", {}).get(token)
+            if operation is None or operation.get("action") != action:
+                raise LifecycleStateError("operation record was lost before completion")
+            mutate(record)
+            active = record.get("active_process")
+            if isinstance(active, dict) and active.get("operation_token") == token:
+                record["active_process"] = None
+            response = self._response(
+                record, token=token, action=action, state="completed", run_id=run_id
+            )
+            operation.update({"state": "completed", "response": response})
+            self._write_record(extension_id, record)
+            return deepcopy(response)
+
+    @staticmethod
+    def _error(phase: str, error: BaseException | str) -> dict[str, Any]:
+        result: dict[str, Any] = {"phase": phase, "message": str(error)}
+        metadata = getattr(error, "metadata", None)
+        if isinstance(metadata, dict) and metadata:
+            result["metadata"] = deepcopy(metadata)
+        return result
+
+    def _build_candidate(
+        self,
+        record: dict[str, Any],
+        evidence: dict[str, Any],
+        *,
+        facts: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        root = self.extension_dir(record["extension_id"])
+        facts = facts or build_execution_facts(evidence)
+        candidate, metadata = self.semantic_generator(facts, root / "raw_code")
+        return {
+            "baseline": evidence,
+            "execution_facts": facts,
+            "semantic_candidate": candidate,
+            "semantic_metadata": metadata,
+            "semantic_repair_history": [],
+            "confirmation": create_confirmation(execution_facts=facts, candidate=candidate),
+            "runtime_binding_contract": build_runtime_binding_contract(
+                facts, candidate, root / "raw_code"
+            ),
+            "validation_runs": [],
+            "reviewed_validation_run_id": None,
+            "published_validation_run_id": None,
+            "error": None,
+            "status": "confirmation_pending",
+        }
+
+    def _run_baseline_operation(
+        self,
+        extension_id: str,
+        *,
+        token: str,
+        action: str,
+        allowed: tuple[str, ...],
+        reserved: bool = False,
+        run_id: str | None = None,
+    ) -> dict[str, Any]:
+        run_id = run_id or f"baseline_{uuid4().hex}"
+        if reserved:
+            record = self.get(extension_id)
+        else:
+            record, existing = self._begin_long_operation(
+                extension_id,
+                token=token,
+                action=action,
+                running_status="baseline_running",
+                allowed=allowed,
+                run_id=run_id,
+            )
+            if record is None:
+                return existing
+        root = self.extension_dir(extension_id)
+        evidence: dict[str, Any] | None = None
+        facts: dict[str, Any] | None = None
+        build: dict[str, Any] | None = None
+        failure: tuple[str, BaseException | str] | None = None
+        try:
+            evidence = run_raw_baseline(
+                command=record["original_command"],
+                raw_code=root / "raw_code",
+                raw_data=root / "raw_test_data",
+                run_dir=root / "baseline" / run_id,
+                env=self.environment,
+                on_process_start=lambda identity: self._mark_process(
+                    extension_id, token=token, phase="baseline", identity=identity
+                ),
+            )
+            if not evidence["success"]:
+                failure = ("baseline", f"original command returned {evidence['returncode']}")
+            else:
+                facts = build_execution_facts(evidence)
+                build = self._build_candidate(record, evidence, facts=facts)
+        except BaseException as exc:
+            failure = ("semantic_candidate" if evidence is not None else "baseline", exc)
+
+        def finish(current: dict[str, Any]) -> None:
+            if build is not None:
+                current.update(build)
+                return
+            if evidence is not None:
+                current["baseline"] = evidence
+            if facts is not None:
+                current["execution_facts"] = facts
+            phase, detail = failure or ("baseline", "unknown build failure")
+            current["error"] = self._error(phase, detail)
+            current["status"] = "baseline_failed" if phase == "baseline" else "build_failed"
+
+        return self._finish_long_operation(
+            extension_id, token=token, action=action, run_id=run_id, mutate=finish
+        )
+
+    def upload(
+        self,
+        *,
+        extension_id: str,
+        raw_code: Path,
+        raw_data: Path,
+        original_command: str,
+        operation_token: str,
+    ) -> dict[str, Any]:
+        raw_code, raw_data = Path(raw_code), Path(raw_data)
+        if not isinstance(operation_token, str) or not operation_token.strip():
+            raise ValueError("operation_token is required")
+        if not raw_code.is_dir() or not raw_data.is_dir():
+            raise ValueError("raw_code and raw_data must be directories")
+        if not original_command.strip():
+            raise ValueError("original_command is required")
+        root = self.extension_dir(extension_id)
+        run_id = f"baseline_{uuid4().hex}"
+        with self._lock(extension_id):
+            if self._record_path(extension_id).exists():
+                record = self._read_record(extension_id)
+                previous = self._existing_operation(
+                    record, token=operation_token, action="upload"
+                )
+                if previous is None:
+                    raise LifecycleStateError("extension already exists")
+                return previous
+            root.mkdir(parents=True, exist_ok=False)
+            _copy_tree(raw_code, root / "raw_code")
+            _copy_tree(raw_data, root / "raw_test_data")
+            self._write_record(
+                extension_id,
+                {
+                    "schema_version": "lightweight-extension-service/v1",
+                    "extension_id": extension_id,
+                    "original_command": original_command,
+                    "status": "baseline_running",
+                    "operations": {
+                        operation_token: {
+                            "action": "upload",
+                            "state": "running",
+                            "run_id": run_id,
+                            "response": {
+                                "extension_id": extension_id,
+                                "operation_token": operation_token,
+                                "action": "upload",
+                                "state": "running",
+                                "status": "baseline_running",
+                                "run_id": run_id,
+                            },
+                        }
+                    },
+                    "active_process": None,
+                    "error": None,
+                },
+            )
+        return self._run_baseline_operation(
+            extension_id,
+            token=operation_token,
+            action="upload",
+            allowed=("uploaded",),
+            reserved=True,
+            run_id=run_id,
+        )
+
+    def rebuild(self, extension_id: str, *, operation_token: str) -> dict[str, Any]:
+        return self._run_baseline_operation(
+            extension_id,
+            token=operation_token,
+            action="rebuild",
+            allowed=("uploaded", "rebuild_required", "baseline_failed", "build_failed", "semantic_repair_failed", "validation_failed"),
+        )
+
+    def retry_semantic(self, extension_id: str, *, operation_token: str) -> dict[str, Any]:
+        if self.get(extension_id).get("status") == "confirmation_pending":
+            return self._short_operation(
+                extension_id,
+                token=operation_token,
+                action="retry_semantic",
+                mutate=lambda record: self._state(record, "confirmation_pending"),
+            )
+        run_id = f"semantic_{uuid4().hex}"
+        record, existing = self._begin_long_operation(
+            extension_id,
+            token=operation_token,
+            action="retry_semantic",
+            running_status="semantic_candidate_running",
+            allowed=("build_failed",),
+            run_id=run_id,
+        )
+        if record is None:
+            return existing
+        evidence = record.get("baseline")
+        facts = record.get("execution_facts")
+        build: dict[str, Any] | None = None
+        failure: BaseException | None = None
+        if isinstance(evidence, dict) and not isinstance(facts, dict):
+            try:
+                facts = build_execution_facts(evidence)
+            except BaseException as exc:
+                failure = exc
+        if not isinstance(evidence, dict) or not isinstance(facts, dict):
+            failure = LifecycleStateError(
+                "semantic retry requires saved baseline evidence and execution facts"
+            )
+        elif failure is None:
+            try:
+                build = self._build_candidate(record, evidence, facts=facts)
+            except BaseException as exc:
+                failure = exc
+
+        def finish(current: dict[str, Any]) -> None:
+            if build is not None:
+                current.update(build)
+                return
+            if isinstance(facts, dict):
+                current["execution_facts"] = facts
+            current["error"] = self._error(
+                "semantic_candidate", failure or "unknown semantic generation failure"
+            )
+            current["status"] = "build_failed"
+
+        return self._finish_long_operation(
+            extension_id,
+            token=operation_token,
+            action="retry_semantic",
+            run_id=run_id,
+            mutate=finish,
+        )
+
+    def revise(
+        self,
+        extension_id: str,
+        *,
+        feedback: str,
+        revision_target: str,
+        operation_token: str,
+    ) -> dict[str, Any]:
+        def revise_record(record: dict[str, Any]) -> None:
+            self._state(record, "confirmation_pending", "semantic_repair_failed")
+            decision = apply_confirmation_action(
+                confirmation=record["confirmation"],
+                action="revise",
+                execution_facts=record["execution_facts"],
+                candidate=record["semantic_candidate"],
+                feedback=feedback,
+                revision_target=revision_target,
+            )
+            if decision["status"] == "fact_dispute":
+                record["confirmation"] = decision
+                record["status"] = "rebuild_required"
+                return
+            try:
+                candidate, history = repair_semantic_candidate(
+                    execution_facts=record["execution_facts"],
+                    candidate=record["semantic_candidate"],
+                    user_feedback=feedback,
+                    patch_generator=self.patch_generator,
+                    raw_code=self.extension_dir(extension_id) / "raw_code",
+                    environ=self.environment,
+                )
+            except BaseException as exc:
+                record["status"] = "semantic_repair_failed"
+                record["error"] = self._error("semantic_repair", exc)
+                return
+            if not history or history[-1]["status"] != "success":
+                record["semantic_repair_history"] = history
+                record["status"] = "semantic_repair_failed"
+                record["error"] = self._error("semantic_repair", "semantic repair was rejected")
+                return
+            record["semantic_candidate"] = candidate
+            record["semantic_repair_history"] = history
+            record["confirmation"] = create_confirmation(
+                execution_facts=record["execution_facts"], candidate=candidate, repair_history=history
+            )
+            record["runtime_binding_contract"] = build_runtime_binding_contract(
+                record["execution_facts"], candidate, self.extension_dir(extension_id) / "raw_code"
+            )
+            record["error"] = None
+            record["status"] = "confirmation_pending"
+
+        return self._short_operation(
+            extension_id, token=operation_token, action="revise", mutate=revise_record
+        )
+
+    def confirm(self, extension_id: str, *, operation_token: str) -> dict[str, Any]:
+        def confirm_record(record: dict[str, Any]) -> None:
+            self._state(record, "confirmation_pending")
+            confirmation = apply_confirmation_action(
+                confirmation=record["confirmation"], action="confirm",
+                execution_facts=record["execution_facts"], candidate=record["semantic_candidate"],
+            )
+            if not is_candidate_accepted(
+                confirmation=confirmation,
+                execution_facts=record["execution_facts"], candidate=record["semantic_candidate"],
+            ):
+                raise LifecycleStateError("candidate confirmation is stale")
+            record["confirmation"] = confirmation
+            record["status"] = "confirmed"
+
+        return self._short_operation(
+            extension_id, token=operation_token, action="confirm", mutate=confirm_record
+        )
+
+    def _default_inputs(self, record: dict[str, Any]) -> dict[str, Path]:
+        data = self.extension_dir(record["extension_id"]) / "raw_test_data"
+        return {
+            item["path"]: data / item["path"]
+            for item in record["runtime_binding_contract"].get("inputs", [])
+            if item.get("replaceable")
+        }
+
+    @staticmethod
+    def _job_path(path: Path, roots: tuple[Path, Path]) -> Path:
+        candidate = Path(os.path.abspath(Path(path).expanduser())).resolve()
+        resolved_roots = tuple(root.resolve() for root in roots)
+        if not candidate.is_file() or not any(
+            candidate.is_relative_to(root) for root in resolved_roots
+        ):
+            raise ValueError("runtime input must be a file inside the selected job")
+        return candidate
+
+    def _execute(
+        self,
+        record: dict[str, Any],
+        *,
+        run_id: str,
+        run_dir: Path,
+        input_overrides: dict[str, Path],
+        parameter_overrides: dict[str, Any] | None = None,
+        explicit_prefix: str | None = None,
+        operation_token: str,
+        phase: str,
+    ) -> dict[str, Any]:
+        root = self.extension_dir(record["extension_id"])
+        resolved = resolve_runtime_bindings(
+            record["runtime_binding_contract"], input_overrides, parameter_overrides or {},
+            explicit_prefix=explicit_prefix,
+        )
+        if resolved["status"] != "resolved":
+            return {
+                "run_id": run_id, "success": False, "contract_passed": False,
+                "binding": resolved, "projection": {"files": [], "stdout": {"present": False}},
+            }
+        rendered = render_runtime_package(
+            record["runtime_binding_contract"], root / "raw_code", resolved, run_dir
+        )
+        result = replay_runtime_binding(
+            rendered,
+            env=self.environment,
+            on_process_start=lambda identity: self._mark_process(
+                record["extension_id"], token=operation_token, phase=phase, identity=identity
+            ),
+        )
+        result["run_id"] = run_id
+        result["binding"] = resolved
+        result["projection"] = self._project_outputs(run_dir, result)
+        return result
+
+    @staticmethod
+    def _project_outputs(run_dir: Path, result: dict[str, Any]) -> dict[str, Any]:
+        output_root = run_dir / "outputs"
+        output_root.mkdir(exist_ok=True)
+        files: list[dict[str, Any]] = []
+        for item in result.get("outputs", []):
+            runtime_path = item["runtime_path"]
+            source = run_dir / "work" / runtime_path
+            destination = output_root / runtime_path
+            destination.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(source, destination)
+            files.append({**item, "path": runtime_path, "absolute_path": str(destination)})
+        stdout_path = Path(result.get("logs", {}).get("stdout", ""))
+        stdout = {"present": stdout_path.is_file() and stdout_path.stat().st_size > 0}
+        if stdout["present"]:
+            stdout.update({"path": str(stdout_path), "text": stdout_path.read_text(encoding="utf-8", errors="replace")})
+        return {"files": files, "stdout": stdout}
+
+    def validate(self, extension_id: str, *, operation_token: str) -> dict[str, Any]:
+        run_id = f"validation_{uuid4().hex}"
+        record, existing = self._begin_long_operation(
+            extension_id, token=operation_token, action="validate", running_status="validation_running",
+            allowed=("confirmed", "validation_failed"), run_id=run_id,
+        )
+        if record is None:
+            return existing
+        result: dict[str, Any]
+        try:
+            result = self._execute(
+                record, run_id=run_id, run_dir=self.extension_dir(extension_id) / "runs" / run_id,
+                input_overrides=self._default_inputs(record), operation_token=operation_token, phase="validation",
+            )
+        except BaseException as exc:
+            result = {"run_id": run_id, "success": False, "contract_passed": False, "error": self._error("validation", exc), "projection": {"files": [], "stdout": {"present": False}}}
+
+        def finish(current: dict[str, Any]) -> None:
+            current.setdefault("validation_runs", []).append(result)
+            current["status"] = "result_review_pending" if result.get("contract_passed") else "validation_failed"
+            current["error"] = None if result.get("contract_passed") else result.get("error")
+
+        return self._finish_long_operation(
+            extension_id, token=operation_token, action="validate", run_id=run_id, mutate=finish
+        )
+
+    def review_result(self, extension_id: str, *, operation_token: str) -> dict[str, Any]:
+        def review(record: dict[str, Any]) -> None:
+            self._state(record, "result_review_pending")
+            run = record["validation_runs"][-1]
+            if not run.get("contract_passed"):
+                raise LifecycleStateError("only a successful validation run can be reviewed")
+            record["reviewed_validation_run_id"] = run["run_id"]
+            record["status"] = "reviewed"
+
+        return self._short_operation(extension_id, token=operation_token, action="review_result", mutate=review)
+
+    def publish(self, extension_id: str, *, operation_token: str) -> dict[str, Any]:
+        def publish_record(record: dict[str, Any]) -> None:
+            self._state(record, "reviewed")
+            reviewed = record.get("reviewed_validation_run_id")
+            run = next((item for item in record["validation_runs"] if item["run_id"] == reviewed), None)
+            if run is None or not run.get("contract_passed"):
+                raise LifecycleStateError("publication requires the reviewed successful validation run")
+            record["published_validation_run_id"] = reviewed
+            record["status"] = "published"
+
+        return self._short_operation(extension_id, token=operation_token, action="publish", mutate=publish_record)
+
+    def help(self, extension_id: str) -> dict[str, Any]:
+        record = self.get(extension_id)
+        return {
+            "extension_id": extension_id, "status": record["status"],
+            "function_summary": record.get("semantic_candidate", {}).get("function_summary"),
+            "original_command": record["original_command"],
+            "inputs": deepcopy(record.get("runtime_binding_contract", {}).get("inputs", [])),
+            "parameters": deepcopy(record.get("runtime_binding_contract", {}).get("parameters", [])),
+            "outputs": deepcopy(record.get("runtime_binding_contract", {}).get("outputs", {})),
+        }
+
+    def run(
+        self,
+        extension_id: str,
+        *,
+        input_overrides: dict[str, Path],
+        run_job_id: str | None = None,
+        input_root: Path | None = None,
+        workspace_root: Path | None = None,
+        parameter_overrides: dict[str, Any] | None = None,
+        explicit_prefix: str | None = None,
+        operation_token: str,
+    ) -> dict[str, Any]:
+        if (
+            not run_job_id
+            or run_job_id in {".", ".."}
+            or "/" in run_job_id
+            or "\\" in run_job_id
+            or input_root is None
+            or workspace_root is None
+        ):
+            raise ValueError("run_job_id, input_root, and workspace_root are required")
+        job_input = Path(os.path.abspath(Path(input_root) / run_job_id))
+        job_workspace = Path(os.path.abspath(Path(workspace_root) / run_job_id))
+        if not job_input.is_dir() or not job_workspace.is_dir():
+            raise ValueError("selected job input and workspace directories must exist")
+        checked_inputs = {
+            key: self._job_path(Path(value), (job_input, job_workspace))
+            for key, value in input_overrides.items()
+        }
+        run_id = f"runtime_{uuid4().hex}"
+        record, existing = self._begin_long_operation(
+            extension_id, token=operation_token, action="run", running_status="runtime_running",
+            allowed=("published",), run_id=run_id,
+        )
+        if record is None:
+            return existing
+        result: dict[str, Any]
+        try:
+            result = self._execute(
+                record, run_id=run_id,
+                run_dir=job_workspace / "extension_runs" / extension_id / run_id,
+                input_overrides=checked_inputs, parameter_overrides=parameter_overrides,
+                explicit_prefix=explicit_prefix, operation_token=operation_token, phase="runtime",
+            )
+        except BaseException as exc:
+            result = {"run_id": run_id, "success": False, "contract_passed": False, "error": self._error("runtime", exc), "projection": {"files": [], "stdout": {"present": False}}}
+
+        def finish(current: dict[str, Any]) -> None:
+            current.setdefault("runtime_runs", []).append(result)
+            current["status"] = "published"
+
+        return self._finish_long_operation(
+            extension_id, token=operation_token, action="run", run_id=run_id, mutate=finish
+        )
+
+    def stop(self, extension_id: str, *, operation_token: str) -> dict[str, Any]:
+        with self._lock(extension_id):
+            record = self._read_record(extension_id)
+            active = record.get("active_process")
+            operation = record.get("operations", {}).get(operation_token)
+            if not isinstance(operation, dict) or operation.get("state") != "running":
+                return {"extension_id": extension_id, "operation_token": operation_token, "stopped": False}
+            identity = (
+                active.get("identity")
+                if isinstance(active, dict) and active.get("operation_token") == operation_token
+                else None
+            )
+            operation["stop_requested"] = True
+            self._write_record(extension_id, record)
+        stopped = (
+            stop_process_group(identity, grace_seconds=1.0)
+            if isinstance(identity, dict)
+            else False
+        )
+        with self._lock(extension_id):
+            record = self._read_record(extension_id)
+            active = record.get("active_process")
+            if isinstance(active, dict) and active.get("operation_token") == operation_token:
+                active["stop_result"] = stopped
+                self._write_record(extension_id, record)
+            elif not stopped:
+                operation = record.get("operations", {}).get(operation_token, {})
+                runs = [record.get("baseline", {})]
+                runs.extend(record.get("validation_runs", []))
+                runs.extend(record.get("runtime_runs", []))
+                stopped = bool(
+                    operation.get("state") == "completed"
+                    and any(
+                        isinstance(item, dict)
+                        and item.get("returncode", 0) < 0
+                        and (
+                            operation.get("action") in {"upload", "rebuild"}
+                            or item.get("run_id") == operation.get("run_id")
+                        )
+                        for item in runs
+                    )
+                )
+        return {"extension_id": extension_id, "operation_token": operation_token, "stopped": stopped}
diff --git a/gfa_core/gene_family_scope.py b/gfa_core/gene_family_scope.py
index e314c7a01..467988388 100755
--- a/gfa_core/gene_family_scope.py
+++ b/gfa_core/gene_family_scope.py
@@ -12,6 +12,7 @@ from dataclasses import asdict, dataclass, field
 from pathlib import Path
 import hashlib
 import json
+import os
 import re
 from typing import Any, Iterable
 
diff --git a/gfa_core/gene_family_stage_context.py b/gfa_core/gene_family_stage_context.py
index f66af3c8f..5219e2ca5 100755
--- a/gfa_core/gene_family_stage_context.py
+++ b/gfa_core/gene_family_stage_context.py
@@ -106,7 +106,7 @@ def infer_analysis_route(stage: str, scope_data: dict[str, Any] | None = None) -
     if scope_mode == "target_only" and len(targets) > 1:
         return "multi_target"
     if refs and scope_mode in {"target_plus_reference", "target_plus_reference_plus_comparative"}:
-        return "subfamily_prediction" if stage in {"phylogeny"} else "multi_species"
+        return "multi_species"
     if comps or len(targets) > 1:
         return "multi_species"
     return scope_mode or "custom"
diff --git a/gfa_core/mas/agents/router_runtime.py b/gfa_core/mas/agents/router_runtime.py
index 709acae89..5ba61a18b 100644
--- a/gfa_core/mas/agents/router_runtime.py
+++ b/gfa_core/mas/agents/router_runtime.py
@@ -40,6 +40,7 @@ class RouterOutcome(BaseModel):
     interaction_kind: InteractionKind = "independent"
     proposal: dict[str, str] | None = None
     input_paths: list[str] = Field(default_factory=list)
+    ui_action: Literal["open_config_dialog"] | None = None
 
 
 RouteGoal = Literal[
@@ -635,6 +636,15 @@ class RouterRuntime:
         job_id: str,
         goal_ledger: GoalLedger | None = None,
     ) -> RouterOutcome:
+        ui_action = self._config_dialog_ui_action(query)
+        if ui_action is not None:
+            return RouterOutcome(
+                status="ok",
+                action="reply",
+                message="已打开当前 job 的 config.xlsx 核对表。",
+                ui_action=ui_action,
+            )
+
         pending_proposal = self._pending_analysis_proposal(goal_ledger)
         confirmed_proposal = (
             pending_proposal
@@ -1322,6 +1332,18 @@ class RouterRuntime:
             tool_trace=tool_trace,
         )
 
+    @staticmethod
+    def _config_dialog_ui_action(query: str) -> str | None:
+        compact = re.sub(r"[\s，,。!！?？]+", "", str(query or "").lower())
+        polite = r"(?:请|请帮我|帮我|麻烦(?:你)?|可以|能否)?(?:给我)?"
+        target = r"(?:当前job的?)?(?:config(?:\.xlsx)?|配置(?:表|文件)?)"
+        action = r"(?:重新)?(?:打开|调出|弹出)(?:一下)?"
+        patterns = (
+            rf"^{polite}{action}{target}(?:弹窗)?$",
+            rf"^{polite}(?:把)?{target}(?:给我)?{action}$",
+        )
+        return "open_config_dialog" if any(re.fullmatch(pattern, compact) for pattern in patterns) else None
+
     @staticmethod
     def _is_explicit_job_file_read(query: str) -> bool:
         text = str(query or "").strip()
diff --git a/gfa_core/mas/artifact_resolver.py b/gfa_core/mas/artifact_resolver.py
index 3c0130417..4b10db6ce 100755
--- a/gfa_core/mas/artifact_resolver.py
+++ b/gfa_core/mas/artifact_resolver.py
@@ -436,6 +436,7 @@ class ArtifactResolver:
             "protein_fasta": {"fasta"},
             "table": {"id_list", "expression_matrix"},
             "manifest": {"metadata"},
+            "tree": {"newick"},
         }
         return actual in aliases.get(required, set())
 
diff --git a/gfa_core/mas/persistent_conversation.py b/gfa_core/mas/persistent_conversation.py
index a331b22d7..bca667594 100644
--- a/gfa_core/mas/persistent_conversation.py
+++ b/gfa_core/mas/persistent_conversation.py
@@ -97,7 +97,7 @@ class PersistentConversationStore:
         return bound or requested
 
     def rebind_job(self, *, session_id: str, job_id: str) -> str:
-        """Explicitly switch a conversation to one job and drop old job semantics."""
+        """Bind one conversation to one job without mixing histories."""
         conversation_id = _conversation_id(session_id)
         requested = str(job_id or "").strip()
         if not requested:
@@ -107,13 +107,36 @@ class PersistentConversationStore:
             raise ValueError("conversation is missing")
         previous_job = str(conversation.job_id or "")
         current = self.repository.get_goal_ledger(conversation_id)
+        ledger_job = str(
+            (current.user_terms if current is not None else {}).get("active_job_id")
+            or ""
+        ).strip()
+        bound_job = previous_job or ledger_job
+        if bound_job == requested:
+            return conversation_id
+        if bound_job:
+            replacement_id = str(uuid4())
+            self.repository.create_conversation(
+                conversation_id=replacement_id,
+                principal_id=conversation.principal_id,
+                job_id=requested,
+            )
+            self.repository.put_goal_ledger(
+                GoalLedger(
+                    conversation_id=replacement_id,
+                    revision=0,
+                    user_terms={"active_job_id": requested},
+                ),
+                expected_revision=None,
+            )
+            return replacement_id
         self.repository.update_conversation(
             conversation_id=conversation_id,
             principal_id=conversation.principal_id,
             job_id=requested,
         )
         if current is None:
-            return requested
+            return conversation_id
         replacement = GoalLedger(
             conversation_id=conversation_id,
             revision=current.revision + 1,
@@ -131,7 +154,7 @@ class PersistentConversationStore:
                 job_id=previous_job,
             )
             raise
-        return requested
+        return conversation_id
 
     def begin_turn(
         self,
diff --git a/gfa_core/mas/tools/stage_tools.py b/gfa_core/mas/tools/stage_tools.py
index e9c27f2da..cc76e2f87 100755
--- a/gfa_core/mas/tools/stage_tools.py
+++ b/gfa_core/mas/tools/stage_tools.py
@@ -304,6 +304,7 @@ class StageToolExecutor:
                     blast_identity=(extra_params or {}).get("blastIdentity", (extra_params or {}).get("blast_identity", 30.0)),
                     phy_mafft=(extra_params or {}).get("mafftParams", f"--auto --thread {cpu}"),
                     phy_iqtree=(extra_params or {}).get("iqtreeParams", f"-m MFP -bb 1000 -nt {cpu}"),
+                    tree_file=(extra_params or {}).get("treeFile", "") or (extra_params or {}).get("tree_file", ""),
                     reference_subfamily_file=(extra_params or {}).get("referenceSubfamilyFile", ""),
                     reference_target_prefix=(extra_params or {}).get("referenceTargetPrefix", ""),
                     reference_prefix=(extra_params or {}).get("referencePrefix", "At"),
diff --git a/start_celery_9000.sh b/start_celery_9000.sh
index d5dd2a070..50a257db2 100755
--- a/start_celery_9000.sh
+++ b/start_celery_9000.sh
@@ -47,6 +47,10 @@ CONDA_ENV="$CONDA_BASE/envs/$DEFAULT_ENV"
 export PATH="$CONDA_ENV/bin:$PATH"
 export BBAV5_PROJECT_ROOT="${BBAV5_PROJECT_ROOT:-$PROJECT_ROOT}"
 export PLANTAI_PROJECT_ROOT="${PLANTAI_PROJECT_ROOT:-$PROJECT_ROOT}"
+export BBAV5_PROJECT_ENV_FILE="${BBAV5_PROJECT_ENV_FILE:-$PROJECT_ROOT/.env}"
+export BBAV5_LIGHTWEIGHT_EXTENSION_STORE="${BBAV5_LIGHTWEIGHT_EXTENSION_STORE:-$PROJECT_ROOT/.runtime/lightweight-extension/store}"
+export BBAV5_LIGHTWEIGHT_INPUT="${BBAV5_LIGHTWEIGHT_INPUT:-$PROJECT_ROOT/input}"
+export BBAV5_LIGHTWEIGHT_WORKSPACE="${BBAV5_LIGHTWEIGHT_WORKSPACE:-$PROJECT_ROOT/workspace}"
 export BBAV5_QUEUE_PREFIX="${BBAV5_QUEUE_PREFIX:-plantai_dev_9000}"
 export BBAV5_REDIS_URL="${BBAV5_REDIS_URL:-redis://localhost:6379/10}"
 WORKER_NAME_PREFIX="${BBAV5_WORKER_NAME_PREFIX:-${BBAV5_QUEUE_PREFIX//[^A-Za-z0-9_]/_}}"
diff --git a/start_plantai_9000.sh b/start_plantai_9000.sh
index 1abf62ddb..e907169fa 100755
--- a/start_plantai_9000.sh
+++ b/start_plantai_9000.sh
@@ -15,6 +15,10 @@ export PATH="$CONDA_ENV/bin:$PATH"
 # the caller's shell; GWAS/other sandboxes have dedicated restart scripts.
 export BBAV5_PROJECT_ROOT="$SCRIPT_DIR"
 export PLANTAI_PROJECT_ROOT="$SCRIPT_DIR"
+export BBAV5_PROJECT_ENV_FILE="${BBAV5_PROJECT_ENV_FILE:-$SCRIPT_DIR/.env}"
+export BBAV5_LIGHTWEIGHT_EXTENSION_STORE="${BBAV5_LIGHTWEIGHT_EXTENSION_STORE:-$SCRIPT_DIR/.runtime/lightweight-extension/store}"
+export BBAV5_LIGHTWEIGHT_INPUT="${BBAV5_LIGHTWEIGHT_INPUT:-$SCRIPT_DIR/input}"
+export BBAV5_LIGHTWEIGHT_WORKSPACE="${BBAV5_LIGHTWEIGHT_WORKSPACE:-$SCRIPT_DIR/workspace}"
 export BBAV5_QUEUE_PREFIX="plantai_dev_9000"
 export BBAV5_REDIS_URL="redis://localhost:6379/10"
 export PLANTAI_WEB_PORT="9000"
diff --git a/tasks.py b/tasks.py
index d443165fc..6afc4df46 100755
--- a/tasks.py
+++ b/tasks.py
@@ -13,6 +13,19 @@ sys.path.insert(0, str(PROJECT_ROOT))
 from celery_app import app
 
 
+@app.task(
+    bind=True,
+    name="tasks.execute_lightweight_extension_operation",
+    time_limit=None,
+    soft_time_limit=None,
+)
+def execute_lightweight_extension_operation(self, payload: dict) -> dict:
+    """Run one lightweight-extension operation without a Celery deadline."""
+    from gfa_core.extension_stage_lightweight.api import execute_queued_operation
+
+    return execute_queued_operation(payload)
+
+
 def normalize_stage_params(stage: str, params: dict | None) -> tuple[dict, dict]:
     """Clamp per-stage CPU at the worker boundary and return resource metadata."""
     params = dict(params or {})
@@ -27,16 +40,19 @@ def normalize_stage_params(stage: str, params: dict | None) -> tuple[dict, dict]
 
             explicit_cpu = requested_cpu not in {None, "", 0, "0"}
             project_limit = rnaseq_project_cpu_limit(requested_cpu if explicit_cpu else None)
+            explicit_threads = params.get("threads_per_sample") or params.get("threadsPerSample")
             plan = recommend_rnaseq_parallelism(
                 total_cpu=project_limit,
                 sample_parallel_jobs=params.get("sample_parallel_jobs") or params.get("sampleParallelJobs"),
-                threads_per_sample=params.get("threads_per_sample") or params.get("threadsPerSample"),
-                sample_count=params.get("sample_count") or params.get("sampleCount"),
                 stage=stage,
             )
-            effective_cpu = clamp_stage_cpu(stage, plan["total_cpu"])
+            effective_cpu = clamp_stage_cpu(stage, project_limit)
             params["sample_parallel_jobs"] = plan["sample_parallel_jobs"]
-            params["threads_per_sample"] = plan["threads_per_sample"]
+            if explicit_threads:
+                params["threads_per_sample"] = max(1, int(explicit_threads))
+            else:
+                params.pop("threads_per_sample", None)
+                params.pop("threadsPerSample", None)
             params["rnaseq_project_max_cpu"] = plan["project_cpu_limit"]
             params["resource_decision"] = {
                 "stage": stage,
@@ -44,8 +60,11 @@ def normalize_stage_params(stage: str, params: dict | None) -> tuple[dict, dict]
                 "effective_cpu": effective_cpu,
                 "project_cpu_limit": plan["project_cpu_limit"],
                 "sample_parallel_jobs": plan["sample_parallel_jobs"],
-                "threads_per_sample": plan["threads_per_sample"],
-                "reason": f"{stage} project CPU budget split across sample-level parallel jobs",
+                "threads_per_sample": max(1, int(explicit_threads)) if explicit_threads else None,
+                "reason": (
+                    f"{stage} preserves the selected total CPU budget; per-sample threads "
+                    "are derived after the real sample count is known"
+                ),
             }
     except Exception as exc:
         requested_cpu = params.get("requested_cpu", params.get("cpu"))
diff --git a/tests/unit/test_autofill_entrypoints.py b/tests/unit/test_autofill_entrypoints.py
index d28f699c4..c0b196e51 100755
--- a/tests/unit/test_autofill_entrypoints.py
+++ b/tests/unit/test_autofill_entrypoints.py
@@ -7,6 +7,28 @@ if str(ROOT) not in sys.path:
 
 from apps.cli.run_config_autofill import build_rows, merge_rows
 from apps.cli.autofill_common import scan_files
+from gfa_core.mas.agents.router_runtime import RouterRuntime
+
+
+def test_direct_config_open_commands_map_to_config_dialog_action():
+    for query in (
+        "打开 config",
+        "打开 config.xlsx",
+        "重新打开配置表",
+        "帮我打开当前 job 的配置",
+    ):
+        assert RouterRuntime._config_dialog_ui_action(query) == "open_config_dialog"
+
+
+def test_config_discussion_does_not_map_to_config_dialog_action():
+    for query in (
+        "读取 config.xlsx 中有哪些物种",
+        "检查 config 是否正确",
+        "我已经打开 config，下一步做什么",
+        "config 为什么打不开",
+        "config 已确认，执行数据准备",
+    ):
+        assert RouterRuntime._config_dialog_ui_action(query) is None
 
 
 def test_at_spl_pep_upload_is_detected_as_seed_reference(tmp_path):
@@ -98,6 +120,16 @@ def test_backend_open_endpoints_prefer_draft_then_confirmed_file():
     assert 'input_dir / "samples.yaml"' in main_py
 
 
+def test_chat_config_dialog_action_is_transmitted_and_opens_current_job_config():
+    main_py = (ROOT / "apps/web/vue3/main.py").read_text(encoding="utf-8")
+    html = (ROOT / "apps/web/vue3/index.html").read_text(encoding="utf-8")
+
+    assert '"ui_action": outcome.get("ui_action")' in main_py
+    assert "data.intent.ui_action === 'open_config_dialog'" in html
+    assert "await openAutofillDialog('config'" in html
+    assert "await openExistingAutofillDraft('config')" in html
+
+
 def test_samples_confirm_no_longer_blocks_on_pending_de_roles_and_closes_dialog():
     html = (ROOT / "apps/web/vue3/index.html").read_text(encoding="utf-8")
     confirm_start = html.index("const confirmAutofillDraft")
@@ -110,4 +142,3 @@ def test_samples_confirm_no_longer_blocks_on_pending_de_roles_and_closes_dialog(
     assert "请在样本表中至少标记一个比较组" not in confirm_block
     assert "autofillDialogVisible.value = false" in confirm_block
 
-
diff --git a/tests/unit/test_extension_stage_lightweight_api.py b/tests/unit/test_extension_stage_lightweight_api.py
new file mode 100644
index 000000000..5ab656ad7
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_api.py
@@ -0,0 +1,930 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+import threading
+import asyncio
+
+from fastapi import FastAPI
+from fastapi.testclient import TestClient
+
+
+class _FakeService:
+    def __init__(self, record: dict | None = None) -> None:
+        self.record = record or {
+            "extension_id": "count_fasta",
+            "status": "validation_running",
+            "operations": {
+                "validate-1": {
+                    "action": "validate",
+                    "state": "running",
+                    "response": {
+                        "extension_id": "count_fasta",
+                        "operation_token": "validate-1",
+                        "action": "validate",
+                        "state": "running",
+                    },
+                }
+            },
+            "validation_runs": [],
+            "runtime_runs": [],
+        }
+        self.stops: list[tuple[str, str]] = []
+
+    def get(self, extension_id: str) -> dict:
+        assert extension_id == self.record["extension_id"]
+        return self.record
+
+    def stop(self, extension_id: str, *, operation_token: str) -> dict:
+        self.stops.append((extension_id, operation_token))
+        return {
+            "extension_id": extension_id,
+            "operation_token": operation_token,
+            "stopped": True,
+        }
+
+    def help(self, extension_id: str) -> dict:
+        return {"extension_id": extension_id, "function_summary": "count FASTA records"}
+
+
+def _client(tmp_path: Path, service: _FakeService | None = None):
+    from gfa_core.extension_stage_lightweight.api import (
+        LightweightApiSettings,
+        create_lightweight_extension_router,
+    )
+
+    queued: list[dict] = []
+    app = FastAPI()
+    app.include_router(
+        create_lightweight_extension_router(
+            settings=LightweightApiSettings(
+                project_root=tmp_path,
+                store_root=tmp_path / "store",
+                input_root=tmp_path / "input",
+                workspace_root=tmp_path / "workspace",
+            ),
+            service_factory=lambda _settings: service or _FakeService(),
+            enqueue=lambda payload: queued.append(payload) or "celery-test-id",
+        )
+    )
+    return TestClient(app), queued
+
+
+def _receipt(tmp_path: Path, *, token: str = "validate-1") -> None:
+    path = tmp_path / "store" / "operations" / f"{token}.json"
+    path.parent.mkdir(parents=True)
+    path.write_text(
+        json.dumps(
+            {
+                "operation_id": token,
+                "operation_token": token,
+                "extension_id": "count_fasta",
+                "action": "validate",
+                "state": "queued",
+                "status": "queued",
+            }
+        ),
+        encoding="utf-8",
+    )
+
+
+def test_settings_use_explicit_environment_or_current_project_root(tmp_path: Path) -> None:
+    from gfa_core.extension_stage_lightweight.api import LightweightApiSettings
+
+    settings = LightweightApiSettings.from_environment(
+        environ={
+            "BBAV5_PROJECT_ROOT": str(tmp_path),
+            "BBAV5_LIGHTWEIGHT_EXTENSION_STORE": "isolated-store",
+            "BBAV5_LIGHTWEIGHT_INPUT": "isolated-input",
+            "BBAV5_LIGHTWEIGHT_WORKSPACE": "isolated-workspace",
+        }
+    )
+
+    assert settings.project_root == tmp_path
+    assert settings.store_root == tmp_path / "isolated-store"
+    assert settings.input_root == tmp_path / "isolated-input"
+    assert settings.workspace_root == tmp_path / "isolated-workspace"
+    assert "bbav5_0502_Yang_Tihuan.7880" not in str(settings.project_root)
+
+    project_root_only = LightweightApiSettings.from_environment(
+        environ={"PROJECT_ROOT": str(tmp_path)}
+    )
+    assert project_root_only.project_root == tmp_path
+
+
+def test_worker_maps_logical_job_paths_to_configured_isolated_roots(tmp_path: Path) -> None:
+    from gfa_core.extension_stage_lightweight.api import (
+        LightweightApiSettings,
+        _runtime_input_path,
+    )
+
+    settings = LightweightApiSettings(
+        tmp_path,
+        tmp_path / "store",
+        tmp_path / "isolated-input",
+        tmp_path / "isolated-workspace",
+    )
+
+    assert _runtime_input_path(settings, "job_1", "input/job_1/sample.fa") == (
+        settings.input_root / "job_1" / "sample.fa"
+    )
+    assert _runtime_input_path(settings, "job_1", "workspace/job_1/sample.fa") == (
+        settings.workspace_root / "job_1" / "sample.fa"
+    )
+
+
+def test_upload_persists_files_and_returns_operation_before_celery_runs(tmp_path: Path) -> None:
+    client, queued = _client(tmp_path)
+
+    response = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data={
+            "extension_id": "count_fasta",
+            "original_command": "bash count.sh input.fa",
+            "operation_token": "upload-1",
+        },
+        files=[
+            ("raw_code_files", ("count.sh", b"grep -c '^>' input.fa\n", "text/plain")),
+            ("raw_data_files", ("input.fa", b">a\nAAAA\n", "text/plain")),
+        ],
+    )
+
+    assert response.status_code == 202
+    assert response.json()["operation_id"] == "upload-1"
+    assert response.json()["state"] == "queued"
+    assert len(queued) == 1
+    assert queued[0]["action"] == "upload"
+    assert queued[0]["original_command"] == "bash count.sh input.fa"
+    assert (tmp_path / "store" / "staging" / "upload-1" / "raw_code" / "count.sh").is_file()
+    assert (tmp_path / "store" / "staging" / "upload-1" / "raw_test_data" / "input.fa").is_file()
+
+    duplicate = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data={
+            "extension_id": "count_fasta",
+            "original_command": "bash count.sh input.fa",
+            "operation_token": "upload-1",
+        },
+        files=[
+            ("raw_code_files", ("count.sh", b"ignored", "text/plain")),
+            ("raw_data_files", ("input.fa", b"ignored", "text/plain")),
+        ],
+    )
+    assert duplicate.status_code == 202
+    assert len(queued) == 1
+
+
+def test_retry_semantic_endpoint_enqueues_only_semantic_generation(tmp_path: Path) -> None:
+    client, queued = _client(tmp_path)
+
+    response = client.post(
+        "/api/lightweight-extension-stages/count_fasta/retry-semantic",
+        json={"operation_token": "semantic-2"},
+    )
+
+    assert response.status_code == 202
+    assert response.json()["operation_id"] == "semantic-2"
+    assert queued == [
+        {
+            "extension_id": "count_fasta",
+            "action": "retry_semantic",
+            "operation_token": "semantic-2",
+        }
+    ]
+
+
+def test_upload_accepts_single_code_entry_without_original_command(tmp_path: Path) -> None:
+    client, queued = _client(tmp_path)
+
+    response = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data={"extension_id": "code_only", "operation_token": "upload-code-only"},
+        files=[
+            ("raw_code_files", ("run.sh", b"printf 'ok\\n' > result.txt\n", "text/plain")),
+            ("raw_data_files", ("input.fa", b">a\nAAAA\n", "text/plain")),
+        ],
+    )
+
+    assert response.status_code == 202
+    assert queued[0]["original_command"] == "bash run.sh"
+
+
+def test_upload_accepts_original_command_without_code_file(tmp_path: Path) -> None:
+    client, queued = _client(tmp_path)
+
+    response = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data={
+            "extension_id": "command_only",
+            "original_command": "wc -l input.txt",
+            "operation_token": "upload-command-only",
+        },
+        files=[("raw_data_files", ("input.txt", b"one\ntwo\n", "text/plain"))],
+    )
+
+    assert response.status_code == 202
+    assert queued[0]["original_command"] == "bash run.sh"
+    run_sh = tmp_path / "store" / "staging" / "upload-command-only" / "raw_code" / "run.sh"
+    assert run_sh.is_file()
+    assert "wc -l input.txt" in run_sh.read_text(encoding="utf-8")
+
+
+def test_upload_accepts_server_data_file_as_symlink(tmp_path: Path) -> None:
+    client, queued = _client(tmp_path)
+    source = tmp_path / "large" / "input.txt"
+    source.parent.mkdir()
+    source.write_text("one\ntwo\n", encoding="utf-8")
+
+    response = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data={
+            "extension_id": "server_path",
+            "original_command": "wc -l input.txt",
+            "operation_token": "upload-server-path",
+            "raw_data_paths": str(source),
+        },
+    )
+
+    assert response.status_code == 202
+    assert len(queued) == 1
+    staged = tmp_path / "store" / "staging" / "upload-server-path" / "raw_test_data" / "input.txt"
+    assert staged.is_symlink()
+    assert staged.resolve() == source.resolve()
+
+
+def test_upload_expands_server_data_directory_preserving_relative_layout(tmp_path: Path) -> None:
+    client, queued = _client(tmp_path)
+    source = tmp_path / "large_case"
+    (source / "nested").mkdir(parents=True)
+    (source / "input.fa").write_text(">a\nAAAA\n", encoding="utf-8")
+    (source / "nested" / "model.hmm").write_text("HMMER3/f\n", encoding="utf-8")
+
+    response = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data={
+            "extension_id": "server_directory",
+            "original_command": "printf ok",
+            "operation_token": "upload-server-directory",
+            "raw_data_paths": str(source),
+        },
+    )
+
+    assert response.status_code == 202
+    assert len(queued) == 1
+    staged = tmp_path / "store" / "staging" / "upload-server-directory" / "raw_test_data"
+    assert (staged / "input.fa").is_symlink()
+    assert (staged / "nested" / "model.hmm").is_symlink()
+
+
+def test_upload_rejects_missing_server_data_path(tmp_path: Path) -> None:
+    client, queued = _client(tmp_path)
+    missing = tmp_path / "missing.fa"
+
+    response = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data={
+            "extension_id": "missing_server_path",
+            "original_command": "wc -l missing.fa",
+            "operation_token": "upload-missing-server-path",
+            "raw_data_paths": str(missing),
+        },
+    )
+
+    assert response.status_code == 400
+    assert f"测试数据路径不存在：{missing}" in response.json()["detail"]["message"]
+    assert queued == []
+
+
+def test_upload_rejects_uploaded_and_server_path_name_collision(tmp_path: Path) -> None:
+    client, queued = _client(tmp_path)
+    source = tmp_path / "large" / "input.txt"
+    source.parent.mkdir()
+    source.write_text("server\n", encoding="utf-8")
+
+    response = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data={
+            "extension_id": "data_collision",
+            "original_command": "wc -l input.txt",
+            "operation_token": "upload-data-collision",
+            "raw_data_paths": str(source),
+        },
+        files=[("raw_data_files", ("input.txt", b"upload\n", "text/plain"))],
+    )
+
+    assert response.status_code == 400
+    assert "测试数据文件名冲突：input.txt" in response.json()["detail"]["message"]
+    assert queued == []
+
+
+def test_server_path_submission_runs_real_raw_baseline(tmp_path: Path) -> None:
+    from gfa_core.extension_stage_lightweight.evidence import run_raw_baseline
+
+    client, queued = _client(tmp_path)
+    source = tmp_path / "external_data" / "input.fa"
+    source.parent.mkdir()
+    source.write_text(">a\nAAAA\n>b\nBBBB\n", encoding="utf-8")
+
+    response = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data={
+            "extension_id": "real_server_path",
+            "operation_token": "upload-real-server-path",
+            "raw_data_paths": str(source),
+        },
+        files=[
+            ("raw_code_files", ("count.sh", b"grep -c '^>' input.fa\n", "text/plain")),
+        ],
+    )
+
+    assert response.status_code == 202
+    assert queued[0]["original_command"] == "bash count.sh"
+    staged = tmp_path / "store" / "staging" / "upload-real-server-path"
+    evidence = run_raw_baseline(
+        command=queued[0]["original_command"],
+        raw_code=staged / "raw_code",
+        raw_data=staged / "raw_test_data",
+        run_dir=tmp_path / "real_baseline",
+    )
+
+    assert evidence["success"] is True
+    assert evidence["outputs"]["stdout"]["preview"] == "2"
+    assert (staged / "raw_test_data" / "input.fa").is_symlink()
+    assert source.read_text(encoding="utf-8").startswith(">a")
+
+
+def test_upload_rejects_ambiguous_code_without_original_command(tmp_path: Path) -> None:
+    client, queued = _client(tmp_path)
+
+    response = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data={"extension_id": "ambiguous", "operation_token": "upload-ambiguous"},
+        files=[
+            ("raw_code_files", ("run_a.sh", b"echo a\n", "text/plain")),
+            ("raw_code_files", ("run_b.sh", b"echo b\n", "text/plain")),
+            ("raw_data_files", ("input.txt", b"data\n", "text/plain")),
+        ],
+    )
+
+    assert response.status_code == 400
+    assert "multiple shell entry candidates" in response.json()["detail"]["message"]
+    assert "provide original_command" in response.json()["detail"]["message"]
+    assert queued == []
+
+
+def test_upload_rejects_when_command_and_code_are_both_missing(tmp_path: Path) -> None:
+    client, queued = _client(tmp_path)
+
+    response = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data={"extension_id": "missing_entry", "operation_token": "upload-missing"},
+        files=[("raw_data_files", ("input.txt", b"data\n", "text/plain"))],
+    )
+
+    assert response.status_code == 400
+    assert "no command or code file was provided" in response.json()["detail"]["message"]
+    assert queued == []
+
+
+def test_operation_poll_and_stop_are_isolated_to_lightweight_service(tmp_path: Path) -> None:
+    service = _FakeService()
+    _receipt(tmp_path)
+    client, _queued = _client(tmp_path, service)
+
+    poll = client.get("/api/lightweight-extension-stages/operations/validate-1")
+    assert poll.status_code == 200
+    assert poll.json()["state"] == "running"
+    assert poll.json()["status"] == "validation_running"
+
+    stopped = client.post(
+        "/api/lightweight-extension-stages/count_fasta/operations/validate-1/stop"
+    )
+    assert stopped.status_code == 200
+    assert stopped.json()["stopped"] is True
+    assert service.stops == [("count_fasta", "validate-1")]
+
+
+def test_operation_failure_reports_phase_message_and_logs(tmp_path: Path) -> None:
+    service = _FakeService(
+        {
+            "extension_id": "count_fasta",
+            "status": "validation_failed",
+            "error": {"phase": "validation", "message": "input binding failed"},
+            "operations": {
+                "validate-1": {
+                    "action": "validate",
+                    "state": "completed",
+                    "response": {"operation_token": "validate-1", "action": "validate"},
+                }
+            },
+            "validation_runs": [
+                {"run_id": "validation_1", "logs": {"stdout": "logs/stdout.log", "stderr": "logs/stderr.log"}}
+            ],
+            "runtime_runs": [],
+        }
+    )
+    _receipt(tmp_path)
+    client, _queued = _client(tmp_path, service)
+
+    response = client.get("/api/lightweight-extension-stages/operations/validate-1")
+
+    assert response.status_code == 200
+    payload = response.json()
+    assert payload["error"] == {"phase": "validation", "message": "input binding failed"}
+    assert payload["logs"] == ["logs/stderr.log", "logs/stdout.log"]
+
+
+def test_result_file_must_be_a_listed_safe_output(tmp_path: Path) -> None:
+    output = tmp_path / "store" / "extensions" / "count_fasta" / "runs" / "validation_1" / "outputs" / "result.txt"
+    output.parent.mkdir(parents=True)
+    output.write_text("answer\n", encoding="utf-8")
+    service = _FakeService(
+        {
+            "extension_id": "count_fasta",
+            "status": "published",
+            "operations": {},
+            "validation_runs": [
+                {
+                    "run_id": "validation_1",
+                    "projection": {"files": [{"path": "result.txt", "absolute_path": str(output)}]},
+                }
+            ],
+            "runtime_runs": [],
+        }
+    )
+    client, _queued = _client(tmp_path, service)
+
+    allowed = client.get(
+        "/api/lightweight-extension-stages/count_fasta/files",
+        params={"run_id": "validation_1", "path": "result.txt"},
+    )
+    rejected = client.get(
+        "/api/lightweight-extension-stages/count_fasta/files",
+        params={"run_id": "validation_1", "path": "../result.txt"},
+    )
+
+    assert allowed.status_code == 200
+    assert allowed.text == "answer\n"
+    assert rejected.status_code == 400
+
+
+def test_list_route_reads_only_lightweight_store_records(tmp_path: Path) -> None:
+    record = tmp_path / "store" / "extensions" / "count_fasta" / "extension.json"
+    record.parent.mkdir(parents=True)
+    record.write_text(
+        json.dumps({"extension_id": "count_fasta", "status": "published"}),
+        encoding="utf-8",
+    )
+    client, _queued = _client(tmp_path)
+
+    response = client.get("/api/lightweight-extension-stages/")
+
+    assert response.status_code == 200
+    assert response.json()["extensions"] == [
+        {"extension_id": "count_fasta", "status": "published"}
+    ]
+
+
+def test_invalid_submission_uses_structured_phase_error(tmp_path: Path) -> None:
+    client, _queued = _client(tmp_path)
+
+    response = client.post(
+        "/api/lightweight-extension-stages/count_fasta/validate",
+        json={"operation_token": "../unsafe"},
+    )
+
+    assert response.status_code == 400
+    assert response.json()["detail"] == {
+        "phase": "validate",
+        "message": "operation_token must be one safe path component",
+        "logs": [],
+    }
+
+
+def test_same_token_concurrent_reservation_has_one_winner(tmp_path: Path) -> None:
+    from gfa_core.extension_stage_lightweight.api import (
+        LightweightApiSettings,
+        _reserve_operation,
+    )
+
+    settings = LightweightApiSettings(tmp_path, tmp_path / "store", tmp_path / "input", tmp_path / "workspace")
+    start = threading.Barrier(8)
+    created: list[bool] = []
+
+    def reserve() -> None:
+        start.wait()
+        _receipt, won = _reserve_operation(
+            settings, extension_id="count_fasta", action="validate", token="same-token"
+        )
+        created.append(won)
+
+    workers = [threading.Thread(target=reserve) for _ in range(8)]
+    for worker in workers:
+        worker.start()
+    for worker in workers:
+        worker.join(timeout=3)
+
+    assert sum(created) == 1
+
+
+def test_bad_upload_leaves_no_receipt_and_same_token_can_retry(tmp_path: Path) -> None:
+    client, queued = _client(tmp_path)
+    fields = {
+        "extension_id": "count_fasta",
+        "original_command": "bash count.sh input.fa",
+        "operation_token": "upload-retry",
+    }
+    bad = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data=fields,
+        files=[
+            ("raw_code_files", ("..\\count.sh", b"bad", "text/plain")),
+            ("raw_data_files", ("input.fa", b">a\n", "text/plain")),
+        ],
+    )
+    assert bad.status_code == 400
+    assert not (tmp_path / "store" / "operations" / "upload-retry.json").exists()
+    good = client.post(
+        "/api/lightweight-extension-stages/upload",
+        data=fields,
+        files=[
+            ("raw_code_files", ("count.sh", b"grep -c '^>' input.fa\n", "text/plain")),
+            ("raw_data_files", ("input.fa", b">a\n", "text/plain")),
+        ],
+    )
+
+    assert good.status_code == 202
+    assert len(queued) == 1
+
+
+def test_generic_intent_returns_standard_usage_without_extension_lookup(tmp_path: Path) -> None:
+    client, _queued = _client(tmp_path)
+
+    response = client.post(
+        "/api/lightweight-extension-stages/intent", json={"message": "如何使用拓展分析阶段？"}
+    )
+
+    assert response.status_code == 200
+    assert "上传" in response.json()["usage"]
+    assert "自然语言" in response.json()["usage"]
+
+
+def test_poll_keeps_operation_snapshot_and_reports_later_extension_status(tmp_path: Path) -> None:
+    service = _FakeService(
+        {
+            "extension_id": "count_fasta",
+            "status": "published",
+            "operations": {
+                "validate-1": {
+                    "action": "validate",
+                    "state": "completed",
+                    "run_id": "validation_1",
+                    "response": {"status": "result_review_pending", "run_id": "validation_1"},
+                }
+            },
+            "validation_runs": [{"run_id": "validation_1", "success": True, "contract_passed": True}],
+            "runtime_runs": [],
+        }
+    )
+    _receipt(tmp_path)
+    client, _queued = _client(tmp_path, service)
+
+    response = client.get("/api/lightweight-extension-stages/operations/validate-1")
+
+    assert response.status_code == 200
+    assert response.json()["status"] == "result_review_pending"
+    assert response.json()["extension_status"] == "published"
+
+
+def test_poll_reports_failed_runtime_run_even_when_extension_is_published(tmp_path: Path) -> None:
+    service = _FakeService(
+        {
+            "extension_id": "count_fasta",
+            "status": "published",
+            "operations": {
+                "validate-1": {"action": "validate", "state": "completed", "response": {}},
+                "run-1": {
+                    "action": "run",
+                    "state": "completed",
+                    "run_id": "runtime_1",
+                    "response": {"status": "published", "run_id": "runtime_1"},
+                },
+            },
+            "validation_runs": [],
+            "runtime_runs": [
+                {
+                    "run_id": "runtime_1",
+                    "success": False,
+                    "contract_passed": False,
+                    "binding": {"status": "blocked", "error": {"message": "required input missing"}},
+                    "logs": {"stderr": "logs/runtime.stderr.log"},
+                }
+            ],
+        }
+    )
+    _receipt(tmp_path, token="run-1")
+    receipt = tmp_path / "store" / "operations" / "run-1.json"
+    receipt.write_text(
+        json.dumps({"operation_id": "run-1", "operation_token": "run-1", "extension_id": "count_fasta", "action": "run", "state": "completed", "status": "published"}),
+        encoding="utf-8",
+    )
+    client, _queued = _client(tmp_path, service)
+
+    response = client.get("/api/lightweight-extension-stages/operations/run-1")
+
+    assert response.status_code == 200
+    assert response.json()["outcome"] == "failed"
+    assert response.json()["error"] == {
+        "phase": "runtime",
+        "message": "required input missing",
+        "logs": ["logs/runtime.stderr.log"],
+    }
+
+
+def test_file_download_rejects_recorded_path_outside_expected_output_root(tmp_path: Path) -> None:
+    service = _FakeService(
+        {
+            "extension_id": "count_fasta",
+            "status": "published",
+            "operations": {},
+            "validation_runs": [
+                {
+                    "run_id": "validation_1",
+                    "projection": {"files": [{"path": "result.txt", "absolute_path": "/etc/hosts"}]},
+                }
+            ],
+            "runtime_runs": [],
+        }
+    )
+    client, _queued = _client(tmp_path, service)
+
+    response = client.get(
+        "/api/lightweight-extension-stages/count_fasta/files",
+        params={"run_id": "validation_1", "path": "result.txt"},
+    )
+
+    assert response.status_code == 400
+
+
+def test_file_download_rejects_symlink_escape_from_expected_output_root(tmp_path: Path) -> None:
+    output = tmp_path / "store" / "extensions" / "count_fasta" / "runs" / "validation_1" / "outputs" / "result.txt"
+    output.parent.mkdir(parents=True)
+    output.symlink_to("/etc/hosts")
+    service = _FakeService(
+        {
+            "extension_id": "count_fasta",
+            "status": "published",
+            "operations": {},
+            "validation_runs": [
+                {
+                    "run_id": "validation_1",
+                    "projection": {"files": [{"path": "result.txt", "absolute_path": str(output)}]},
+                }
+            ],
+            "runtime_runs": [],
+        }
+    )
+    client, _queued = _client(tmp_path, service)
+
+    response = client.get(
+        "/api/lightweight-extension-stages/count_fasta/files",
+        params={"run_id": "validation_1", "path": "result.txt"},
+    )
+
+    assert response.status_code == 400
+
+
+def test_old_upload_poll_does_not_project_a_later_baseline_run(tmp_path: Path) -> None:
+    service = _FakeService(
+        {
+            "extension_id": "count_fasta",
+            "status": "confirmation_pending",
+            "operations": {
+                "upload-old": {
+                    "action": "upload",
+                    "state": "completed",
+                    "run_id": "baseline_old",
+                    "response": {"status": "baseline_failed", "run_id": "baseline_old"},
+                },
+                "rebuild-new": {
+                    "action": "rebuild",
+                    "state": "completed",
+                    "run_id": "baseline_new",
+                    "response": {"status": "confirmation_pending", "run_id": "baseline_new"},
+                },
+            },
+            "baseline": {
+                "run_dir": str(tmp_path / "store" / "extensions" / "count_fasta" / "baseline" / "baseline_new"),
+                "success": True,
+                "logs": {"stdout": "logs/new-baseline.stdout.log"},
+            },
+            "validation_runs": [],
+            "runtime_runs": [],
+        }
+    )
+    path = tmp_path / "store" / "operations" / "upload-old.json"
+    path.parent.mkdir(parents=True)
+    path.write_text(
+        json.dumps({"operation_id": "upload-old", "operation_token": "upload-old", "extension_id": "count_fasta", "action": "upload", "state": "completed", "status": "baseline_failed"}),
+        encoding="utf-8",
+    )
+    client, _queued = _client(tmp_path, service)
+
+    response = client.get("/api/lightweight-extension-stages/operations/upload-old")
+
+    assert response.status_code == 200
+    assert response.json()["status"] == "baseline_failed"
+    assert "outcome" not in response.json()
+    assert "logs" not in response.json()
+
+
+def test_upload_streaming_copy_uses_bounded_reads_and_preserves_content(tmp_path: Path) -> None:
+    from gfa_core.extension_stage_lightweight.api import UPLOAD_CHUNK_BYTES, _copy_upload_file
+
+    class _Upload:
+        filename = "large.bin"
+
+        def __init__(self, content: bytes) -> None:
+            self.content = content
+            self.offset = 0
+            self.read_sizes: list[int] = []
+
+        async def read(self, size: int = -1) -> bytes:
+            self.read_sizes.append(size)
+            chunk = self.content[self.offset : self.offset + size]
+            self.offset += len(chunk)
+            return chunk
+
+    content = b"A" * (UPLOAD_CHUNK_BYTES * 2 + 17)
+    upload = _Upload(content)
+    destination = tmp_path / "large.bin"
+
+    asyncio.run(_copy_upload_file(upload, destination))
+
+    assert destination.read_bytes() == content
+    assert upload.read_sizes == [UPLOAD_CHUNK_BYTES] * 4
+
+
+def test_old_upload_poll_is_not_polluted_by_later_failed_rebuild(tmp_path: Path) -> None:
+    service = _FakeService(
+        {
+            "extension_id": "count_fasta",
+            "status": "baseline_failed",
+            "error": {"phase": "baseline", "message": "later rebuild failed"},
+            "operations": {
+                "upload-old": {
+                    "action": "upload",
+                    "state": "completed",
+                    "run_id": "baseline_old",
+                    "response": {"status": "baseline_failed", "run_id": "baseline_old"},
+                },
+                "rebuild-new": {
+                    "action": "rebuild",
+                    "state": "completed",
+                    "run_id": "baseline_new",
+                    "response": {"status": "baseline_failed", "run_id": "baseline_new"},
+                },
+            },
+            "baseline": {
+                "run_dir": str(tmp_path / "store" / "extensions" / "count_fasta" / "baseline" / "baseline_new"),
+                "success": False,
+                "logs": {"stderr": "logs/new-baseline.stderr.log"},
+            },
+            "validation_runs": [],
+            "runtime_runs": [],
+        }
+    )
+    path = tmp_path / "store" / "operations" / "upload-old.json"
+    path.parent.mkdir(parents=True)
+    path.write_text(
+        json.dumps({"operation_id": "upload-old", "operation_token": "upload-old", "extension_id": "count_fasta", "action": "upload", "state": "completed", "status": "baseline_failed"}),
+        encoding="utf-8",
+    )
+    client, _queued = _client(tmp_path, service)
+
+    response = client.get("/api/lightweight-extension-stages/operations/upload-old")
+
+    assert response.status_code == 200
+    assert "outcome" not in response.json()
+    assert "error" not in response.json()
+    assert "logs" not in response.json()
+
+
+def test_current_pre_evidence_baseline_failure_is_saved_on_its_receipt(
+    tmp_path: Path, monkeypatch
+) -> None:
+    import gfa_core.extension_stage_lightweight.api as api
+
+    settings = api.LightweightApiSettings(
+        project_root=tmp_path,
+        store_root=tmp_path / "store",
+        input_root=tmp_path / "input",
+        workspace_root=tmp_path / "workspace",
+    )
+    api._write_json(
+        api._receipt_path(settings, "upload-current"),
+        {"operation_id": "upload-current", "operation_token": "upload-current", "extension_id": "count_fasta", "action": "upload", "state": "queued", "status": "queued"},
+    )
+    record = {
+        "extension_id": "count_fasta",
+        "status": "baseline_failed",
+        "error": {"phase": "baseline", "message": "command failed before evidence"},
+        "operations": {
+            "upload-current": {
+                "action": "upload",
+                "state": "completed",
+                "run_id": "baseline_current",
+                "response": {"status": "baseline_failed", "run_id": "baseline_current"},
+            }
+        },
+        "validation_runs": [],
+        "runtime_runs": [],
+    }
+
+    class _CurrentFailureService:
+        def upload(self, **_kwargs):
+            return {"status": "baseline_failed"}
+
+        def get(self, extension_id: str):
+            assert extension_id == "count_fasta"
+            return record
+
+    monkeypatch.setattr(api.LightweightApiSettings, "from_environment", classmethod(lambda _cls: settings))
+    monkeypatch.setattr(api, "_service_for", lambda _settings: _CurrentFailureService())
+
+    receipt = api.execute_queued_operation(
+        {
+            "action": "upload",
+            "extension_id": "count_fasta",
+            "operation_token": "upload-current",
+            "original_command": "bash count.sh input.fa",
+        }
+    )
+
+    assert receipt["error"] == {
+        "phase": "baseline",
+        "message": "command failed before evidence",
+        "logs": [],
+    }
+
+
+def test_current_pre_evidence_rebuild_failure_does_not_inherit_prior_baseline_logs(
+    tmp_path: Path, monkeypatch
+) -> None:
+    import gfa_core.extension_stage_lightweight.api as api
+
+    settings = api.LightweightApiSettings(tmp_path, tmp_path / "store", tmp_path / "input", tmp_path / "workspace")
+    api._write_json(
+        api._receipt_path(settings, "rebuild-current"),
+        {"operation_id": "rebuild-current", "operation_token": "rebuild-current", "extension_id": "count_fasta", "action": "rebuild", "state": "queued", "status": "queued"},
+    )
+    record = {
+        "extension_id": "count_fasta",
+        "status": "baseline_failed",
+        "error": {"phase": "baseline", "message": "rebuild failed before evidence"},
+        "operations": {
+            "rebuild-current": {
+                "action": "rebuild",
+                "state": "completed",
+                "run_id": "baseline_current",
+                "response": {"status": "baseline_failed", "run_id": "baseline_current"},
+            }
+        },
+        "baseline": {
+            "run_dir": str(tmp_path / "store" / "extensions" / "count_fasta" / "baseline" / "baseline_prior"),
+            "logs": {"stderr": "logs/prior-baseline.stderr.log"},
+        },
+        "validation_runs": [],
+        "runtime_runs": [],
+    }
+
+    class _CurrentFailureService:
+        def rebuild(self, *_args, **_kwargs):
+            return {"status": "baseline_failed"}
+
+        def get(self, extension_id: str):
+            assert extension_id == "count_fasta"
+            return record
+
+    monkeypatch.setattr(api.LightweightApiSettings, "from_environment", classmethod(lambda _cls: settings))
+    monkeypatch.setattr(api, "_service_for", lambda _settings: _CurrentFailureService())
+
+    receipt = api.execute_queued_operation(
+        {"action": "rebuild", "extension_id": "count_fasta", "operation_token": "rebuild-current"}
+    )
+
+    assert receipt["error"]["logs"] == []
+
+
+def test_celery_task_is_explicitly_unlimited_and_main_registers_only_new_router() -> None:
+    root = Path(__file__).resolve().parents[2]
+    tasks = (root / "tasks.py").read_text(encoding="utf-8")
+    celery = (root / "celery_app.py").read_text(encoding="utf-8")
+    main = (root / "apps/web/vue3/main.py").read_text(encoding="utf-8")
+
+    assert 'name="tasks.execute_lightweight_extension_operation"' in tasks
+    assert "time_limit=None" in tasks
+    assert "soft_time_limit=None" in tasks
+    assert '"tasks.execute_lightweight_extension_operation"' in celery
+    assert "create_lightweight_extension_router" in main
+    assert "/api/extension-stages" not in (root / "gfa_core/extension_stage_lightweight/api.py").read_text(encoding="utf-8")
diff --git a/tests/unit/test_extension_stage_lightweight_command_model.py b/tests/unit/test_extension_stage_lightweight_command_model.py
new file mode 100644
index 000000000..80a3a19fc
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_command_model.py
@@ -0,0 +1,373 @@
+from pathlib import Path
+
+import pytest
+
+from gfa_core.extension_stage_lightweight.command_model import build_command_model
+
+
+def _file_state(*paths: str) -> dict[str, dict[str, object]]:
+    return {path: {"kind": "file", "size": 1, "sha256": path} for path in paths}
+
+
+def test_direct_command_retains_all_flags_and_binds_input(tmp_path: Path) -> None:
+    model = build_command_model(
+        command="iqtree -s Ft.SPL.pep.mfa -m MFP -bb 1000 -nt 4 -pre Ft.SPL.iqtree",
+        work_dir=tmp_path,
+        before_files=_file_state("Ft.SPL.pep.mfa"),
+        output_files=["Ft.SPL.iqtree.treefile", "Ft.SPL.iqtree.iqtree"],
+        code_files=[],
+    )
+
+    assert model["source_scripts"] == []
+    assert len(model["commands"]) == 1
+    command = model["commands"][0]
+    assert command["tool"] == "iqtree"
+    assert [item["flag"] for item in command["arguments"]] == [
+        "-s",
+        "-m",
+        "-bb",
+        "-nt",
+        "-pre",
+    ]
+    assert command["inputs"] == [
+        {
+            "path": "Ft.SPL.pep.mfa",
+            "source": "baseline_input",
+            "flag": "-s",
+            "token_index": 2,
+        }
+    ]
+    assert [(item["flag"], item["value"], item["kind"]) for item in command["parameters"]] == [
+        ("-m", "MFP", "flag_value"),
+        ("-bb", "1000", "flag_value"),
+        ("-nt", "4", "flag_value"),
+        ("-pre", "Ft.SPL.iqtree", "flag_value"),
+    ]
+    assert command["outputs"] == [
+        "Ft.SPL.iqtree.iqtree",
+        "Ft.SPL.iqtree.treefile",
+    ]
+
+
+def test_shell_script_is_expanded_per_command_with_switch_and_generated_input(
+    tmp_path: Path,
+) -> None:
+    script = tmp_path / "run.sh"
+    script.write_text(
+        """#!/usr/bin/env bash
+hmmsearch --cut_tc \\
+  --domtblout Ft.SPL.domtblout \\
+  -o Ft.SPL.hmmout \\
+  SBP.hmm Ft.pep.fasta
+python parse_hmmer.py Ft.SPL.domtblout > parsed.tsv
+""",
+        encoding="utf-8",
+    )
+    (tmp_path / "parse_hmmer.py").write_text("", encoding="utf-8")
+
+    model = build_command_model(
+        command="bash run.sh",
+        work_dir=tmp_path,
+        before_files=_file_state(
+            "run.sh", "parse_hmmer.py", "SBP.hmm", "Ft.pep.fasta"
+        ),
+        output_files=["Ft.SPL.domtblout", "Ft.SPL.hmmout", "parsed.tsv"],
+        code_files=["run.sh", "parse_hmmer.py"],
+    )
+
+    assert model["source_scripts"] == ["run.sh"]
+    assert [item["tool"] for item in model["commands"]] == ["hmmsearch", "python"]
+
+    search, parser = model["commands"]
+    assert [(item["path"], item["source"]) for item in search["inputs"]] == [
+        ("SBP.hmm", "baseline_input"),
+        ("Ft.pep.fasta", "baseline_input"),
+    ]
+    assert [(item["flag"], item["kind"], item["value"]) for item in search["parameters"]] == [
+        ("--cut_tc", "switch", "--cut_tc"),
+        ("--domtblout", "flag_value", "Ft.SPL.domtblout"),
+        ("-o", "flag_value", "Ft.SPL.hmmout"),
+    ]
+    assert search["outputs"] == ["Ft.SPL.domtblout", "Ft.SPL.hmmout"]
+
+    assert parser["source_files"] == ["parse_hmmer.py"]
+    assert parser["inputs"] == [
+        {
+            "path": "Ft.SPL.domtblout",
+            "source": "generated_input",
+            "flag": None,
+            "token_index": 2,
+        }
+    ]
+    assert parser["outputs"] == ["parsed.tsv"]
+    assert all(item["path"] != "run.sh" for item in parser["inputs"])
+
+
+def test_output_binding_uses_observed_artifact_not_known_flag_name(tmp_path: Path) -> None:
+    model = build_command_model(
+        command="unknown_tool --destination result.custom input.weird",
+        work_dir=tmp_path,
+        before_files=_file_state("input.weird"),
+        output_files=["result.custom"],
+        code_files=[],
+    )
+
+    command = model["commands"][0]
+    assert command["parameters"] == [
+        {
+            "kind": "flag_value",
+            "flag": "--destination",
+            "value": "result.custom",
+            "token_index": 1,
+            "value_role": "output_reference",
+        }
+    ]
+    assert command["outputs"] == ["result.custom"]
+    assert command["inputs"][0]["path"] == "input.weird"
+
+
+@pytest.mark.parametrize("quote", [pytest.param("'", id="single"), pytest.param('"', id="double")])
+def test_quoted_value_before_known_input_preserves_ambiguous_grouping(
+    tmp_path: Path, quote: str,
+) -> None:
+    model = build_command_model(
+        command=f"unknown_tool -x {quote}rewrite program{quote} input.txt",
+        work_dir=tmp_path,
+        before_files=_file_state("input.txt"),
+        output_files=[],
+        code_files=[],
+    )
+
+    command = model["commands"][0]
+    assert command["arguments"] == [
+        {
+            "kind": "switch",
+            "flag": "-x",
+            "value": "-x",
+            "token_index": 1,
+            "grouping_confidence": "ambiguous",
+        }
+    ]
+    assert command["parameters"] == [
+        {
+            "kind": "switch",
+            "flag": "-x",
+            "value": "-x",
+            "token_index": 1,
+            "grouping_confidence": "ambiguous",
+        },
+        {
+            "kind": "positional",
+            "flag": None,
+            "value": "rewrite program",
+            "token_index": 2,
+            "position": 0,
+            "value_role": "value",
+            "grouping_confidence": "ambiguous",
+        },
+    ]
+    assert command["inputs"] == [
+        {
+            "path": "input.txt",
+            "source": "baseline_input",
+            "flag": None,
+            "token_index": 3,
+        }
+    ]
+
+
+def test_quoted_candidate_without_later_input_keeps_flag_value(tmp_path: Path) -> None:
+    model = build_command_model(
+        command="unknown_tool -x 'rewrite program'",
+        work_dir=tmp_path,
+        before_files={},
+        output_files=[],
+        code_files=[],
+    )
+
+    command = model["commands"][0]
+    assert command["arguments"] == [
+        {
+            "kind": "flag_value",
+            "flag": "-x",
+            "value": "rewrite program",
+            "token_index": 1,
+            "value_role": "value",
+        }
+    ]
+    assert command["parameters"] == command["arguments"]
+
+
+@pytest.mark.parametrize(
+    ("candidate", "before_paths", "output_files", "code_files", "value_role"),
+    [
+        pytest.param(
+            "known input.txt",
+            ("known input.txt", "later.txt"),
+            [],
+            [],
+            "input",
+            id="baseline-input",
+        ),
+        pytest.param(
+            "script file.py",
+            ("script file.py", "later.txt"),
+            [],
+            ["script file.py"],
+            "value",
+            id="code-file",
+        ),
+        pytest.param(
+            "result file.txt",
+            ("later.txt",),
+            ["result file.txt"],
+            [],
+            "output_reference",
+            id="observed-output",
+        ),
+    ],
+)
+def test_quoted_candidate_reference_keeps_flag_value(
+    tmp_path: Path,
+    candidate: str,
+    before_paths: tuple[str, ...],
+    output_files: list[str],
+    code_files: list[str],
+    value_role: str,
+) -> None:
+    model = build_command_model(
+        command=f"unknown_tool -x '{candidate}' later.txt",
+        work_dir=tmp_path,
+        before_files=_file_state(*before_paths),
+        output_files=output_files,
+        code_files=code_files,
+    )
+
+    command = model["commands"][0]
+    assert command["arguments"][0] == {
+        "kind": "flag_value",
+        "flag": "-x",
+        "value": candidate,
+        "token_index": 1,
+        "value_role": value_role,
+    }
+    assert "grouping_confidence" not in command["arguments"][0]
+    assert any(item["path"] == "later.txt" for item in command["inputs"])
+
+
+def test_unaligned_posix_and_non_posix_tokens_keep_flag_value(tmp_path: Path) -> None:
+    model = build_command_model(
+        command=r"unknown_tool -x rewrite\ program input.txt",
+        work_dir=tmp_path,
+        before_files=_file_state("input.txt"),
+        output_files=[],
+        code_files=[],
+    )
+
+    command = model["commands"][0]
+    assert command["arguments"][0] == {
+        "kind": "flag_value",
+        "flag": "-x",
+        "value": "rewrite program",
+        "token_index": 1,
+        "value_role": "value",
+    }
+    assert "grouping_confidence" not in command["arguments"][0]
+
+
+def test_escaped_literal_quotes_in_argv_are_not_outer_shell_quotes(
+    tmp_path: Path,
+) -> None:
+    model = build_command_model(
+        command=r'unknown_tool -x \"rewrite\ program\" input.txt',
+        work_dir=tmp_path,
+        before_files=_file_state("input.txt"),
+        output_files=[],
+        code_files=[],
+    )
+
+    command = model["commands"][0]
+    assert command["arguments"][0] == {
+        "kind": "flag_value",
+        "flag": "-x",
+        "value": '"rewrite program"',
+        "token_index": 1,
+        "value_role": "value",
+    }
+    assert "grouping_confidence" not in command["arguments"][0]
+    assert command["inputs"][0]["path"] == "input.txt"
+
+
+def test_consecutive_ambiguous_pairs_keep_all_tokens_and_positions(
+    tmp_path: Path,
+) -> None:
+    model = build_command_model(
+        command="unknown_tool -x 'first program' -y 'second program' input.txt",
+        work_dir=tmp_path,
+        before_files=_file_state("input.txt"),
+        output_files=[],
+        code_files=[],
+    )
+
+    command = model["commands"][0]
+    assert [
+        (
+            item["kind"],
+            item["flag"],
+            item["value"],
+            item.get("position"),
+            item.get("grouping_confidence"),
+        )
+        for item in command["parameters"]
+    ] == [
+        ("switch", "-x", "-x", None, "ambiguous"),
+        ("positional", None, "first program", 0, "ambiguous"),
+        ("switch", "-y", "-y", None, "ambiguous"),
+        ("positional", None, "second program", 1, "ambiguous"),
+    ]
+    assert [(item["flag"], item["token_index"]) for item in command["arguments"]] == [
+        ("-x", 1),
+        ("-y", 3),
+    ]
+    assert command["inputs"][0]["token_index"] == 5
+
+
+def test_generated_input_evidence_excludes_candidate_and_triggers_later_pair(
+    tmp_path: Path,
+) -> None:
+    model = build_command_model(
+        command=(
+            "unknown_tool input.txt > 'generated candidate.txt' && "
+            "unknown_tool -x 'generated candidate.txt' input.txt && "
+            "unknown_tool input.txt > generated_later.txt && "
+            "unknown_tool -x 'rewrite program' generated_later.txt"
+        ),
+        work_dir=tmp_path,
+        before_files=_file_state("input.txt"),
+        output_files=["generated candidate.txt", "generated_later.txt"],
+        code_files=[],
+    )
+
+    candidate_command = model["commands"][1]
+    assert candidate_command["arguments"][0]["kind"] == "flag_value"
+    assert candidate_command["arguments"][0]["value_role"] == "input"
+    assert "grouping_confidence" not in candidate_command["arguments"][0]
+    assert candidate_command["inputs"][0]["source"] == "generated_input"
+
+    later_command = model["commands"][3]
+    assert [item["kind"] for item in later_command["parameters"]] == [
+        "switch",
+        "positional",
+    ]
+    assert all(
+        item["grouping_confidence"] == "ambiguous"
+        for item in later_command["parameters"]
+    )
+    assert later_command["inputs"] == [
+        {
+            "path": "generated_later.txt",
+            "source": "generated_input",
+            "flag": None,
+            "token_index": 3,
+        }
+    ]
diff --git a/tests/unit/test_extension_stage_lightweight_confirmation.py b/tests/unit/test_extension_stage_lightweight_confirmation.py
new file mode 100644
index 000000000..6268c1eee
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_confirmation.py
@@ -0,0 +1,287 @@
+from __future__ import annotations
+
+from copy import deepcopy
+import importlib
+
+import pytest
+
+
+def _module():
+    return importlib.import_module(
+        "gfa_core.extension_stage_lightweight.confirmation"
+    )
+
+
+def _facts_and_candidate() -> tuple[dict, dict]:
+    facts = {
+        "facts_sha256": "facts-v1",
+        "commands": [
+            {
+                "inputs": [{"fact_id": "step_001:input:001"}],
+                "parameters": [{"fact_id": "step_001:parameter:001"}],
+            }
+        ],
+        "outputs": {
+            "files": [{"fact_id": "output:file:001"}],
+            "stdout": {"present": False},
+        },
+    }
+    candidate = {
+        "facts_sha256": "facts-v1",
+        "function_summary": "Search sequences with a fixed HMM profile.",
+        "inputs": [
+            {
+                "fact_id": "step_001:input:001",
+                "role": "hmm_profile",
+                "description": "HMM profile used by the search.",
+                "replaceability": "fixed_resource",
+            }
+        ],
+        "parameters": [
+            {
+                "fact_id": "step_001:parameter:001",
+                "display_name": "trusted cutoff",
+                "description": "Use the trusted cutoff stored in the model.",
+            }
+        ],
+        "outputs": [
+            {
+                "fact_id": "output:file:001",
+                "description": "Domain table produced by the search.",
+                "result_role": "final",
+            }
+        ],
+    }
+    return facts, candidate
+
+
+def test_confirm_revise_and_cancel_have_distinct_non_ambiguous_states() -> None:
+    module = _module()
+    facts, candidate = _facts_and_candidate()
+    repair_history = [
+        {
+            "attempt": 1,
+            "status": "success",
+            "diff": [
+                {
+                    "section": "inputs",
+                    "fact_id": "step_001:input:001",
+                    "field": "replaceability",
+                    "before": "replaceable",
+                    "after": "fixed_resource",
+                }
+            ],
+        }
+    ]
+    confirmation = module.create_confirmation(
+        execution_facts=facts,
+        candidate=candidate,
+        repair_history=repair_history,
+    )
+
+    assert confirmation["status"] == "pending"
+    assert confirmation["accepted"] is False
+    assert confirmation["facts_sha256"] == "facts-v1"
+    assert len(confirmation["candidate_sha256"]) == 64
+    assert confirmation["candidate_version"].startswith("semantic_")
+    assert confirmation["summary"] == {
+        "function_summary": candidate["function_summary"],
+        "input_count": 1,
+        "parameter_count": 1,
+        "output_count": 1,
+        "revision_diff": repair_history[0]["diff"],
+    }
+
+    confirmed = module.apply_confirmation_action(
+        confirmation=confirmation,
+        action="confirm",
+        execution_facts=facts,
+        candidate=candidate,
+    )
+    assert confirmed["status"] == "confirmed"
+    assert confirmed["accepted"] is True
+    assert module.is_candidate_accepted(
+        confirmation=confirmed,
+        execution_facts=facts,
+        candidate=candidate,
+    )
+
+    cancelled = module.apply_confirmation_action(
+        confirmation=confirmation,
+        action="cancel",
+        execution_facts=facts,
+        candidate=candidate,
+    )
+    assert cancelled["status"] == "cancelled"
+    assert cancelled["accepted"] is False
+
+    revised = module.apply_confirmation_action(
+        confirmation=confirmation,
+        action="revise",
+        execution_facts=facts,
+        candidate=candidate,
+        feedback="HMM 文件应标记为固定资源",
+        revision_target="inputs.replaceability",
+    )
+    assert revised["status"] == "revision_requested"
+    assert revised["accepted"] is False
+    assert revised["route"] == "semantic_repair"
+    assert revised["feedback"] == "HMM 文件应标记为固定资源"
+    assert confirmation["status"] == "pending"
+
+    with pytest.raises(ValueError, match="non-empty feedback"):
+        module.apply_confirmation_action(
+            confirmation=confirmation,
+            action="revise",
+            execution_facts=facts,
+            candidate=candidate,
+            feedback="  ",
+            revision_target="inputs.description",
+        )
+
+
+def test_confirmation_cannot_be_reused_after_facts_or_candidate_change() -> None:
+    module = _module()
+    facts, candidate = _facts_and_candidate()
+    confirmation = module.create_confirmation(
+        execution_facts=facts,
+        candidate=candidate,
+    )
+    confirmed = module.apply_confirmation_action(
+        confirmation=confirmation,
+        action="confirm",
+        execution_facts=facts,
+        candidate=candidate,
+    )
+
+    changed_candidate = deepcopy(candidate)
+    changed_candidate["function_summary"] = "Revised scientific summary."
+    stale_candidate = module.apply_confirmation_action(
+        confirmation=confirmation,
+        action="confirm",
+        execution_facts=facts,
+        candidate=changed_candidate,
+    )
+    assert stale_candidate["status"] == "stale"
+    assert stale_candidate["stale_reason"] == "candidate_changed"
+    assert stale_candidate["accepted"] is False
+    assert not module.is_candidate_accepted(
+        confirmation=confirmed,
+        execution_facts=facts,
+        candidate=changed_candidate,
+    )
+
+    changed_facts = deepcopy(facts)
+    changed_facts["facts_sha256"] = "facts-v2"
+    stale_facts = module.apply_confirmation_action(
+        confirmation=confirmation,
+        action="confirm",
+        execution_facts=changed_facts,
+        candidate=candidate,
+    )
+    assert stale_facts["status"] == "stale"
+    assert stale_facts["stale_reason"] == "facts_changed"
+    assert stale_facts["accepted"] is False
+
+
+def test_revised_candidate_is_a_new_pending_version() -> None:
+    module = _module()
+    facts, candidate = _facts_and_candidate()
+    original = module.create_confirmation(
+        execution_facts=facts,
+        candidate=candidate,
+    )
+    revised_candidate = deepcopy(candidate)
+    revised_candidate["inputs"][0]["description"] = (
+        "Bundled HMM profile used as a fixed scientific resource."
+    )
+    revised = module.create_confirmation(
+        execution_facts=facts,
+        candidate=revised_candidate,
+        repair_history=[
+            {
+                "attempt": 1,
+                "status": "success",
+                "diff": [
+                    {
+                        "section": "inputs",
+                        "fact_id": "step_001:input:001",
+                        "field": "description",
+                        "before": candidate["inputs"][0]["description"],
+                        "after": revised_candidate["inputs"][0]["description"],
+                    }
+                ],
+            }
+        ],
+    )
+
+    assert revised["candidate_version"] != original["candidate_version"]
+    assert revised["status"] == "pending"
+    assert revised["accepted"] is False
+
+
+@pytest.mark.parametrize(
+    "target",
+    [
+        "semantic",
+        "function_summary",
+        "inputs.role",
+        "inputs.description",
+        "inputs.replaceability",
+        "parameters.display_name",
+        "parameters.description",
+        "outputs.description",
+        "outputs.result_role",
+    ],
+)
+def test_semantic_revision_targets_return_to_repair(target: str) -> None:
+    module = _module()
+    facts, candidate = _facts_and_candidate()
+    result = module.apply_confirmation_action(
+        confirmation=module.create_confirmation(
+            execution_facts=facts,
+            candidate=candidate,
+        ),
+        action="revise",
+        execution_facts=facts,
+        candidate=candidate,
+        feedback="请按我的科学语义说明修订",
+        revision_target=target,
+    )
+
+    assert result["status"] == "revision_requested"
+    assert result["route"] == "semantic_repair"
+    assert result["accepted"] is False
+
+
+@pytest.mark.parametrize(
+    "target",
+    [
+        "execution_facts.original_command",
+        "execution_facts.path",
+        "execution_facts.flag",
+        "execution_facts.value",
+        "execution_facts.default_value",
+        "execution_facts.observed_output",
+    ],
+)
+def test_fact_disputes_require_new_evidence_and_never_enter_deepseek(
+    target: str,
+) -> None:
+    module = _module()
+    facts, candidate = _facts_and_candidate()
+    result = module.apply_confirmation_action(
+        confirmation=module.create_confirmation(
+            execution_facts=facts,
+            candidate=candidate,
+        ),
+        action="revise",
+        execution_facts=facts,
+        candidate=candidate,
+        feedback="这个执行事实不正确",
+        revision_target=target,
+    )
+
+    assert result["status"] == "fact_dispute"
+    assert result["route"] == "recollect_execution_evidence"
+    assert result["accepted"] is False
diff --git a/tests/unit/test_extension_stage_lightweight_deepseek_semantics.py b/tests/unit/test_extension_stage_lightweight_deepseek_semantics.py
new file mode 100644
index 000000000..b7f50c671
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_deepseek_semantics.py
@@ -0,0 +1,364 @@
+from __future__ import annotations
+
+import importlib
+import json
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+from gfa_core.extension_stage_lightweight.converter import build_execution_facts
+from gfa_core.extension_stage_lightweight.evidence import run_raw_baseline
+
+
+def _module():
+    return importlib.import_module(
+        "gfa_core.extension_stage_lightweight.deepseek_semantics"
+    )
+
+
+def _write(root: Path, relative: str, content: str | bytes) -> Path:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if isinstance(content, bytes):
+        path.write_bytes(content)
+    else:
+        path.write_text(content, encoding="utf-8")
+    return path
+
+
+def _facts_and_code(tmp_path: Path) -> tuple[dict, Path]:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(
+        raw_code,
+        "run.sh",
+        "cp input.fa result.txt\nprintf 'baseline complete\\n'\n",
+    )
+    _write(raw_code, "large_helper.py", "x = 1\n" * 7000)
+    _write(raw_code, "compiled.bin", b"\x00\x01\x02\xff")
+    _write(raw_data, "input.fa", ">a\nAAAA\n")
+    evidence = run_raw_baseline(
+        command="bash run.sh",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+    return build_execution_facts(evidence), raw_code
+
+
+def _candidate(facts: dict) -> dict:
+    output_facts = list(facts["outputs"]["files"])
+    if facts["outputs"]["stdout"]["present"]:
+        output_facts.append(facts["outputs"]["stdout"])
+    return {
+        "facts_sha256": facts["facts_sha256"],
+        "function_summary": "Copy a FASTA file and report completion.",
+        "inputs": [
+            {
+                "fact_id": item["fact_id"],
+                "role": "input_sequences",
+                "description": "Uploaded FASTA sequences.",
+                "replaceability": "replaceable",
+            }
+            for command in facts["commands"]
+            for item in command["inputs"]
+        ],
+        "parameters": [
+            {
+                "fact_id": item["fact_id"],
+                "display_name": "explicit command value",
+                "description": "Value present in the original command.",
+            }
+            for command in facts["commands"]
+            for item in command["parameters"]
+        ],
+        "outputs": [
+            {
+                "fact_id": item["fact_id"],
+                "description": "Observed analysis output.",
+                "result_role": "final",
+            }
+            for item in output_facts
+        ],
+    }
+
+
+def _env_file(tmp_path: Path, *, include_key: bool = True) -> Path:
+    lines = [
+        "NEW_API_BASE_URL=https://api.example.test/v1",
+        "NEW_API_MODEL=deepseek-test",
+    ]
+    if include_key:
+        lines.append("NEW_API_KEY=secret-test-key")
+    return _write(tmp_path, ".env", "\n".join(lines) + "\n")
+
+
+class _FakeCompletions:
+    def __init__(self, response=None, error: Exception | None = None) -> None:
+        self.response = response
+        self.error = error
+        self.requests: list[dict] = []
+
+    def create(self, **kwargs):
+        self.requests.append(kwargs)
+        if self.error is not None:
+            raise self.error
+        return self.response
+
+
+class _FakeClient:
+    def __init__(self, response=None, error: Exception | None = None) -> None:
+        self.completions = _FakeCompletions(response=response, error=error)
+        self.chat = SimpleNamespace(completions=self.completions)
+
+
+def _response(content: str):
+    return SimpleNamespace(
+        id="request-123",
+        model="deepseek-test",
+        choices=[
+            SimpleNamespace(
+                message=SimpleNamespace(content=content), finish_reason="stop"
+            )
+        ],
+        usage=SimpleNamespace(
+            prompt_tokens=120,
+            completion_tokens=80,
+            total_tokens=200,
+        ),
+    )
+
+
+@pytest.mark.parametrize(
+    ("environ", "create_file", "expected_fragment"),
+    [
+        ({}, False, "BBAV5_PROJECT_ENV_FILE"),
+        ({"BBAV5_PROJECT_ENV_FILE": "missing.env"}, False, "does not exist"),
+        ({"BBAV5_PROJECT_ENV_FILE": "configured.env"}, True, "API key"),
+    ],
+)
+def test_configuration_requires_one_explicit_project_env_file(
+    tmp_path: Path,
+    environ: dict[str, str],
+    create_file: bool,
+    expected_fragment: str,
+) -> None:
+    module = _module()
+    resolved = dict(environ)
+    if "BBAV5_PROJECT_ENV_FILE" in resolved:
+        env_path = tmp_path / resolved["BBAV5_PROJECT_ENV_FILE"]
+        resolved["BBAV5_PROJECT_ENV_FILE"] = str(env_path)
+        if create_file:
+            _env_file(tmp_path, include_key=False).rename(env_path)
+
+    with pytest.raises(module.DeepSeekSemanticError) as raised:
+        module.load_deepseek_config(resolved)
+
+    assert raised.value.code == "configuration_error"
+    assert expected_fragment in str(raised.value)
+
+
+def test_success_request_contains_locked_facts_and_bounded_code_preview(
+    tmp_path: Path,
+) -> None:
+    module = _module()
+    facts, raw_code = _facts_and_code(tmp_path)
+    candidate = _candidate(facts)
+    api_candidate = dict(candidate)
+    api_candidate.pop("facts_sha256")
+    fake = _FakeClient(response=_response(json.dumps(api_candidate)))
+    env_file = _env_file(tmp_path)
+
+    actual, metadata = module.generate_semantic_candidate(
+        execution_facts=facts,
+        raw_code=raw_code,
+        environ={"BBAV5_PROJECT_ENV_FILE": str(env_file)},
+        client_factory=lambda config: fake,
+        attempt=3,
+    )
+
+    assert actual == candidate
+    request = fake.completions.requests[0]
+    assert request["model"] == "deepseek-test"
+    assert request["temperature"] == 0
+    assert request["max_tokens"] == 32000
+    assert request["response_format"] == {"type": "json_object"}
+    assert request["extra_body"] == {"thinking": {"type": "enabled"}}
+    assert metadata["finish_reason"] == "stop"
+    system_message = request["messages"][0]["content"]
+    assert "must not return or modify execution facts" in system_message
+    assert (
+        "exactly one entry for every supplied input, parameter, and output fact_id"
+        in system_message
+    )
+    assert "no omissions, duplicates, or extras" in system_message
+    assert "final means" in system_message
+    assert "intermediate means" in system_message
+    assert "unknown only" in system_message
+    payload = json.loads(request["messages"][1]["content"])
+    assert payload["execution_facts"] == facts
+    assert "facts_sha256" not in payload["required_candidate_shape"]
+    assert "generated_input" in payload["required_candidate_shape"]["inputs"][0][
+        "replaceability"
+    ]
+    assert payload["execution_facts"]["outputs"]["stdout"]["preview"] == (
+        "baseline complete"
+    )
+
+    previews = {item["path"]: item for item in payload["raw_code_preview"]["files"]}
+    assert previews["run.sh"]["kind"] == "text"
+    assert "content" in previews["run.sh"]
+    assert previews["large_helper.py"]["truncated"] is True
+    assert previews["compiled.bin"]["kind"] == "binary"
+    assert "content" not in previews["compiled.bin"]
+    assert "large_helper.py" in payload["raw_code_preview"]["truncated_files"]
+
+    assert metadata["model"] == "deepseek-test"
+    assert metadata["base_url"] == "https://api.example.test/v1"
+    assert metadata["api_key_alias"] == "NEW_API_KEY"
+    assert metadata["request_id"] == "request-123"
+    assert metadata["attempt"] == 3
+    assert metadata["usage"]["total_tokens"] == 200
+    assert "secret-test-key" not in json.dumps(request)
+    assert "secret-test-key" not in json.dumps(metadata)
+
+
+def test_api_cannot_override_system_bound_facts_digest(tmp_path: Path) -> None:
+    module = _module()
+    facts, raw_code = _facts_and_code(tmp_path)
+    api_candidate = _candidate(facts)
+    api_candidate["facts_sha256"] = "invented-digest"
+    fake = _FakeClient(response=_response(json.dumps(api_candidate)))
+
+    actual, metadata = module.generate_semantic_candidate(
+        execution_facts=facts,
+        raw_code=raw_code,
+        environ={"BBAV5_PROJECT_ENV_FILE": str(_env_file(tmp_path))},
+        client_factory=lambda config: fake,
+    )
+
+    assert actual["facts_sha256"] == facts["facts_sha256"]
+    assert metadata["discarded_fact_fields"] == ["facts_sha256"]
+
+
+def test_non_json_response_is_reported_separately(tmp_path: Path) -> None:
+    module = _module()
+    facts, raw_code = _facts_and_code(tmp_path)
+    fake = _FakeClient(response=_response("not json"))
+
+    with pytest.raises(module.DeepSeekSemanticError) as raised:
+        module.generate_semantic_candidate(
+            execution_facts=facts,
+            raw_code=raw_code,
+            environ={"BBAV5_PROJECT_ENV_FILE": str(_env_file(tmp_path))},
+            client_factory=lambda config: fake,
+        )
+
+    assert raised.value.code == "invalid_json"
+    assert raised.value.metadata["raw_response"] == "not json"
+
+
+def test_missing_input_replaceability_is_bound_from_locked_input_source(
+    tmp_path: Path,
+) -> None:
+    module = _module()
+    facts, raw_code = _facts_and_code(tmp_path)
+    api_candidate = _candidate(facts)
+    api_candidate.pop("facts_sha256")
+    for item in api_candidate["inputs"]:
+        item.pop("replaceability")
+    fake = _FakeClient(response=_response(json.dumps(api_candidate)))
+
+    actual, metadata = module.generate_semantic_candidate(
+        execution_facts=facts,
+        raw_code=raw_code,
+        environ={"BBAV5_PROJECT_ENV_FILE": str(_env_file(tmp_path))},
+        client_factory=lambda config: fake,
+    )
+
+    assert {item["replaceability"] for item in actual["inputs"]} == {
+        "replaceable"
+    }
+    assert {
+        item["action"] for item in metadata["fact_derived_semantic_bindings"]
+    } == {"bind_missing_input_replaceability"}
+
+
+def test_semantic_gate_error_is_not_reported_as_api_error(tmp_path: Path) -> None:
+    module = _module()
+    facts, raw_code = _facts_and_code(tmp_path)
+    invalid = _candidate(facts)
+    invalid["original_command"] = "invented command"
+    fake = _FakeClient(response=_response(json.dumps(invalid)))
+
+    with pytest.raises(module.DeepSeekSemanticError) as raised:
+        module.generate_semantic_candidate(
+            execution_facts=facts,
+            raw_code=raw_code,
+            environ={"BBAV5_PROJECT_ENV_FILE": str(_env_file(tmp_path))},
+            client_factory=lambda config: fake,
+        )
+
+    assert raised.value.code == "semantic_candidate_invalid"
+    assert raised.value.metadata["system_bound_candidate"]["facts_sha256"] == facts[
+        "facts_sha256"
+    ]
+    assert any(
+        error["field"] == "original_command"
+        for error in raised.value.metadata["validation_errors"]
+    )
+
+
+def test_unknown_model_reference_is_discarded_before_field_repair(
+    tmp_path: Path,
+) -> None:
+    module = _module()
+    facts, raw_code = _facts_and_code(tmp_path)
+    invalid = _candidate(facts)
+    wrong_fact_id = invalid["parameters"][0]["fact_id"]
+    invalid["outputs"][0]["fact_id"] = wrong_fact_id
+    fake = _FakeClient(response=_response(json.dumps(invalid)))
+
+    with pytest.raises(module.DeepSeekSemanticError) as raised:
+        module.generate_semantic_candidate(
+            execution_facts=facts,
+            raw_code=raw_code,
+            environ={"BBAV5_PROJECT_ENV_FILE": str(_env_file(tmp_path))},
+            client_factory=lambda config: fake,
+        )
+
+    assert raised.value.code == "semantic_candidate_invalid"
+    assert wrong_fact_id not in {
+        item["fact_id"]
+        for item in raised.value.metadata["system_bound_candidate"]["outputs"]
+    }
+    assert raised.value.metadata["fact_derived_semantic_bindings"] == [
+        {
+            "action": "discard_unknown_reference",
+            "section": "outputs",
+            "fact_id": wrong_fact_id,
+        }
+    ]
+    assert all(
+        error["code"] == "missing_fact_id"
+        for error in raised.value.metadata["validation_errors"]
+    )
+
+
+def test_api_error_is_redacted_and_classified(tmp_path: Path) -> None:
+    module = _module()
+    facts, raw_code = _facts_and_code(tmp_path)
+    fake = _FakeClient(error=RuntimeError("rejected secret-test-key"))
+
+    with pytest.raises(module.DeepSeekSemanticError) as raised:
+        module.generate_semantic_candidate(
+            execution_facts=facts,
+            raw_code=raw_code,
+            environ={"BBAV5_PROJECT_ENV_FILE": str(_env_file(tmp_path))},
+            client_factory=lambda config: fake,
+        )
+
+    assert raised.value.code == "api_request_failed"
+    assert "secret-test-key" not in str(raised.value)
+    assert raised.value.metadata["api_key_alias"] == "NEW_API_KEY"
diff --git a/tests/unit/test_extension_stage_lightweight_evidence.py b/tests/unit/test_extension_stage_lightweight_evidence.py
new file mode 100644
index 000000000..09af3cc37
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_evidence.py
@@ -0,0 +1,99 @@
+from pathlib import Path
+
+import pytest
+
+from gfa_core.extension_stage_lightweight.evidence import (
+    run_raw_baseline,
+    stage_package,
+)
+
+
+def _write(root: Path, relative: str, content: str) -> Path:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def test_stage_package_copies_code_and_symlinks_data(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    work = tmp_path / "run" / "work"
+    source_code = _write(raw_code, "scripts/run.sh", "wc -l input.fa\n")
+    source_data = _write(raw_data, "input.fa", ">a\nAAAA\n")
+
+    staged = stage_package(raw_code=raw_code, raw_data=raw_data, work_dir=work)
+
+    assert staged["code_files"] == ["scripts/run.sh"]
+    assert staged["data_files"] == ["input.fa"]
+    assert (work / "scripts/run.sh").read_text(encoding="utf-8") == source_code.read_text(
+        encoding="utf-8"
+    )
+    assert not (work / "scripts/run.sh").is_symlink()
+    assert (work / "input.fa").is_symlink()
+    assert (work / "input.fa").resolve() == source_data.resolve()
+
+
+def test_stage_package_rejects_same_relative_path(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(raw_code, "shared.txt", "code\n")
+    _write(raw_data, "shared.txt", "data\n")
+
+    with pytest.raises(ValueError, match=r"shared\.txt"):
+        stage_package(
+            raw_code=raw_code,
+            raw_data=raw_data,
+            work_dir=tmp_path / "run" / "work",
+        )
+
+
+def test_run_raw_baseline_records_new_and_modified_files(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(
+        raw_code,
+        "run.sh",
+        "printf 'result\\n' > result.txt\nprintf 'changed\\n' > existing.txt\nprintf 'done\\n'\n",
+    )
+    _write(raw_code, "existing.txt", "before\n")
+    _write(raw_data, "input.fa", ">a\nAAAA\n")
+
+    evidence = run_raw_baseline(
+        command="bash run.sh",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+
+    assert evidence["command"] == "bash run.sh"
+    assert evidence["returncode"] == 0
+    assert evidence["success"] is True
+    assert evidence["outputs"]["new_files"] == ["result.txt"]
+    assert evidence["outputs"]["modified_files"] == ["existing.txt"]
+    assert evidence["outputs"]["stdout"]["present"] is True
+    assert evidence["outputs"]["stdout"]["preview"] == "done"
+    assert Path(evidence["logs"]["stdout"]).read_text(encoding="utf-8") == "done\n"
+    assert Path(evidence["logs"]["stderr"]).is_file()
+    assert evidence["before_files"]["input.fa"]["kind"] == "symlink"
+    assert evidence["after_files"]["result.txt"]["size"] > 0
+
+
+def test_stdout_only_success_is_a_valid_output(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(raw_code, "count.sh", "grep -c '^>' input.fa\n")
+    _write(raw_data, "input.fa", ">a\nAAAA\n>b\nBBBB\n")
+
+    evidence = run_raw_baseline(
+        command="bash count.sh",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+
+    assert evidence["success"] is True
+    assert evidence["outputs"]["new_files"] == []
+    assert evidence["outputs"]["modified_files"] == []
+    assert evidence["outputs"]["stdout"]["present"] is True
+    assert evidence["outputs"]["stdout"]["preview"] == "2"
diff --git a/tests/unit/test_extension_stage_lightweight_fact_contract.py b/tests/unit/test_extension_stage_lightweight_fact_contract.py
new file mode 100644
index 000000000..aa916b981
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_fact_contract.py
@@ -0,0 +1,123 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from pathlib import Path
+
+from gfa_core.extension_stage_lightweight import converter
+from gfa_core.extension_stage_lightweight.evidence import run_raw_baseline
+
+
+def _write(root: Path, relative: str, content: str) -> Path:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def _two_step_evidence(tmp_path: Path) -> dict:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(
+        raw_code,
+        "run.sh",
+        "cp model.hmm intermediate.domtblout\n"
+        "python parse.py intermediate.domtblout > parsed.tsv\n",
+    )
+    _write(
+        raw_code,
+        "parse.py",
+        "from pathlib import Path\n"
+        "import sys\n"
+        "print(Path(sys.argv[1]).read_text(encoding='utf-8').strip())\n",
+    )
+    _write(raw_data, "model.hmm", "MODEL\n")
+    return run_raw_baseline(
+        command="bash run.sh",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+
+
+def test_build_execution_facts_locks_package_and_assigns_stable_ids(
+    tmp_path: Path,
+) -> None:
+    evidence = _two_step_evidence(tmp_path)
+    original = deepcopy(evidence)
+
+    facts = converter.build_execution_facts(evidence)
+
+    assert evidence == original
+    assert facts["original_command"] == "bash run.sh"
+    assert facts["package"]["code_files"] == ["parse.py", "run.sh"]
+    assert facts["package"]["data_files"] == ["model.hmm"]
+    assert facts["package"]["inventory"]["run.sh"]["source"] == "raw_code"
+    assert facts["package"]["inventory"]["model.hmm"]["source"] == "raw_test_data"
+    assert len(facts["package"]["inventory"]["model.hmm"]["sha256"]) == 64
+
+    first, second = facts["commands"]
+    assert first["step_id"] == "step_001"
+    assert second["step_id"] == "step_002"
+    assert first["inputs"][0]["fact_id"] == "step_001:input:001"
+    assert first["parameters"][0]["fact_id"] == "step_001:parameter:002"
+    assert second["inputs"][0]["source"] == "generated_input"
+    assert second["inputs"][0]["path"] == "intermediate.domtblout"
+    assert second["inputs"][0]["fact_id"] == "step_002:input:002"
+
+    outputs = {item["path"]: item for item in facts["outputs"]["files"]}
+    assert outputs["intermediate.domtblout"]["producer_step_ids"] == ["step_001"]
+    assert outputs["parsed.tsv"]["producer_step_ids"] == ["step_002"]
+    assert outputs["intermediate.domtblout"]["fact_id"] == "output:file:001"
+    assert outputs["parsed.tsv"]["fact_id"] == "output:file:002"
+    assert len(facts["facts_sha256"]) == 64
+
+
+def test_absent_stdout_is_not_exposed_as_a_semantic_fact(tmp_path: Path) -> None:
+    facts = converter.build_execution_facts(_two_step_evidence(tmp_path))
+
+    assert facts["outputs"]["stdout"]["present"] is False
+    assert "fact_id" not in facts["outputs"]["stdout"]
+
+
+def test_build_execution_facts_is_deterministic_for_same_evidence(
+    tmp_path: Path,
+) -> None:
+    evidence = _two_step_evidence(tmp_path)
+
+    first = converter.build_execution_facts(evidence)
+    second = converter.build_execution_facts(evidence)
+
+    assert first == second
+    assert first["facts_sha256"] == second["facts_sha256"]
+
+
+def test_build_execution_facts_keeps_unmatched_outputs_without_guessing(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(raw_code, "run.sh", "python make_output.py\n")
+    _write(
+        raw_code,
+        "make_output.py",
+        "from pathlib import Path\n"
+        "Path('dynamically_named.txt').write_text('result\\n', encoding='utf-8')\n",
+    )
+    raw_data.mkdir()
+    evidence = run_raw_baseline(
+        command="bash run.sh",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+
+    facts = converter.build_execution_facts(evidence)
+
+    assert facts["outputs"]["files"] == [
+        {
+            "fact_id": "output:file:001",
+            "path": "dynamically_named.txt",
+            "producer_step_ids": [],
+        }
+    ]
+    assert facts["unmatched_output_fact_ids"] == ["output:file:001"]
diff --git a/tests/unit/test_extension_stage_lightweight_frontend_contract.py b/tests/unit/test_extension_stage_lightweight_frontend_contract.py
new file mode 100644
index 000000000..9f44a6fed
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_frontend_contract.py
@@ -0,0 +1,250 @@
+from pathlib import Path
+import subprocess
+
+
+ROOT = Path(__file__).resolve().parents[2]
+FRONTEND = ROOT / "apps" / "web" / "vue3" / "index.html"
+
+
+def _source() -> str:
+    return FRONTEND.read_text(encoding="utf-8")
+
+
+def test_lightweight_extension_frontend_uses_new_api_and_conversation_cards() -> None:
+    source = _source()
+
+    assert "/api/lightweight-extension-stages/upload" in source
+    assert "lightweightExtensionConversation" in source
+    assert "拓展分析候选核对" in source
+    assert "提出修订意见" in source
+    assert "授权发布" in source
+
+
+def test_lightweight_extension_frontend_deduplicates_operations_and_cards() -> None:
+    source = _source()
+
+    assert "lightweightOperationPromises" in source
+    assert "lightweightConversationCardKeys" in source
+    assert "operation_token" in source
+    assert "card_id" in source
+
+
+def test_lightweight_published_run_button_does_not_pass_pointer_event_as_extension_id() -> None:
+    source = _source()
+
+    assert '@click="openLightweightRuntimeCard()"' in source
+
+
+def test_lightweight_extension_frontend_keeps_running_controls_and_stops_lightweight_operation() -> None:
+    source = _source()
+
+    assert "isExecuting.value = true" in source
+    assert "Polling" in source
+    assert "⏹ Stop" in source
+    assert "/operations/${encodeURIComponent(operationToken)}/stop" in source
+    assert "setInterval" in source
+
+
+def test_lightweight_extension_frontend_does_not_route_new_submission_through_legacy_gates() -> None:
+    source = _source()
+
+    start = source.index("const buildLightweightExtensionStage")
+    end = source.index("const buildExtensionStage", start)
+    lightweight = source[start:end]
+
+    assert "/api/extension-stages/build" not in lightweight
+    assert "nl-runtime-gate" not in lightweight
+    assert "frontend-e2e-gate" not in lightweight
+
+
+def test_lightweight_extension_frontend_accepts_command_or_code_with_required_data() -> None:
+    source = _source()
+    start = source.index("const buildLightweightExtensionStage")
+    end = source.index("const confirmLightweightCandidate", start)
+    upload = source[start:end]
+
+    assert "const hasCommand = Boolean(String(extensionBuild.command || '').trim());" in upload
+    assert "const hasCode = extensionBuild.codeFiles.length > 0;" in upload
+    assert "(!extensionBuild.dataFiles.length && !hasDataPaths) || (!hasCommand && !hasCode)" in upload
+    assert "请填写名称并提供测试数据文件或服务器路径；原始命令和原始代码至少提供一项。" in upload
+    assert "if (hasCommand) form.append('original_command', extensionBuild.command);" in upload
+    assert "请填写名称和原始命令，并上传原始代码与测试数据。" not in upload
+
+
+def test_lightweight_extension_api_errors_render_structured_details_in_node() -> None:
+    source = _source()
+    start = source.index("const extensionApiError")
+    end = source.index("const extensionApiUrl", start)
+    script = f"""
+const assert = require('assert');
+{source[start:end]}
+(async () => {{
+  const objectMessage = await extensionApiError({{
+    status: 400,
+    statusText: 'Bad Request',
+    json: async () => ({{detail: {{phase: 'upload', message: '缺少执行入口'}}}})
+  }}, '提交失败');
+  assert.strictEqual(objectMessage, '提交失败：缺少执行入口');
+
+  const validationMessage = await extensionApiError({{
+    status: 422,
+    statusText: 'Unprocessable Entity',
+    json: async () => ({{detail: [{{loc: ['body', 'raw_data_files'], msg: 'Field required'}}]}})
+  }}, '提交失败');
+  assert.strictEqual(validationMessage, '提交失败：Field required');
+}})().catch((error) => {{ console.error(error); process.exit(1); }});
+"""
+    result = subprocess.run(["/usr/bin/node", "-e", script], text=True, capture_output=True)
+    assert result.returncode == 0, result.stderr
+
+
+def test_lightweight_upload_card_uses_command_and_code_neutral_entry_wording() -> None:
+    source = _source()
+    start = source.index("const showLightweightCandidate")
+    end = source.index("const confirmLightweightCandidate", start)
+    upload = source[start:end]
+
+    assert "执行入口已在隔离环境运行" in upload
+    assert "系统正在确定执行入口，并运行上传的代码和测试数据" in upload
+    assert "✓ 执行入口已成功复现；候选信息已生成。" in upload
+    assert "原始命令已在隔离环境执行" not in upload
+    assert "系统正在以原始命令执行上传的代码和测试数据" not in upload
+
+
+def test_lightweight_extension_upload_reports_selection_and_server_acceptance() -> None:
+    source = _source()
+    handlers_start = source.index("const onExtensionCodeFilesChange")
+    handlers_end = source.index("const removeExtensionFile", handlers_start)
+    handlers = source[handlers_start:handlers_end]
+    upload_start = source.index("const buildLightweightExtensionStage")
+    upload_end = source.index("const confirmLightweightCandidate", upload_start)
+    upload = source[upload_start:upload_end]
+
+    assert "已选择 ${selected.length} 个原始代码文件" in handlers
+    assert "已选择 ${selected.length} 个测试数据文件" in handlers
+    assert "文件上传成功，已开始生成并验收" in upload
+    assert upload.index("if (!response.ok)") < upload.index("文件上传成功，已开始生成并验收")
+
+
+def test_lightweight_extension_frontend_accepts_uploaded_or_server_path_data() -> None:
+    source = _source()
+    upload_start = source.index("const buildLightweightExtensionStage")
+    upload_end = source.index("const confirmLightweightCandidate", upload_start)
+    upload = source[upload_start:upload_end]
+
+    assert 'v-model="extensionBuild.dataPaths"' in source
+    assert "每行填写一个绝对路径" in source
+    assert "const hasDataPaths = Boolean(String(extensionBuild.dataPaths || '').trim());" in upload
+    assert "(!extensionBuild.dataFiles.length && !hasDataPaths)" in upload
+    assert "form.append('raw_data_paths', extensionBuild.dataPaths);" in upload
+
+
+def test_lightweight_cards_render_in_main_chat_not_extension_form() -> None:
+    source = _source()
+    form_start = source.index("生成并验收")
+    main_chat = source.index('class="agent-chat-history"')
+    card_renderer = source.index('v-if="lightweightExtensionConversation.cards.length"')
+
+    assert 'lightweightExtensionConversation.cards.length' not in source[form_start:main_chat]
+    assert card_renderer > main_chat
+    assert 'class="role-badge ai"' in source[card_renderer - 500:card_renderer + 500]
+
+
+def test_lightweight_revision_uses_main_chat_input_without_inline_editor() -> None:
+    source = _source()
+    card_start = source.index('v-if="lightweightExtensionConversation.cards.length"')
+    card_end = source.index('<!-- 自然语言Input框 -->', card_start)
+    cards = source[card_start:card_end]
+    handler_start = source.index("const handleNlInput")
+    handler_end = source.index("// V2: RAG模式", handler_start)
+    handler = source[handler_start:handler_end]
+
+    assert 'v-model="card.feedback"' not in cards
+    assert 'v-model="card.revision_target"' not in cards
+    assert '@click="beginLightweightRevision(card)"' in cards
+    assert "pendingRevisionCardId" in source
+    assert "revision_target: 'semantic'" in source
+    assert "reviseLightweightCandidate(revisionCard, userInput)" in handler
+
+
+def test_semantic_candidate_failure_offers_semantic_only_retry() -> None:
+    source = _source()
+
+    assert "retry_semantic" in source
+    assert "retryLightweightSemantic(card)" in source
+    assert "/retry-semantic" in source
+    assert "只重新生成说明，不会重新运行原始命令" in source
+
+
+def test_lightweight_card_and_operation_dedup_helpers_execute_in_node() -> None:
+    source = _source()
+    card_start = source.index("const lightweightCardKey")
+    card_end = source.index("const finishLightweightCard", card_start)
+    poll_start = source.index("const pollLightweightOperation")
+    poll_end = source.index("const submitLightweightOperation", poll_start)
+    script = f"""
+const assert = require('assert');
+const reactive = (value) => value;
+const lightweightExtensionConversation = {{ cards: [] }};
+const lightweightConversationCardKeys = new Set();
+{source[card_start:card_end]}
+const first = addLightweightCard({{ card_id: 'candidate', status: 'pending' }});
+const duplicate = addLightweightCard({{ card_id: 'candidate', status: 'pending' }});
+assert(first);
+assert.strictEqual(duplicate, null);
+assert.strictEqual(lightweightExtensionConversation.cards.length, 1);
+
+const lightweightOperationPromises = new Map();
+const extensionApiFetch = async () => ({{ ok: true, json: async () => ({{ state: 'completed', status: 'confirmed' }}) }});
+const setLightweightRunning = () => {{}};
+const clearLightweightRunning = () => {{}};
+const forgetLightweightOperation = () => {{}};
+const window = {{ setTimeout: (callback) => setTimeout(callback, 0) }};
+{source[poll_start:poll_end]}
+(async () => {{
+  const card = {{ loading: true }};
+  let completed = 0;
+  const one = pollLightweightOperation('demo', 'same-token', card, async () => {{ completed += 1; }});
+  const two = pollLightweightOperation('demo', 'same-token', card, async () => {{ completed += 1; }});
+  assert.strictEqual(one, two);
+  await one;
+  assert.strictEqual(completed, 1);
+  assert.strictEqual(lightweightOperationPromises.size, 0);
+}})().catch((error) => {{ console.error(error); process.exit(1); }});
+"""
+    result = subprocess.run(["/usr/bin/node", "-e", script], text=True, capture_output=True)
+    assert result.returncode == 0, result.stderr
+
+
+def test_lightweight_frontend_phase_b_closure_helpers_execute_in_one_node_script() -> None:
+    source = _source()
+    helper_start = source.index("const isLightweightExtensionId")
+    helper_end = source.index("const buildLightweightExtensionStage", helper_start)
+    script = f"""
+const assert = require('assert');
+const lightweightExtensions = {{ value: [{{ extension_id: 'lightweight_tree', status: 'published' }}] }};
+{source[helper_start:helper_end]}
+assert.strictEqual(isLightweightExtensionId('lightweight_tree'), true);
+assert.strictEqual(isLightweightExtensionId('legacy_tree'), false);
+const runs = [{{ run_id: 'run_old' }}, {{ run_id: 'run_new' }}];
+assert.deepStrictEqual(lightweightRunById(runs, 'run_old'), {{ run_id: 'run_old' }});
+assert.strictEqual(lightweightResumeNext('upload'), 'candidate');
+assert.strictEqual(lightweightResumeNext('confirm'), 'validate');
+assert.strictEqual(lightweightResumeNext('revise'), 'candidate');
+assert.strictEqual(lightweightResumeNext('validate'), 'review');
+assert.strictEqual(lightweightResumeNext('review'), 'publish');
+assert.strictEqual(lightweightResumeNext('publish'), 'list');
+assert.strictEqual(lightweightResumeNext('run'), 'runtime_result');
+assert.strictEqual(lightweightCandidateConfirmationSummary({{ revision_summary: 'parameters.description' }}), '✓ 已确认候选｜已修订：parameters.description');
+assert.strictEqual(lightweightCandidateConfirmationSummary({{}}), '✓ 已确认候选｜未作修订');
+const rows = lightweightResultRows({{ execution_command: 'bash run.sh', projection: {{ files: [], stdout: {{ present: true, text: '42\\n' }} }}, logs: {{ stdout: 'stdout.log' }} }});
+assert.strictEqual(rows.find((row) => row.item === '标准输出').value, '42\\n');
+assert.strictEqual(lightweightParameterText({{ flag: '--cut_tc', value: 'true', fact_id: 'p1' }}), '--cut_tc = true');
+const parameterRows = lightweightRows({{ inputs: [], parameters: [{{ flag: '--cut_tc', value: 'true', fact_id: 'p1' }}], outputs: {{ stdout: {{ present: false }} }} }});
+assert.strictEqual(parameterRows.find((row) => row.item === '可改参数').value, '--cut_tc = true');
+"""
+    result = subprocess.run(["/usr/bin/node", "-e", script], text=True, capture_output=True)
+    assert result.returncode == 0, result.stderr
+    intent = source[source.index("const runExtensionStageFromIntent"):source.index("const extensionOutputIcon")]
+    assert "if (isLightweightExtensionId(extensionId))" in intent
+    assert intent.index("openLightweightRuntimeCard(extensionId)") < intent.index("executeExtensionStageRun(")
diff --git a/tests/unit/test_extension_stage_lightweight_process_control.py b/tests/unit/test_extension_stage_lightweight_process_control.py
new file mode 100644
index 000000000..28af8632f
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_process_control.py
@@ -0,0 +1,583 @@
+from __future__ import annotations
+
+import os
+import hashlib
+import json
+from pathlib import Path
+import signal
+import subprocess
+import sys
+import threading
+import time
+
+import gfa_core.extension_stage_lightweight.process_control as process_module
+import pytest
+from gfa_core.extension_stage_lightweight.evidence import run_raw_baseline
+from gfa_core.extension_stage_lightweight.process_control import (
+    start_managed_process,
+    stop_process_group,
+)
+from gfa_core.extension_stage_lightweight.runtime_binding import (
+    render_runtime_package,
+    replay_runtime_binding,
+    resolve_runtime_bindings,
+)
+
+
+def _write(root: Path, relative: str, content: str) -> Path:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def _wait_for(path: Path) -> None:
+    deadline = time.monotonic() + 5
+    while not path.is_file() and time.monotonic() < deadline:
+        time.sleep(0.01)
+    assert path.is_file()
+
+
+def _pid_is_running(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    return True
+
+
+def _pid_start_time(pid: int) -> int:
+    fields = Path(f"/proc/{pid}/stat").read_text(encoding="utf-8").split()
+    return int(fields[21])
+
+
+def _force_stop(identity: dict[str, int]) -> None:
+    if identity:
+        try:
+            os.killpg(identity["pgid"], 9)
+        except ProcessLookupError:
+            pass
+
+
+def _term_ignoring_child_command(child_pid_path: str, child_ready_path: str) -> str:
+    return (
+        f"{sys.executable} -c \"import signal, time; "
+        "signal.signal(signal.SIGTERM, signal.SIG_IGN); "
+        f"open('{child_ready_path}', 'w').write('ready'); time.sleep(30)\" "
+        f"& child=$!; echo $child > {child_pid_path}; "
+        "trap 'exit 0' TERM; while :; do sleep 1; done\n"
+    )
+
+
+def _digest(value: object) -> str:
+    return hashlib.sha256(
+        json.dumps(value, sort_keys=True, separators=(",", ":")).encode("utf-8")
+    ).hexdigest()
+
+
+def _render_sleeping_package(tmp_path: Path) -> dict[str, object]:
+    raw_code = tmp_path / "raw_code"
+    script = _write(
+        raw_code,
+        "run.sh",
+        _term_ignoring_child_command("child.pid", "child.ready"),
+    )
+    script_hash = hashlib.sha256(script.read_bytes()).hexdigest()
+    contract: dict[str, object] = {
+        "schema_version": "lightweight-runtime-binding/v1",
+        "facts_sha256": "facts-locked",
+        "original_command": "bash run.sh\ntrue",
+        "source_scripts": [{"path": "run.sh", "sha256": script_hash, "locked": True}],
+        "package_files": [
+            {
+                "path": "run.sh",
+                "source": "raw_code",
+                "kind": "file",
+                "size": script.stat().st_size,
+                "sha256": script_hash,
+                "locked": True,
+                "exposed_as_input": False,
+            }
+        ],
+        "inputs": [],
+        "parameters": [],
+        "path_references": [],
+        "outputs": {"files": [], "stdout": {"present": True}},
+        "patch_targets": [],
+        "unpatchable_targets": [],
+    }
+    contract["package_digest"] = _digest(
+        {
+            "run.sh": {
+                "kind": "file",
+                "size": script.stat().st_size,
+                "sha256": script_hash,
+                "source": "raw_code",
+            }
+        }
+    )
+    contract["contract_digest"] = _digest(contract)
+    resolved = resolve_runtime_bindings(contract, {}, {})
+    assert resolved["status"] == "resolved"
+    return render_runtime_package(contract, raw_code, resolved, tmp_path / "run")
+
+
+def test_baseline_cancellation_stops_its_process_group_only(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    child_pid_path = tmp_path / "child.pid"
+    child_ready_path = tmp_path / "child.ready"
+    _write(
+        raw_code,
+        "run.sh",
+        _term_ignoring_child_command(str(child_pid_path), str(child_ready_path)),
+    )
+    _write(raw_data, "input.txt", "input\n")
+
+    started = threading.Event()
+    identity: dict[str, int] = {}
+    result: dict[str, object] = {}
+
+    def run() -> None:
+        result["evidence"] = run_raw_baseline(
+            command="bash run.sh\ntrue",
+            raw_code=raw_code,
+            raw_data=raw_data,
+            run_dir=tmp_path / "baseline",
+            on_process_start=lambda value: (identity.update(value), started.set()),
+        )
+
+    thread = threading.Thread(target=run)
+    unrelated = subprocess.Popen(["sleep", "30"], start_new_session=True)
+    try:
+        thread.start()
+        assert started.wait(timeout=5)
+        _wait_for(child_pid_path)
+        _wait_for(child_ready_path)
+        child_pid = int(child_pid_path.read_text(encoding="utf-8").strip())
+
+        assert identity["pid"] == identity["pgid"]
+        assert identity["pid_start_time"] > 0
+        assert stop_process_group(identity) is True
+
+        thread.join(timeout=5)
+        assert not thread.is_alive()
+        assert result["evidence"]["process"] == identity
+        assert not _pid_is_running(child_pid)
+        assert unrelated.poll() is None
+    finally:
+        if thread.is_alive():
+            _force_stop(identity)
+            thread.join(timeout=5)
+        unrelated.terminate()
+        unrelated.wait(timeout=5)
+
+
+def test_stop_rejects_a_process_group_without_the_original_leader_identity() -> None:
+    unrelated = subprocess.Popen(["sleep", "30"], start_new_session=True)
+    try:
+        assert stop_process_group(
+            {
+                "pid": unrelated.pid,
+                "pgid": unrelated.pid,
+                "pid_start_time": 0,
+            }
+        ) is False
+        assert unrelated.poll() is None
+    finally:
+        unrelated.terminate()
+        unrelated.wait(timeout=5)
+
+
+def test_managed_supervisor_anchors_group_and_waits_for_descendants(
+    tmp_path: Path,
+) -> None:
+    command_pid_path = tmp_path / "command.pid"
+    release_path = tmp_path / "release"
+    command = (
+        f"echo $$ > {command_pid_path}; "
+        f"while [ ! -f {release_path} ]; do sleep 0.01; done; "
+        "sleep 0.2 & exit 7"
+    )
+    process, identity = start_managed_process(["bash", "-c", command])
+    try:
+        _wait_for(command_pid_path)
+        command_pid = int(command_pid_path.read_text(encoding="utf-8").strip())
+        assert identity["pid"] != command_pid
+        assert isinstance(identity["supervisor_token"], str)
+
+        started = time.monotonic()
+        release_path.write_text("release\n", encoding="utf-8")
+        assert process.wait(timeout=5) == 7
+        assert time.monotonic() - started >= 0.15
+    finally:
+        release_path.touch()
+        if process.poll() is None:
+            _force_stop(identity)
+            process.wait(timeout=5)
+
+
+def test_stop_rejects_valid_numeric_identity_without_supervisor_token() -> None:
+    unrelated = subprocess.Popen(["sleep", "30"], start_new_session=True)
+    try:
+        assert stop_process_group(
+            {
+                "pid": unrelated.pid,
+                "pgid": unrelated.pid,
+                "pid_start_time": _pid_start_time(unrelated.pid),
+                "supervisor_token": "stale-token",
+            }
+        ) is False
+        assert unrelated.poll() is None
+    finally:
+        if unrelated.poll() is None:
+            unrelated.terminate()
+        unrelated.wait(timeout=5)
+
+
+def test_start_retries_transient_proc_disappearance(
+    monkeypatch,
+) -> None:
+    original_read_text = Path.read_text
+    missing_once = True
+
+    def flaky_read_text(path: Path, *args, **kwargs) -> str:
+        nonlocal missing_once
+        if missing_once and path.parent.parent == Path("/proc") and path.name == "stat":
+            missing_once = False
+            raise FileNotFoundError(path)
+        return original_read_text(path, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "read_text", flaky_read_text)
+    process, identity = start_managed_process(["bash", "-c", "sleep 0.1; exit 0"])
+
+    assert identity["pid"] == identity["pgid"]
+    assert process.wait(timeout=5) == 0
+
+
+def test_supervised_command_keeps_default_sigterm_behavior() -> None:
+    process, identity = start_managed_process(["sleep", "30"])
+
+    assert stop_process_group(identity) is True
+    assert process.wait(timeout=5) == -signal.SIGTERM
+
+
+def test_supervisor_mirrors_independent_command_sigkill(tmp_path: Path) -> None:
+    command_pid_path = tmp_path / "command.pid"
+    command = (
+        "import os, time; "
+        f"open('{command_pid_path}', 'w').write(str(os.getpid())); "
+        "time.sleep(30)"
+    )
+    process, _identity = start_managed_process([sys.executable, "-c", command])
+    _wait_for(command_pid_path)
+    command_pid = int(command_pid_path.read_text(encoding="utf-8"))
+
+    os.kill(command_pid, signal.SIGKILL)
+
+    assert process.wait(timeout=5) == -signal.SIGKILL
+
+
+def test_stop_fails_closed_if_supervisor_disappears_during_grace(
+    tmp_path: Path,
+) -> None:
+    child_pid_path = tmp_path / "child.pid"
+    child_ready_path = tmp_path / "child.ready"
+    command = _term_ignoring_child_command(
+        str(child_pid_path), str(child_ready_path)
+    )
+    process, identity = start_managed_process(["bash", "-c", command])
+    _wait_for(child_pid_path)
+    _wait_for(child_ready_path)
+    child_pid = int(child_pid_path.read_text(encoding="utf-8"))
+    result: dict[str, bool] = {}
+
+    thread = threading.Thread(
+        target=lambda: result.update(
+            stopped=stop_process_group(identity, grace_seconds=0.5)
+        )
+    )
+    try:
+        thread.start()
+        time.sleep(0.05)
+        os.kill(int(identity["pid"]), signal.SIGKILL)
+        thread.join(timeout=5)
+
+        assert not thread.is_alive()
+        assert result["stopped"] is False
+        assert _pid_is_running(child_pid)
+    finally:
+        if _pid_is_running(child_pid):
+            os.kill(child_pid, signal.SIGKILL)
+        if process.poll() is None:
+            os.kill(int(identity["pid"]), signal.SIGKILL)
+        process.wait(timeout=5)
+
+
+def test_supervisor_state_rechecks_a_clean_zombie_transition(monkeypatch) -> None:
+    snapshots = iter(
+        [
+            ("S", 101, 101, 202),
+            ("Z", 101, 101, 202),
+        ]
+    )
+    monkeypatch.setattr(process_module, "_read_proc_stat", lambda _pid: next(snapshots))
+    monkeypatch.setattr(process_module, "_is_matching_supervisor", lambda **_kwargs: False)
+    monkeypatch.setattr(process_module, "_group_membership", lambda *_args: "empty")
+
+    assert process_module._supervisor_state(
+        pid=101,
+        pgid=101,
+        start_time=202,
+        token="token",
+    ) == "exited"
+
+
+def test_stop_fails_closed_if_sigkill_target_disappears(monkeypatch) -> None:
+    identity = {
+        "pid": 101,
+        "pgid": 101,
+        "pid_start_time": 202,
+        "supervisor_token": "token",
+    }
+    monkeypatch.setattr(process_module, "_is_matching_supervisor", lambda **_kwargs: True)
+    monkeypatch.setattr(
+        process_module, "_wait_for_supervisor_state", lambda **_kwargs: "running"
+    )
+
+    def killpg(_pgid: int, signum: int) -> None:
+        if signum == signal.SIGKILL:
+            raise ProcessLookupError
+
+    monkeypatch.setattr(process_module.os, "killpg", killpg)
+
+    assert stop_process_group(identity) is False
+
+
+def test_stop_requires_verified_exit_after_sigkill(monkeypatch) -> None:
+    identity = {
+        "pid": 101,
+        "pgid": 101,
+        "pid_start_time": 202,
+        "supervisor_token": "token",
+    }
+    states = iter(["running", "lost"])
+    monkeypatch.setattr(process_module, "_is_matching_supervisor", lambda **_kwargs: True)
+    monkeypatch.setattr(
+        process_module,
+        "_wait_for_supervisor_state",
+        lambda **_kwargs: next(states),
+    )
+    monkeypatch.setattr(process_module.os, "killpg", lambda *_args: None)
+
+    assert stop_process_group(identity) is False
+
+
+def test_start_accepts_only_the_execution_context_used_by_callers(
+    tmp_path: Path,
+) -> None:
+    process_env = os.environ.copy()
+    process_env["BBAV5_PROCESS_TEST"] = "allowed"
+    process, _identity = start_managed_process(
+        ["bash", "-c", "printf '%s\\n' \"$BBAV5_PROCESS_TEST\"; pwd; cat"],
+        cwd=tmp_path,
+        env=process_env,
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+
+    stdout, stderr = process.communicate(b"payload\n", timeout=5)
+
+    assert process.returncode == 0
+    assert stdout.decode().splitlines() == ["allowed", str(tmp_path), "payload"]
+    assert stderr == b""
+
+
+@pytest.mark.parametrize(
+    ("group_membership", "expected"),
+    [("empty", "exited"), ("member", "matching"), ("uncertain", "matching")],
+)
+def test_post_kill_absent_anchor_requires_an_empty_original_group(
+    monkeypatch,
+    group_membership: str,
+    expected: str,
+) -> None:
+    monkeypatch.setattr(process_module, "_read_proc_stat", lambda _pid: None)
+    monkeypatch.setattr(
+        process_module.os,
+        "kill",
+        lambda *_args: (_ for _ in ()).throw(ProcessLookupError()),
+    )
+    monkeypatch.setattr(
+        process_module,
+        "_group_membership",
+        lambda *_args: group_membership,
+    )
+
+    assert process_module._supervisor_state(
+        pid=101,
+        pgid=101,
+        start_time=202,
+        token="token",
+        verify_absent_exit=True,
+    ) == expected
+
+
+def test_post_kill_present_zombie_is_not_verified_absent(monkeypatch) -> None:
+    monkeypatch.setattr(
+        process_module,
+        "_read_proc_stat",
+        lambda _pid: ("Z", 101, 101, 202),
+    )
+    monkeypatch.setattr(
+        process_module, "_group_membership", lambda *_args: "empty"
+    )
+
+    assert process_module._supervisor_state(
+        pid=101,
+        pgid=101,
+        start_time=202,
+        token="token",
+        verify_absent_exit=True,
+    ) == "matching"
+
+
+def test_unreadable_group_member_fails_closed(monkeypatch) -> None:
+    monkeypatch.setattr(Path, "iterdir", lambda _path: iter([Path("/proc/303")]))
+    monkeypatch.setattr(Path, "exists", lambda _path: True)
+    monkeypatch.setattr(process_module, "_read_proc_stat", lambda _pid: None)
+
+    assert process_module._group_membership(101, 202) == "uncertain"
+
+
+def test_disappeared_unreadable_group_entry_is_skipped(monkeypatch) -> None:
+    monkeypatch.setattr(Path, "iterdir", lambda _path: iter([Path("/proc/303")]))
+    monkeypatch.setattr(Path, "exists", lambda _path: False)
+    monkeypatch.setattr(process_module, "_read_proc_stat", lambda _pid: None)
+
+    assert process_module._group_membership(101, 202) == "empty"
+
+
+def test_stop_fails_closed_on_proc_stat_permission_error(monkeypatch) -> None:
+    monkeypatch.setattr(
+        Path,
+        "read_text",
+        lambda *_args, **_kwargs: (_ for _ in ()).throw(PermissionError()),
+    )
+
+    assert stop_process_group(
+        {
+            "pid": 101,
+            "pgid": 101,
+            "pid_start_time": 202,
+            "supervisor_token": "token",
+        }
+    ) is False
+
+
+def test_stop_fails_closed_on_proc_cmdline_oserror(monkeypatch) -> None:
+    monkeypatch.setattr(
+        process_module,
+        "_read_proc_stat",
+        lambda _pid: ("S", 101, 101, 202),
+    )
+    monkeypatch.setattr(
+        Path,
+        "read_bytes",
+        lambda *_args, **_kwargs: (_ for _ in ()).throw(OSError("unreadable")),
+    )
+
+    assert stop_process_group(
+        {
+            "pid": 101,
+            "pgid": 101,
+            "pid_start_time": 202,
+            "supervisor_token": "token",
+        }
+    ) is False
+
+
+def test_proc_iteration_permission_error_is_uncertain(monkeypatch) -> None:
+    monkeypatch.setattr(
+        Path,
+        "iterdir",
+        lambda _path: (_ for _ in ()).throw(PermissionError()),
+    )
+
+    assert process_module._group_membership(101, 202) == "uncertain"
+
+
+def test_proc_entry_exists_oserror_is_uncertain(monkeypatch) -> None:
+    monkeypatch.setattr(Path, "iterdir", lambda _path: iter([Path("/proc/303")]))
+    monkeypatch.setattr(process_module, "_read_proc_stat", lambda _pid: None)
+    monkeypatch.setattr(
+        Path,
+        "exists",
+        lambda _path: (_ for _ in ()).throw(OSError("unreadable")),
+    )
+
+    assert process_module._group_membership(101, 202) == "uncertain"
+
+
+def test_start_rejects_unsupported_popen_options_before_launch(
+    monkeypatch,
+) -> None:
+    monkeypatch.setattr(
+        process_module.subprocess,
+        "Popen",
+        lambda *_args, **_kwargs: pytest.fail("unsupported option reached launch"),
+    )
+    unsupported = {
+        "pass_fds": (1,),
+        "shell": True,
+        "executable": "/bin/bash",
+        "preexec_fn": lambda: None,
+        "start_new_session": False,
+        "process_group": 0,
+        "user": 1000,
+        "group": 1000,
+        "extra_groups": [1000],
+        "umask": 0o022,
+    }
+
+    for option, value in unsupported.items():
+        with pytest.raises(TypeError, match=option):
+            start_managed_process(["true"], **{option: value})
+
+
+def test_replay_reports_process_identity_to_its_start_callback(tmp_path: Path) -> None:
+    rendered = _render_sleeping_package(tmp_path)
+    started = threading.Event()
+    identity: dict[str, int] = {}
+    result: dict[str, object] = {}
+
+    def run() -> None:
+        result["value"] = replay_runtime_binding(
+            rendered,
+            on_process_start=lambda value: (identity.update(value), started.set()),
+        )
+
+    thread = threading.Thread(target=run)
+    unrelated = subprocess.Popen(["sleep", "30"], start_new_session=True)
+    thread.start()
+    assert started.wait(timeout=5)
+    try:
+        child_pid_path = Path(rendered["work_dir"]) / "child.pid"
+        child_ready_path = Path(rendered["work_dir"]) / "child.ready"
+        _wait_for(child_pid_path)
+        _wait_for(child_ready_path)
+        child_pid = int(child_pid_path.read_text(encoding="utf-8").strip())
+        assert identity["pid"] == identity["pgid"]
+        assert stop_process_group(identity) is True
+        thread.join(timeout=5)
+        assert not thread.is_alive()
+        assert result["value"]["process"] == identity
+        assert not _pid_is_running(child_pid)
+        assert unrelated.poll() is None
+    finally:
+        if thread.is_alive():
+            _force_stop(identity)
+            thread.join(timeout=5)
+        unrelated.terminate()
+        unrelated.wait(timeout=5)
diff --git a/tests/unit/test_extension_stage_lightweight_raw_package_normalizer.py b/tests/unit/test_extension_stage_lightweight_raw_package_normalizer.py
new file mode 100644
index 000000000..ccb3ff652
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_raw_package_normalizer.py
@@ -0,0 +1,62 @@
+from pathlib import Path
+
+from gfa_core.extension_stage.raw_package_normalizer import normalize_raw_package
+
+
+def test_single_shell_upload_becomes_entry_command(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    raw_code.mkdir()
+    raw_data.mkdir()
+    script = raw_code / "run.sh"
+    script.write_text("cp input.fa output.fa\n", encoding="utf-8")
+
+    normalized = normalize_raw_package(
+        explicit_command="",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        saved_code=[script],
+    )
+
+    assert normalized["entry_command"] == "bash run.sh"
+    assert normalized["entry_source"] == "single_shell_script"
+    assert normalized["requires_user_confirmation"] is False
+
+
+def test_multiple_shell_uploads_require_entry_confirmation(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    raw_code.mkdir()
+    raw_data.mkdir()
+    (raw_code / "run_a.sh").write_text("echo a\n", encoding="utf-8")
+    (raw_code / "run_b.sh").write_text("echo b\n", encoding="utf-8")
+
+    normalized = normalize_raw_package(
+        explicit_command="",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        saved_code=sorted(raw_code.iterdir()),
+    )
+
+    assert normalized["entry_source"] == "ambiguous_shell_script"
+    assert normalized["requires_user_confirmation"] is True
+
+
+def test_inline_command_is_wrapped_as_run_sh(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    raw_code.mkdir()
+    raw_data.mkdir()
+
+    normalized = normalize_raw_package(
+        explicit_command="mafft --auto input.fa > output.msa.fa",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        saved_code=[],
+    )
+
+    assert normalized["entry_command"] == "bash run.sh"
+    assert normalized["entry_source"] == "inline_command_wrapped"
+    assert (raw_code / "run.sh").read_text(encoding="utf-8").strip().endswith(
+        "mafft --auto input.fa > output.msa.fa"
+    )
diff --git a/tests/unit/test_extension_stage_lightweight_replay.py b/tests/unit/test_extension_stage_lightweight_replay.py
new file mode 100644
index 000000000..aea8c22c9
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_replay.py
@@ -0,0 +1,96 @@
+import json
+from pathlib import Path
+
+from gfa_core.extension_stage_lightweight.converter import (
+    build_spec,
+    replay,
+    write_spec,
+    write_wrapper,
+)
+from gfa_core.extension_stage_lightweight.evidence import run_raw_baseline
+
+
+def _write(root: Path, relative: str, content: str) -> Path:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def _baseline(tmp_path: Path) -> tuple[Path, Path, dict[str, object]]:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(raw_data, "input.txt", "baseline\n")
+    evidence = run_raw_baseline(
+        command="cp input.txt output.txt",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+    return raw_code, raw_data, evidence
+
+
+def test_build_and_write_spec_is_json_serializable(tmp_path: Path) -> None:
+    _, _, evidence = _baseline(tmp_path)
+
+    spec = build_spec(evidence)
+    destination = write_spec(spec, tmp_path / "lightweight_spec.json")
+
+    loaded = json.loads(destination.read_text(encoding="utf-8"))
+    assert loaded["schema_version"] == "lightweight-extension/v1"
+    assert loaded["original_command"] == "cp input.txt output.txt"
+    assert loaded["baseline"]["returncode"] == 0
+    assert loaded["outputs"]["files"] == ["output.txt"]
+    assert loaded["commands"][0]["inputs"][0]["path"] == "input.txt"
+
+
+def test_wrapper_preserves_original_command(tmp_path: Path) -> None:
+    _, _, evidence = _baseline(tmp_path)
+    spec = build_spec(evidence)
+
+    wrapper = write_wrapper(spec, tmp_path / "run_extension.sh")
+
+    text = wrapper.read_text(encoding="utf-8")
+    assert "cp input.txt output.txt" in text
+    assert wrapper.stat().st_mode & 0o111
+
+
+def test_replay_runs_in_a_new_directory_and_reproduces_output(tmp_path: Path) -> None:
+    raw_code, raw_data, evidence = _baseline(tmp_path)
+    spec = build_spec(evidence)
+
+    result = replay(
+        spec=spec,
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "replay",
+    )
+
+    assert result["success"] is True
+    assert result["contract_passed"] is True
+    assert result["work_dir"] != evidence["work_dir"]
+    assert (tmp_path / "replay" / "work" / "output.txt").read_text(
+        encoding="utf-8"
+    ) == "baseline\n"
+
+
+def test_replay_input_override_is_bound_by_symlink(tmp_path: Path) -> None:
+    raw_code, raw_data, evidence = _baseline(tmp_path)
+    spec = build_spec(evidence)
+    replacement = _write(tmp_path, "replacement/new.txt", "replacement\n")
+
+    result = replay(
+        spec=spec,
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "replay",
+        input_overrides={"input.txt": replacement},
+    )
+
+    rebound = tmp_path / "replay" / "work" / "input.txt"
+    assert result["success"] is True
+    assert rebound.is_symlink()
+    assert rebound.resolve() == replacement.resolve()
+    assert (tmp_path / "replay" / "work" / "output.txt").read_text(
+        encoding="utf-8"
+    ) == "replacement\n"
diff --git a/tests/unit/test_extension_stage_lightweight_runtime_binding.py b/tests/unit/test_extension_stage_lightweight_runtime_binding.py
new file mode 100644
index 000000000..8fa91605b
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_runtime_binding.py
@@ -0,0 +1,467 @@
+from __future__ import annotations
+
+from copy import deepcopy
+import hashlib
+import json
+from pathlib import Path
+
+import pytest
+
+from gfa_core.extension_stage_lightweight.converter import build_execution_facts
+from gfa_core.extension_stage_lightweight.evidence import run_raw_baseline
+from gfa_core.extension_stage_lightweight.runtime_binding import (
+    build_runtime_binding_contract,
+)
+
+
+def test_package_exports_runtime_binding_public_api() -> None:
+    from gfa_core.extension_stage_lightweight import (
+        RuntimeBindingError,
+        build_runtime_binding_contract as package_build_contract,
+        render_runtime_package,
+        replay_runtime_binding,
+        resolve_runtime_bindings,
+    )
+    from gfa_core.extension_stage_lightweight import runtime_binding
+
+    assert RuntimeBindingError is runtime_binding.RuntimeBindingError
+    assert package_build_contract is runtime_binding.build_runtime_binding_contract
+    assert resolve_runtime_bindings is runtime_binding.resolve_runtime_bindings
+    assert render_runtime_package is runtime_binding.render_runtime_package
+    assert replay_runtime_binding is runtime_binding.replay_runtime_binding
+
+
+def _write(root: Path, relative: str, content: str) -> Path:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def _package(tmp_path: Path) -> tuple[dict, dict, Path]:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(
+        raw_code,
+        "run.sh",
+        "head -n 1 input.fa > intermediate.fa\n"
+        "cp intermediate.fa result.fa\n",
+    )
+    _write(raw_code, "unused_helper.py", "print('locked code')\n")
+    _write(raw_data, "input.fa", ">a\nAAAA\n>b\nBBBB\n")
+    evidence = run_raw_baseline(
+        command="bash run.sh",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+    facts = build_execution_facts(evidence)
+    candidate = {
+        "facts_sha256": facts["facts_sha256"],
+        "function_summary": "Keep the first FASTA record line.",
+        "inputs": [
+            {
+                "fact_id": item["fact_id"],
+                "role": "uploaded_sequences",
+                "description": "User-provided sequence data.",
+                "replaceability": "fixed_resource",
+            }
+            for command in facts["commands"]
+            for item in command["inputs"]
+        ],
+        "parameters": [
+            {
+                "fact_id": item["fact_id"],
+                "display_name": "user-facing label",
+                "description": "A command value.",
+            }
+            for command in facts["commands"]
+            for item in command["parameters"]
+        ],
+        "outputs": [
+            {
+                "fact_id": item["fact_id"],
+                "description": "Observed result file.",
+                "result_role": "final",
+            }
+            for item in facts["outputs"]["files"]
+        ],
+    }
+    return facts, candidate, raw_code
+
+
+def _by_fact_id(items: list[dict]) -> dict[str, dict]:
+    return {item["fact_id"]: item for item in items}
+
+
+def test_contract_locks_code_and_owns_external_and_generated_inputs(
+    tmp_path: Path,
+) -> None:
+    facts, candidate, raw_code = _package(tmp_path)
+
+    contract = build_runtime_binding_contract(facts, candidate, raw_code)
+
+    assert contract["schema_version"] == "lightweight-runtime-binding/v1"
+    assert contract["facts_sha256"] == facts["facts_sha256"]
+    assert contract["original_command"] == "bash run.sh"
+
+    inputs = _by_fact_id(contract["inputs"])
+    external = next(
+        item for item in inputs.values() if item["source"] == "baseline_input"
+    )
+    generated = next(
+        item for item in inputs.values() if item["source"] == "generated_input"
+    )
+    assert external["path"] == "input.fa"
+    assert external["replaceable"] is True
+    assert external["locked"] is False
+    assert generated["path"] == "intermediate.fa"
+    assert generated["replaceable"] is False
+    assert generated["locked"] is True
+
+    package_files = {item["path"]: item for item in contract["package_files"]}
+    assert package_files["run.sh"]["locked"] is True
+    assert package_files["unused_helper.py"]["locked"] is True
+    assert package_files["run.sh"]["exposed_as_input"] is False
+    assert package_files["unused_helper.py"]["exposed_as_input"] is False
+    assert package_files["input.fa"]["exposed_as_input"] is True
+    assert not (
+        {"run.sh", "unused_helper.py"}
+        & {item["path"] for item in contract["inputs"]}
+    )
+
+
+def test_contract_digest_and_source_hash_come_from_locked_package_inventory(
+    tmp_path: Path,
+) -> None:
+    facts, candidate, raw_code = _package(tmp_path)
+
+    contract = build_runtime_binding_contract(facts, candidate, raw_code)
+
+    canonical_inventory = json.dumps(
+        facts["package"]["inventory"],
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    assert contract["package_digest"] == hashlib.sha256(
+        canonical_inventory
+    ).hexdigest()
+    assert contract["source_scripts"] == [
+        {
+            "path": "run.sh",
+            "sha256": facts["package"]["inventory"]["run.sh"]["sha256"],
+            "locked": True,
+        }
+    ]
+    assert contract["contract_digest"] == hashlib.sha256(
+        json.dumps(
+            {
+                key: value
+                for key, value in contract.items()
+                if key != "contract_digest"
+            },
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode("utf-8")
+    ).hexdigest()
+
+
+def test_contract_rejects_tampered_non_entry_code_file(tmp_path: Path) -> None:
+    facts, candidate, raw_code = _package(tmp_path)
+    (raw_code / "unused_helper.py").write_text(
+        "print('tampered code')\n", encoding="utf-8"
+    )
+
+    with pytest.raises(
+        ValueError, match=r"Code file changed after baseline: unused_helper\.py"
+    ):
+        build_runtime_binding_contract(facts, candidate, raw_code)
+
+
+def test_contract_exposes_only_explicit_non_path_parameters(tmp_path: Path) -> None:
+    facts, candidate, raw_code = _package(tmp_path)
+
+    contract = build_runtime_binding_contract(facts, candidate, raw_code)
+
+    assert [
+        (item["kind"], item["flag"], item["value"])
+        for item in contract["parameters"]
+    ] == [("flag_value", "-n", "1")]
+    assert all(
+        item.get("value_role") != "output_reference"
+        for item in contract["parameters"]
+    )
+    assert "input.fa" not in {item["value"] for item in contract["parameters"]}
+    assert "result.fa" not in {item["value"] for item in contract["parameters"]}
+    assert [item["path"] for item in contract["path_references"]] == [
+        "result.fa"
+    ]
+    reference = contract["path_references"][0]
+    assert reference["value_role"] == "output_reference"
+    assert any(
+        target["binding_key"] == f"path_reference:{reference['fact_id']}"
+        for target in contract["patch_targets"]
+    )
+
+
+def test_semantics_can_only_add_text_bound_to_known_fact_ids(tmp_path: Path) -> None:
+    facts, candidate, raw_code = _package(tmp_path)
+    baseline_id = next(
+        item["fact_id"]
+        for command in facts["commands"]
+        for item in command["inputs"]
+        if item["source"] == "baseline_input"
+    )
+    parameter_id = next(
+        item["fact_id"]
+        for command in facts["commands"]
+        for item in command["parameters"]
+        if item.get("value_role") == "value"
+    )
+    candidate["original_command"] = "rm -rf /"
+    candidate["inputs"][0].update(
+        {"path": "invented.fa", "replaceability": "fixed_resource"}
+    )
+    next(
+        item
+        for item in candidate["parameters"]
+        if item["fact_id"] == parameter_id
+    ).update({"flag": "--invented", "value": "invented"})
+    candidate["outputs"][0]["path"] = "invented.out"
+
+    contract = build_runtime_binding_contract(facts, candidate, raw_code)
+
+    input_item = _by_fact_id(contract["inputs"])[baseline_id]
+    parameter_item = _by_fact_id(contract["parameters"])[parameter_id]
+    assert contract["original_command"] == facts["original_command"]
+    assert input_item["path"] == "input.fa"
+    assert input_item["replaceable"] is True
+    assert input_item["role"] == "uploaded_sequences"
+    assert input_item["description"] == "User-provided sequence data."
+    assert parameter_item["flag"] == "-n"
+    assert parameter_item["value"] == "1"
+    assert parameter_item["display_name"] == "user-facing label"
+    assert all(
+        item["path"] != "invented.out"
+        for item in contract["outputs"]["files"]
+    )
+
+
+def test_shell_patch_targets_record_hash_literal_kind_and_exact_count(
+    tmp_path: Path,
+) -> None:
+    facts, candidate, raw_code = _package(tmp_path)
+
+    contract = build_runtime_binding_contract(facts, candidate, raw_code)
+
+    targets = {
+        (item["patch_kind"], item["original_literal"]): item
+        for item in contract["patch_targets"]
+    }
+    script_hash = facts["package"]["inventory"]["run.sh"]["sha256"]
+    assert targets[("input_path", "input.fa")]["expected_exact_match_count"] == 1
+    assert targets[("parameter_value", "1")]["expected_exact_match_count"] == 1
+    assert targets[("parameter_value", "1")]["token_index"] == 2
+    assert targets[("output_path", "result.fa")]["expected_exact_match_count"] == 1
+    assert (
+        targets[("output_path", "intermediate.fa")][
+            "expected_exact_match_count"
+        ]
+        == 2
+    )
+    assert all(item["script_path"] == "run.sh" for item in targets.values())
+    assert all(item["script_hash"] == script_hash for item in targets.values())
+    assert all(
+        {"binding_key", "fact_ids", "anchors"} <= set(item)
+        and all(
+            {"step_id", "token_index", "command_digest"} <= set(anchor)
+            for anchor in item["anchors"]
+        )
+        for item in targets.values()
+    )
+    result_target = targets[("output_path", "result.fa")]
+    result_fact = next(
+        item
+        for item in facts["outputs"]["files"]
+        if item["path"] == "result.fa"
+    )
+    assert result_target["producer_step_ids"] == result_fact["producer_step_ids"]
+    assert result_target["step_id"] == "step_002"
+    assert (
+        result_target["command_digest"]
+        == hashlib.sha256(b"cp intermediate.fa result.fa").hexdigest()
+    )
+    intermediate_target = targets[("output_path", "intermediate.fa")]
+    intermediate_fact_ids = {
+        item["fact_id"]
+        for command in facts["commands"]
+        for item in command["inputs"]
+        if item["path"] == "intermediate.fa"
+    } | {
+        item["fact_id"]
+        for item in facts["outputs"]["files"]
+        if item["path"] == "intermediate.fa"
+    }
+    assert intermediate_target["binding_key"] == "path:intermediate.fa"
+    assert set(intermediate_target["fact_ids"]) == intermediate_fact_ids
+    assert {anchor["step_id"] for anchor in intermediate_target["anchors"]} == {
+        "step_001",
+        "step_002",
+    }
+
+
+def test_same_uploaded_path_in_two_steps_forms_one_safe_path_binding(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(
+        raw_code,
+        "run.sh",
+        "head input.fa > first.txt\n"
+        "tail input.fa > last.txt\n",
+    )
+    _write(raw_data, "input.fa", ">a\nAAAA\n>b\nBBBB\n")
+    evidence = run_raw_baseline(
+        command="bash run.sh",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+    facts = build_execution_facts(evidence)
+
+    contract = build_runtime_binding_contract(facts, {}, raw_code)
+
+    input_fact_ids = {
+        item["fact_id"]
+        for command in facts["commands"]
+        for item in command["inputs"]
+        if item["path"] == "input.fa"
+    }
+    targets = [
+        item
+        for item in contract["patch_targets"]
+        if item["binding_key"] == "path:input.fa"
+    ]
+    assert len(input_fact_ids) == 2
+    assert len(targets) == 1
+    assert set(targets[0]["fact_ids"]) == input_fact_ids
+    assert len(targets[0]["anchors"]) == 2
+    assert targets[0]["expected_exact_match_count"] == 2
+
+
+def test_inline_flag_value_is_not_patchable_in_v1(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(raw_code, "run.sh", "head --lines=1 input.fa > result.fa\n")
+    _write(raw_data, "input.fa", ">a\nAAAA\n>b\nBBBB\n")
+    evidence = run_raw_baseline(
+        command="bash run.sh",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+    facts = build_execution_facts(evidence)
+
+    contract = build_runtime_binding_contract(facts, {}, raw_code)
+
+    parameter_fact = next(
+        item
+        for command in facts["commands"]
+        for item in command["parameters"]
+        if item.get("flag") == "--lines"
+    )
+    assert not any(
+        item["binding_key"] == f"parameter:{parameter_fact['fact_id']}"
+        for item in contract["patch_targets"]
+    )
+    blocked = next(
+        item
+        for item in contract["unpatchable_targets"]
+        if item["binding_key"] == f"parameter:{parameter_fact['fact_id']}"
+    )
+    assert blocked["reason"] == "inline_flag_value_not_supported"
+
+
+def test_repeated_parameter_literal_across_facts_is_not_patchable(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(
+        raw_code,
+        "run.sh",
+        "head -n 1 input.fa > first.txt\n"
+        "tail -n 1 input.fa > last.txt\n",
+    )
+    _write(raw_data, "input.fa", ">a\nAAAA\n>b\nBBBB\n")
+    evidence = run_raw_baseline(
+        command="bash run.sh",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+    facts = build_execution_facts(evidence)
+
+    contract = build_runtime_binding_contract(facts, {}, raw_code)
+
+    parameter_fact_ids = {
+        item["fact_id"]
+        for command in facts["commands"]
+        for item in command["parameters"]
+        if item.get("value") == "1"
+    }
+    assert len(parameter_fact_ids) == 2
+    assert not any(
+        item["patch_kind"] == "parameter_value"
+        and item["original_literal"] == "1"
+        for item in contract["patch_targets"]
+    )
+    ambiguous = {
+        item["fact_ids"][0]
+        for item in contract["unpatchable_targets"]
+        if item["patch_kind"] == "parameter_value"
+        and item["original_literal"] == "1"
+        and item["reason"] == "source_literal_ambiguous"
+    }
+    assert ambiguous == parameter_fact_ids
+
+
+def test_contract_is_deterministic_and_does_not_mutate_inputs(tmp_path: Path) -> None:
+    facts, candidate, raw_code = _package(tmp_path)
+    original_facts = deepcopy(facts)
+    original_candidate = deepcopy(candidate)
+
+    first = build_runtime_binding_contract(facts, candidate, raw_code)
+    second = build_runtime_binding_contract(facts, candidate, raw_code)
+
+    assert first == second
+    assert facts == original_facts
+    assert candidate == original_candidate
+
+
+def test_contract_records_unpatchable_reason_without_guessing_for_direct_command(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    raw_code.mkdir()
+    _write(raw_data, "input.fa", ">a\nAAAA\n")
+    evidence = run_raw_baseline(
+        command="head -n 1 input.fa > result.fa",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+    facts = build_execution_facts(evidence)
+
+    contract = build_runtime_binding_contract(facts, {}, raw_code)
+
+    assert contract["source_scripts"] == []
+    assert contract["patch_targets"] == []
+    assert contract["unpatchable_targets"]
+    assert {item["reason"] for item in contract["unpatchable_targets"]} == {
+        "source_literal_not_found_in_raw_shell"
+    }
diff --git a/tests/unit/test_extension_stage_lightweight_runtime_binding_resolver.py b/tests/unit/test_extension_stage_lightweight_runtime_binding_resolver.py
new file mode 100644
index 000000000..a871e9bb8
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_runtime_binding_resolver.py
@@ -0,0 +1,630 @@
+from __future__ import annotations
+
+from copy import deepcopy
+import json
+from pathlib import Path
+
+import pytest
+
+from gfa_core.extension_stage_lightweight.runtime_binding import (
+    build_runtime_binding_contract,
+    resolve_runtime_bindings,
+)
+
+
+CATALOG_ROOT = (
+    Path(__file__).resolve().parents[2]
+    / "benchmarks"
+    / "extension_stage_lightweight_gene_family_8x5"
+)
+
+
+def _file(tmp_path: Path, name: str) -> Path:
+    path = tmp_path / name
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text("test\n", encoding="utf-8")
+    return path
+
+
+def _input(
+    fact_id: str,
+    path: str,
+    role: str | None = None,
+    step_id: str = "step_001",
+) -> dict:
+    item = {
+        "fact_id": fact_id,
+        "path": path,
+        "step_id": step_id,
+        "source": "baseline_input",
+        "replaceable": True,
+        "locked": False,
+    }
+    if role:
+        item["role"] = role
+    return item
+
+
+def _contract(
+    *,
+    inputs: list[dict],
+    outputs: list[tuple[str, str]],
+    parameters: list[dict] | None = None,
+    stdout: bool = False,
+) -> dict:
+    return {
+        "schema_version": "lightweight-runtime-binding/v1",
+        "facts_sha256": "facts-1",
+        "package_digest": "package-1",
+        "inputs": inputs,
+        "parameters": parameters or [],
+        "outputs": {
+            "files": [
+                {
+                    "fact_id": fact_id,
+                    "path": path,
+                    "producer_step_ids": ["step_001"],
+                }
+                for fact_id, path in outputs
+            ],
+            "stdout": {"present": stdout},
+        },
+    }
+
+
+def _outputs(result: dict) -> dict[str, dict]:
+    return {item["fact_id"]: item for item in result["output_bindings"]}
+
+
+def test_resolves_single_input_and_output_prefix(tmp_path: Path) -> None:
+    replacement = _file(tmp_path, "Runtime.Sample.pep.fasta")
+    contract = _contract(
+        inputs=[_input("input:1", "Ft.SPL.pep.fasta", "sequences")],
+        outputs=[("output:1", "Ft.SPL.pep.mfa")],
+    )
+
+    result = resolve_runtime_bindings(
+        contract, {"input:1": replacement}, {}
+    )
+
+    assert result["status"] == "resolved"
+    assert result["error"] is None
+    assert result["input_bindings"] == [
+        {
+            "original_path": "Ft.SPL.pep.fasta",
+            "runtime_path": str(replacement),
+            "fact_ids": ["input:1"],
+        }
+    ]
+    assert _outputs(result)["output:1"]["runtime_path"] == "output.mfa"
+    assert result["prefix_binding"]["mode"] == "default"
+
+
+def test_consistent_multi_input_prefixes_resolve_once(tmp_path: Path) -> None:
+    first = _file(tmp_path, "Runtime.one.fa")
+    second = _file(tmp_path, "Runtime.two.fa")
+    contract = _contract(
+        inputs=[
+            _input("input:1", "Ft.one.fa"),
+            _input("input:2", "Ft.two.fa"),
+        ],
+        outputs=[("output:1", "Ft.result.txt")],
+    )
+
+    result = resolve_runtime_bindings(
+        contract, {"input:1": first, "input:2": second}, {}
+    )
+
+    assert result["status"] == "resolved"
+    assert _outputs(result)["output:1"]["runtime_path"] == "output.result.txt"
+
+
+def test_unrelated_model_input_does_not_participate_in_output_prefix(
+    tmp_path: Path,
+) -> None:
+    model = _file(tmp_path, "RuntimeModel.hmm")
+    sequences = _file(tmp_path, "Runtime.pep.fasta")
+    contract = _contract(
+        inputs=[
+            _input("input:model", "SBP.hmm"),
+            _input("input:sequences", "Ft.pep.fasta"),
+        ],
+        outputs=[("output:1", "Ft.domtblout")],
+    )
+
+    result = resolve_runtime_bindings(
+        contract,
+        {"input:model": model, "input:sequences": sequences},
+        {},
+    )
+
+    assert result["status"] == "resolved"
+    assert _outputs(result)["output:1"]["runtime_path"] == "output.domtblout"
+
+
+def test_separator_change_without_evidence_uses_default_output_prefix(
+    tmp_path: Path,
+) -> None:
+    replacement = _file(tmp_path, "Runtime-Reference.collinearity")
+    contract = _contract(
+        inputs=[_input("input:1", "Ft-Ath.collinearity")],
+        outputs=[("output:1", "Ft.Ath.anchors")],
+    )
+
+    result = resolve_runtime_bindings(
+        contract, {"input:1": replacement}, {}
+    )
+
+    assert result["status"] == "resolved"
+    assert result["prefix_binding"] == {
+        "mode": "default",
+        "old_prefix": "Ft.Ath",
+        "new_prefix": "output",
+        "participating_inputs": [],
+    }
+    assert _outputs(result)["output:1"]["runtime_path"] == "output.anchors"
+
+
+def test_no_input_output_name_relation_uses_default_output_prefix(
+    tmp_path: Path,
+) -> None:
+    replacement = _file(tmp_path, "Runtime.fa")
+    contract = _contract(
+        inputs=[_input("input:1", "input.fa")],
+        outputs=[("output:1", "result.txt")],
+    )
+
+    result = resolve_runtime_bindings(
+        contract, {"input:1": replacement}, {}
+    )
+
+    assert result["status"] == "resolved"
+    assert result["prefix_binding"]["mode"] == "default"
+    assert result["prefix_binding"]["old_prefix"] == "result"
+    assert result["prefix_binding"]["new_prefix"] == "output"
+    assert _outputs(result)["output:1"]["runtime_path"] == "output.txt"
+
+
+def test_common_output_prefix_is_replaced_without_input_name_relation(
+    tmp_path: Path,
+) -> None:
+    replacement = _file(tmp_path, "Runtime.Sample.genomic.gff")
+    contract = _contract(
+        inputs=[_input("input:1", "GCF_reference_genomic.gff")],
+        outputs=[
+            ("output:tmp", "Ath.gff3.tmp"),
+            ("output:gff", "Ath_final.gff3"),
+            ("output:ids", "Ath_gene_mrna_cds.ids"),
+        ],
+    )
+
+    result = resolve_runtime_bindings(
+        contract, {"input:1": replacement}, {}
+    )
+
+    assert result["status"] == "resolved"
+    assert result["prefix_binding"]["old_prefix"] == "Ath"
+    assert result["prefix_binding"]["new_prefix"] == "output"
+    assert {
+        fact_id: item["runtime_path"]
+        for fact_id, item in _outputs(result).items()
+    } == {
+        "output:tmp": "output.gff3.tmp",
+        "output:gff": "output_final.gff3",
+        "output:ids": "output_gene_mrna_cds.ids",
+    }
+
+
+def test_auxiliary_output_stays_unchanged_after_another_output_is_derived(
+    tmp_path: Path,
+) -> None:
+    replacement = _file(tmp_path, "Runtime.fa")
+    contract = _contract(
+        inputs=[_input("input:1", "Ft.fa")],
+        outputs=[
+            ("output:main", "Ft.result.txt"),
+            ("output:aux", "summary.log"),
+        ],
+    )
+
+    result = resolve_runtime_bindings(
+        contract, {"input:1": replacement}, {}
+    )
+
+    assert result["status"] == "resolved"
+    assert _outputs(result)["output:main"]["runtime_path"] == "output.result.txt"
+    assert _outputs(result)["output:aux"] == {
+        "fact_id": "output:aux",
+        "original_path": "summary.log",
+        "runtime_path": "summary.log",
+        "transformed": False,
+    }
+
+
+def test_conflicting_input_prefixes_use_default_and_accept_explicit_prefix(
+    tmp_path: Path,
+) -> None:
+    first = _file(tmp_path, "X.one.fa")
+    second = _file(tmp_path, "Y.two.fa")
+    contract = _contract(
+        inputs=[
+            _input("input:1", "Ft.one.fa"),
+            _input("input:2", "Ft.two.fa"),
+        ],
+        outputs=[("output:1", "Ft.result.txt")],
+    )
+
+    blocked = resolve_runtime_bindings(
+        contract, {"input:1": first, "input:2": second}, {}
+    )
+    resolved = resolve_runtime_bindings(
+        contract,
+        {"input:1": first, "input:2": second},
+        {},
+        explicit_prefix="Chosen",
+    )
+
+    assert blocked["status"] == "resolved"
+    assert blocked["prefix_binding"]["mode"] == "default"
+    assert _outputs(blocked)["output:1"]["runtime_path"] == "output.result.txt"
+    assert resolved["status"] == "resolved"
+    assert resolved["prefix_binding"]["mode"] == "explicit"
+    assert _outputs(resolved)["output:1"]["runtime_path"] == "Chosen.result.txt"
+
+
+def test_different_source_prefixes_use_declared_output_with_explicit_prefix(
+    tmp_path: Path,
+) -> None:
+    first = _file(tmp_path, "X.one.fa")
+    second = _file(tmp_path, "Y.two.fa")
+    contract = _contract(
+        inputs=[
+            _input("input:1", "Ft.one.fa"),
+            _input("input:2", "Ft.SPL.two.fa"),
+        ],
+        outputs=[("output:1", "Ft.SPL.result.txt")],
+    )
+
+    result = resolve_runtime_bindings(
+        contract,
+        {"input:1": first, "input:2": second},
+        {},
+        explicit_prefix="Chosen",
+    )
+
+    assert result["status"] == "resolved"
+    assert result["prefix_binding"]["mode"] == "explicit"
+    assert _outputs(result)["output:1"]["runtime_path"] == "Chosen.txt"
+
+
+def test_duplicate_input_facts_group_by_path_and_conflicts_are_blocked(
+    tmp_path: Path,
+) -> None:
+    first = _file(tmp_path, "Runtime.fa")
+    other = _file(tmp_path, "Other.fa")
+    contract = _contract(
+        inputs=[
+            _input("input:1", "Ft.fa", "sequences"),
+            _input("input:2", "Ft.fa", "sequences"),
+        ],
+        outputs=[("output:1", "Ft.out")],
+    )
+
+    grouped = resolve_runtime_bindings(
+        contract, {"sequences": first}, {}
+    )
+    conflict = resolve_runtime_bindings(
+        contract, {"input:1": first, "input:2": other}, {}
+    )
+
+    assert grouped["status"] == "resolved"
+    assert grouped["input_bindings"][0]["fact_ids"] == ["input:1", "input:2"]
+    assert conflict["error"]["code"] == "INPUT_BINDING_CONFLICT"
+
+
+def test_missing_unknown_and_nonexistent_inputs_have_stable_codes(
+    tmp_path: Path,
+) -> None:
+    contract = _contract(
+        inputs=[_input("input:1", "Ft.fa")],
+        outputs=[("output:1", "Ft.out")],
+    )
+
+    missing = resolve_runtime_bindings(contract, {}, {})
+    unknown = resolve_runtime_bindings(
+        contract, {"invented": _file(tmp_path, "Runtime.fa")}, {}
+    )
+    nonexistent = resolve_runtime_bindings(
+        contract, {"input:1": tmp_path / "absent.fa"}, {}
+    )
+
+    assert missing["error"]["code"] == "INPUT_BINDING_MISSING"
+    assert unknown["error"]["code"] == "INPUT_NOT_DECLARED"
+    assert nonexistent["error"]["code"] == "INPUT_PATH_NOT_FOUND"
+
+
+def test_stdout_only_contract_does_not_need_output_prefix(tmp_path: Path) -> None:
+    replacement = _file(tmp_path, "Runtime.fa")
+    contract = _contract(
+        inputs=[_input("input:1", "input.fa")],
+        outputs=[],
+        stdout=True,
+    )
+
+    result = resolve_runtime_bindings(
+        contract, {"input.fa": replacement}, {}
+    )
+
+    assert result["status"] == "resolved"
+    assert result["prefix_binding"]["mode"] == "none"
+    assert result["output_bindings"] == []
+
+
+def test_parameter_overrides_only_declared_values_and_safe_switches(
+    tmp_path: Path,
+) -> None:
+    replacement = _file(tmp_path, "Ft.fa")
+    contract = _contract(
+        inputs=[_input("input:1", "Ft.fa")],
+        outputs=[("output:1", "Ft.out")],
+        parameters=[
+            {
+                "fact_id": "parameter:model",
+                "kind": "flag_value",
+                "flag": "-m",
+                "value": "MFP",
+            },
+            {
+                "fact_id": "parameter:threshold",
+                "kind": "switch",
+                "flag": "--cut_tc",
+                "value": "--cut_tc",
+            },
+            {
+                "fact_id": "parameter:count",
+                "kind": "positional",
+                "flag": None,
+                "value": "10",
+            },
+        ],
+    )
+
+    result = resolve_runtime_bindings(
+        contract,
+        {"input:1": replacement},
+        {
+            "parameter:model": "LG+G4",
+            "parameter:threshold": "--cut_ga",
+            "parameter:count": 20,
+        },
+    )
+
+    bindings = {item["fact_id"]: item for item in result["parameter_bindings"]}
+    assert result["status"] == "resolved"
+    assert bindings["parameter:model"]["flag"] == "-m"
+    assert bindings["parameter:model"]["runtime_value"] == "LG+G4"
+    assert bindings["parameter:threshold"]["runtime_value"] == "--cut_ga"
+    assert bindings["parameter:count"]["runtime_value"] == "20"
+
+
+def test_unknown_and_unsafe_parameter_overrides_are_blocked(
+    tmp_path: Path,
+) -> None:
+    replacement = _file(tmp_path, "Ft.fa")
+    contract = _contract(
+        inputs=[_input("input:1", "Ft.fa")],
+        outputs=[("output:1", "Ft.out")],
+        parameters=[
+            {
+                "fact_id": "parameter:threshold",
+                "kind": "switch",
+                "flag": "--cut_tc",
+                "value": "--cut_tc",
+            }
+        ],
+    )
+
+    unknown = resolve_runtime_bindings(
+        contract, {"input:1": replacement}, {"parameter:other": "x"}
+    )
+    whitespace = resolve_runtime_bindings(
+        contract,
+        {"input:1": replacement},
+        {"parameter:threshold": "--cut_ga extra"},
+    )
+    control = resolve_runtime_bindings(
+        contract,
+        {"input:1": replacement},
+        {"parameter:threshold": "--cut_ga\nrm"},
+    )
+
+    assert unknown["error"]["code"] == "PARAMETER_NOT_DECLARED"
+    assert unknown["error"]["available_fact_ids"] == ["parameter:threshold"]
+    assert whitespace["error"]["code"] == "PARAMETER_VALUE_INVALID"
+    assert control["error"]["code"] == "PARAMETER_VALUE_INVALID"
+
+
+def test_resolution_is_deterministic_json_and_does_not_mutate_arguments(
+    tmp_path: Path,
+) -> None:
+    replacement = _file(tmp_path, "Runtime.fa")
+    contract = _contract(
+        inputs=[_input("input:1", "Ft.fa")],
+        outputs=[("output:1", "Ft.out")],
+    )
+    input_overrides = {"input:1": replacement}
+    parameter_overrides: dict = {}
+    original_contract = deepcopy(contract)
+    original_inputs = dict(input_overrides)
+
+    first = resolve_runtime_bindings(
+        contract, input_overrides, parameter_overrides
+    )
+    second = resolve_runtime_bindings(
+        contract, input_overrides, parameter_overrides
+    )
+
+    assert first == second
+    assert len(first["binding_digest"]) == 64
+    assert contract == original_contract
+    assert input_overrides == original_inputs
+    assert parameter_overrides == {}
+
+
+def test_dev_contracts_match_all_runtime_binding_gold_cases(
+    tmp_path: Path,
+) -> None:
+    if not (CATALOG_ROOT / "runtime_binding_dev_gold.json").is_file():
+        pytest.skip("runtime-binding benchmark data is outside this migration")
+
+    gold = json.loads(
+        (CATALOG_ROOT / "runtime_binding_dev_gold.json").read_text(
+            encoding="utf-8"
+        )
+    )
+    attempt = json.loads(
+        (CATALOG_ROOT / "dev_api_results_attempt_007.json").read_text(
+            encoding="utf-8"
+        )
+    )
+    actual_by_case = {item["case_id"]: item for item in attempt["cases"]}
+    counts = {"resolved": 0, "blocked": 0}
+
+    for expected in gold["cases"]:
+        case_id = expected["case_id"]
+        actual = actual_by_case[case_id]
+        materialized = CATALOG_ROOT / "materialized" / case_id
+        contract = build_runtime_binding_contract(
+            actual["execution_facts"],
+            actual["final_semantic"]["candidate"],
+            materialized / "raw_code",
+        )
+        overrides = {}
+        for binding in expected["input_overrides"]:
+            source = materialized / "raw_test_data" / binding["original_path"]
+            replacement = tmp_path / case_id / binding["replacement_path"]
+            replacement.parent.mkdir(parents=True, exist_ok=True)
+            replacement.write_bytes(source.read_bytes())
+            overrides[binding["fact_id"]] = replacement
+
+        result = resolve_runtime_bindings(contract, overrides, {})
+        counts[result["status"]] += 1
+        wanted_status = (
+            "resolved" if expected["expected_status"] == "runnable" else "blocked"
+        )
+        assert result["status"] == wanted_status, case_id
+        if wanted_status == "blocked":
+            assert result["error"]["code"] == expected["blocked"]["code"], case_id
+            continue
+
+        assert result["prefix_binding"]["old_prefix"] == expected["evidence"]["old_prefix"], case_id
+        assert result["prefix_binding"]["new_prefix"] == expected["evidence"]["new_prefix"], case_id
+        actual_outputs = _outputs(result)
+        for output in expected["expected_output_path_transforms"]:
+            assert actual_outputs[output["fact_id"]]["runtime_path"] == output["expected_path"], case_id
+            assert actual_outputs[output["fact_id"]]["transformed"] is output["transformed"], case_id
+
+    assert counts == {"resolved": 16, "blocked": 0}
+
+
+def test_colliding_runtime_output_paths_are_blocked(tmp_path: Path) -> None:
+    replacement = _file(tmp_path, "Runtime.fa")
+    contract = _contract(
+        inputs=[_input("input:1", "Ft.fa")],
+        outputs=[("output:1", "Ft.out"), ("output:2", "output.out")],
+    )
+
+    result = resolve_runtime_bindings(contract, {"input:1": replacement}, {})
+
+    assert result["status"] == "blocked"
+    assert result["error"]["code"] == "OUTPUT_PATH_COLLISION"
+
+
+def test_explicit_and_inferred_prefixes_share_strict_validation(
+    tmp_path: Path,
+) -> None:
+    contract = _contract(
+        inputs=[_input("input:1", "Ft.fa")],
+        outputs=[("output:1", "Ft.out")],
+    )
+    safe_input = _file(tmp_path, "Runtime.fa")
+    unsafe_inferred = _file(tmp_path, "Runtime\nName.fa")
+
+    inferred = resolve_runtime_bindings(
+        contract, {"input:1": unsafe_inferred}, {}
+    )
+    explicit_results = [
+        resolve_runtime_bindings(
+            contract,
+            {"input:1": safe_input},
+            {},
+            explicit_prefix=value,
+        )
+        for value in ("with space", "$(touch_x)", "-leading")
+    ]
+
+    assert inferred["error"]["code"] == "INVALID_PREFIX"
+    assert [item["error"]["code"] for item in explicit_results] == [
+        "INVALID_PREFIX",
+        "INVALID_PREFIX",
+        "INVALID_PREFIX",
+    ]
+
+
+def test_symlink_runtime_name_drives_prefix_without_mutating_inputs(
+    tmp_path: Path,
+) -> None:
+    target = _file(tmp_path, "old_name.fa")
+    replacement = tmp_path / "new_name.fa"
+    replacement.symlink_to(target.name)
+    contract = _contract(
+        inputs=[_input("input:1", "old_name.fa")],
+        outputs=[("output:1", "old_name.out")],
+    )
+    overrides = {"input:1": replacement}
+    original_contract = deepcopy(contract)
+    original_overrides = dict(overrides)
+
+    result = resolve_runtime_bindings(contract, overrides, {})
+
+    assert result["status"] == "resolved"
+    assert Path(result["input_bindings"][0]["runtime_path"]).name == "new_name.fa"
+    assert result["prefix_binding"]["new_prefix"] == "output"
+    assert _outputs(result)["output:1"]["runtime_path"] == "output.out"
+    assert contract == original_contract
+    assert overrides == original_overrides
+
+
+def test_symlink_separator_change_uses_default_output_prefix(
+    tmp_path: Path,
+) -> None:
+    target = _file(tmp_path, "Ft-Ath.collinearity")
+    replacement = tmp_path / "Runtime-Reference.collinearity"
+    replacement.symlink_to(target.name)
+    contract = _contract(
+        inputs=[_input("input:1", "Ft-Ath.collinearity")],
+        outputs=[("output:1", "Ft.Ath.anchors")],
+    )
+
+    result = resolve_runtime_bindings(
+        contract, {"input:1": replacement}, {}
+    )
+
+    assert result["status"] == "resolved"
+    assert _outputs(result)["output:1"]["runtime_path"] == "output.anchors"
+
+
+def test_dangling_runtime_input_symlink_is_rejected(tmp_path: Path) -> None:
+    replacement = tmp_path / "new_name.fa"
+    replacement.symlink_to("missing.fa")
+    contract = _contract(
+        inputs=[_input("input:1", "old_name.fa")],
+        outputs=[("output:1", "old_name.out")],
+    )
+
+    result = resolve_runtime_bindings(
+        contract, {"input:1": replacement}, {}
+    )
+
+    assert result["status"] == "blocked"
+    assert result["error"]["code"] == "INPUT_PATH_NOT_FOUND"
diff --git a/tests/unit/test_extension_stage_lightweight_runtime_package.py b/tests/unit/test_extension_stage_lightweight_runtime_package.py
new file mode 100644
index 000000000..bee044d56
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_runtime_package.py
@@ -0,0 +1,1459 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from pathlib import Path
+import shlex
+import time
+
+import pytest
+
+import gfa_core.extension_stage_lightweight.runtime_binding as runtime_module
+from gfa_core.extension_stage_lightweight.command_model import (
+    _prepare_script_commands,
+)
+from gfa_core.extension_stage_lightweight.runtime_binding import (
+    RuntimeBindingError,
+    render_runtime_package,
+    replay_runtime_binding,
+    resolve_runtime_bindings,
+)
+
+
+def _sha256_bytes(value: bytes) -> str:
+    return hashlib.sha256(value).hexdigest()
+
+
+def _sha256_json(value: object) -> str:
+    payload = json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+    ).encode("utf-8")
+    return hashlib.sha256(payload).hexdigest()
+
+
+def _refresh_digest(value: dict, field: str) -> None:
+    value[field] = _sha256_json(
+        {key: item for key, item in value.items() if key != field}
+    )
+
+
+def _write(root: Path, relative: str, content: str) -> Path:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def _target(
+    *,
+    binding_key: str,
+    literal: str,
+    kind: str,
+    script_hash: str,
+    count: int = 1,
+    fact_ids: list[str] | None = None,
+) -> dict:
+    return {
+        "binding_key": binding_key,
+        "fact_ids": fact_ids or [],
+        "original_literal": literal,
+        "patch_kind": kind,
+        "script_path": "run.sh",
+        "script_hash": script_hash,
+        "expected_exact_match_count": count,
+    }
+
+
+def _contract_and_resolved(
+    raw_code: Path,
+    runtime_input: Path,
+    *,
+    script: str,
+    original_input: str = "Ft.input.txt",
+    output_bindings: list[dict] | None = None,
+    parameter_bindings: list[dict] | None = None,
+    stdout: bool = False,
+    path_references: list[dict] | None = None,
+    patch_targets: list[dict] | None = None,
+    unpatchable_targets: list[dict] | None = None,
+) -> tuple[dict, dict]:
+    script_path = _write(raw_code, "run.sh", script)
+    script_hash = _sha256_bytes(script_path.read_bytes())
+    commands = _prepare_script_commands(script, [])
+    targets = []
+    for supplied in patch_targets or []:
+        target = dict(supplied)
+        anchors = []
+        for index, command in enumerate(commands, start=1):
+            for token_index, token in enumerate(shlex.split(command)):
+                if token == target["original_literal"]:
+                    anchors.append(
+                        {
+                            "fact_id": target["fact_ids"][0],
+                            "step_id": f"step_{index:03d}",
+                            "command_digest": _sha256_bytes(command.encode()),
+                            "token_index": token_index,
+                        }
+                    )
+        target["anchors"] = anchors
+        targets.append(target)
+    data_hash = _sha256_bytes(runtime_input.read_bytes())
+    contract = {
+        "schema_version": "lightweight-runtime-binding/v1",
+        "facts_sha256": "facts-locked",
+        "package_digest": "",
+        "original_command": "bash run.sh",
+        "source_scripts": [
+            {"path": "run.sh", "sha256": script_hash, "locked": True}
+        ],
+        "package_files": [
+            {
+                "path": "run.sh",
+                "source": "raw_code",
+                "kind": "file",
+                "size": script_path.stat().st_size,
+                "sha256": script_hash,
+                "locked": True,
+                "exposed_as_input": False,
+            },
+            {
+                "path": original_input,
+                "source": "raw_test_data",
+                "kind": "file",
+                "size": runtime_input.stat().st_size,
+                "sha256": data_hash,
+                "locked": False,
+                "exposed_as_input": True,
+            },
+        ],
+        "inputs": [
+            {
+                "fact_id": "input:1",
+                "path": original_input,
+                "source": "baseline_input",
+                "replaceable": True,
+            }
+        ],
+        "parameters": [
+            {
+                "fact_id": item["fact_id"],
+                "kind": item["kind"],
+                "flag": item["flag"],
+                "value": item["original_value"],
+            }
+            for item in (parameter_bindings or [])
+        ],
+        "path_references": path_references or [],
+        "outputs": {
+            "files": [
+                {
+                    "fact_id": item["fact_id"],
+                    "path": item["original_path"],
+                }
+                for item in (output_bindings or [])
+            ],
+            "stdout": {"present": stdout},
+        },
+        "patch_targets": targets,
+        "unpatchable_targets": unpatchable_targets or [],
+    }
+    inventory = {
+        item["path"]: {
+            key: item[key]
+            for key in ("kind", "size", "sha256", "source")
+        }
+        for item in contract["package_files"]
+    }
+    contract["package_digest"] = _sha256_json(inventory)
+    _refresh_digest(contract, "contract_digest")
+    resolved = resolve_runtime_bindings(
+        contract,
+        {"input:1": runtime_input},
+        {
+            item["fact_id"]: item["runtime_value"]
+            for item in (parameter_bindings or [])
+        },
+    )
+    assert resolved["status"] == "resolved", resolved
+    return contract, resolved
+
+
+def test_render_copies_and_patches_only_working_code_and_materializes_input(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Sample.input.txt", "a\nb\n")
+    original = (
+        "cp Ft.input.txt Ft.tmp.txt\n"
+        "head -n 1 Ft.tmp.txt > Ft.output.txt\n"
+        "sort -u Ft.output.txt > Ft.sorted.txt\n"
+    )
+    script_hash = _sha256_bytes(original.encode())
+    outputs = [
+        {
+            "fact_id": "output:tmp",
+            "original_path": "Ft.tmp.txt",
+            "runtime_path": "Sample.tmp.txt",
+            "transformed": True,
+        },
+        {
+            "fact_id": "output:main",
+            "original_path": "Ft.output.txt",
+            "runtime_path": "Sample.output.txt",
+            "transformed": True,
+        },
+        {
+            "fact_id": "output:sorted",
+            "original_path": "Ft.sorted.txt",
+            "runtime_path": "Sample.sorted.txt",
+            "transformed": True,
+        },
+    ]
+    parameters = [
+        {
+            "fact_id": "parameter:n",
+            "kind": "flag_value",
+            "flag": "-n",
+            "original_value": "1",
+            "runtime_value": "2",
+            "changed": True,
+        },
+        {
+            "fact_id": "parameter:sort",
+            "kind": "switch",
+            "flag": "-u",
+            "original_value": "-u",
+            "runtime_value": "-r",
+            "changed": True,
+        },
+    ]
+    targets = [
+        _target(
+            binding_key="path:Ft.input.txt",
+            literal="Ft.input.txt",
+            kind="input_path",
+            script_hash=script_hash,
+            fact_ids=["input:1"],
+        ),
+        _target(
+            binding_key="path:Ft.tmp.txt",
+            literal="Ft.tmp.txt",
+            kind="output_path",
+            script_hash=script_hash,
+            count=2,
+            fact_ids=["output:tmp"],
+        ),
+        _target(
+            binding_key="path:Ft.output.txt",
+            literal="Ft.output.txt",
+            kind="output_path",
+            script_hash=script_hash,
+            count=2,
+            fact_ids=["output:main"],
+        ),
+        _target(
+            binding_key="path:Ft.sorted.txt",
+            literal="Ft.sorted.txt",
+            kind="output_path",
+            script_hash=script_hash,
+            fact_ids=["output:sorted"],
+        ),
+        _target(
+            binding_key="parameter:parameter:n",
+            literal="1",
+            kind="parameter_value",
+            script_hash=script_hash,
+            fact_ids=["parameter:n"],
+        ),
+        _target(
+            binding_key="parameter:parameter:sort",
+            literal="-u",
+            kind="parameter_switch",
+            script_hash=script_hash,
+            fact_ids=["parameter:sort"],
+        ),
+    ]
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=original,
+        output_bindings=outputs,
+        parameter_bindings=parameters,
+        patch_targets=targets,
+    )
+
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+
+    assert (raw_code / "run.sh").read_text(encoding="utf-8") == original
+    patched = (tmp_path / "run/work/run.sh").read_text(encoding="utf-8")
+    assert "cp Sample.input.txt output.tmp.txt" in patched
+    assert "head -n 2 output.tmp.txt > output.output.txt" in patched
+    assert "sort -r output.output.txt > output.sorted.txt" in patched
+    materialized = tmp_path / "run/work/Sample.input.txt"
+    assert materialized.is_symlink()
+    assert materialized.resolve() == runtime_input.resolve()
+    assert not (tmp_path / "run/work/output.output.txt").exists()
+    record = json.loads(
+        (tmp_path / "run/runtime_binding_record.json").read_text(encoding="utf-8")
+    )
+    assert record == rendered
+    assert record["source_hashes"]["run.sh"] == script_hash
+    assert record["patch_diff"]
+
+
+def test_render_copies_input_when_the_same_path_is_a_modified_output(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Sample.txt", "before\n")
+    script = "printf 'after\\n' >> Ft.input.txt\n"
+    script_hash = _sha256_bytes(script.encode())
+    outputs = [
+        {
+            "fact_id": "output:1",
+            "original_path": "Ft.input.txt",
+            "runtime_path": "Sample.txt",
+            "transformed": True,
+        }
+    ]
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        output_bindings=outputs,
+        patch_targets=[
+            _target(
+                binding_key="path:Ft.input.txt",
+                literal="Ft.input.txt",
+                kind="output_path",
+                script_hash=script_hash,
+                fact_ids=["input:1", "output:1"],
+            )
+        ],
+    )
+
+    rendered = render_runtime_package(contract, raw_code, resolved, tmp_path / "run")
+
+    materialized = tmp_path / "run/work/Sample.txt"
+    assert materialized.is_file() and not materialized.is_symlink()
+    assert materialized.read_text(encoding="utf-8") == "before\n"
+    result = replay_runtime_binding(rendered)
+    assert result["contract_passed"] is True
+    assert runtime_input.read_text(encoding="utf-8") == "before\n"
+    assert materialized.read_text(encoding="utf-8") == "before\nafter\n"
+
+
+def test_render_rechecks_each_copied_source_hash(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Ft.input.txt", "x\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="cat Ft.input.txt\n",
+        stdout=True,
+    )
+    original_copy = runtime_module.shutil.copy2
+
+    def corrupt_copy(source: Path, destination: Path) -> Path:
+        copied = original_copy(source, destination)
+        if Path(source) == raw_code / "run.sh":
+            Path(destination).write_text("corrupted\n", encoding="utf-8")
+        return copied
+
+    monkeypatch.setattr(runtime_module.shutil, "copy2", corrupt_copy)
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(contract, raw_code, resolved, tmp_path / "run")
+
+    assert caught.value.code == "SOURCE_COPY_HASH_MISMATCH"
+
+
+@pytest.mark.parametrize(
+    ("mutation", "code"),
+    [
+        ("source_hash", "SOURCE_HASH_MISMATCH"),
+        ("match_count", "PATCH_MATCH_COUNT_MISMATCH"),
+        ("digest", "RESOLUTION_DIGEST_MISMATCH"),
+    ],
+)
+def test_render_fails_closed_on_hash_match_or_resolution_mismatch(
+    tmp_path: Path, mutation: str, code: str
+) -> None:
+    raw_code = tmp_path / mutation / "raw_code"
+    runtime_input = _write(tmp_path, f"{mutation}/Sample.input.txt", "x\n")
+    script = "cp Ft.input.txt Ft.output.txt\n"
+    script_hash = _sha256_bytes(script.encode())
+    outputs = [
+        {
+            "fact_id": "output:1",
+            "original_path": "Ft.output.txt",
+            "runtime_path": "Sample.output.txt",
+            "transformed": True,
+        }
+    ]
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        output_bindings=outputs,
+        patch_targets=[
+            _target(
+                binding_key="path:Ft.input.txt",
+                literal="Ft.input.txt",
+                kind="input_path",
+                script_hash=script_hash,
+                fact_ids=["input:1"],
+            ),
+            _target(
+                binding_key="path:Ft.output.txt",
+                literal="Ft.output.txt",
+                kind="output_path",
+                script_hash=script_hash,
+                fact_ids=["output:1"],
+            ),
+        ],
+    )
+    if mutation == "source_hash":
+        (raw_code / "run.sh").write_text(script + "# changed\n", encoding="utf-8")
+    elif mutation == "match_count":
+        contract["patch_targets"][0]["expected_exact_match_count"] = 2
+        _refresh_digest(contract, "contract_digest")
+        resolved["contract_digest"] = contract["contract_digest"]
+        _refresh_digest(resolved, "binding_digest")
+    else:
+        resolved["binding_digest"] = "0" * 64
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(
+            contract, raw_code, resolved, tmp_path / mutation / "run"
+        )
+
+    assert caught.value.code == code
+
+
+def test_render_rejects_changed_binding_with_only_unpatchable_target(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Sample.input.txt", "x\n")
+    script = "cp Ft.input.txt Ft.output.txt\n"
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        output_bindings=[
+            {
+                "fact_id": "output:1",
+                "original_path": "Ft.output.txt",
+                "runtime_path": "Ft.output.txt",
+                "transformed": False,
+            }
+        ],
+        unpatchable_targets=[
+            {
+                "binding_key": "path:Ft.input.txt",
+                "fact_ids": ["input:1"],
+                "original_literal": "Ft.input.txt",
+                "patch_kind": "input_path",
+                "reason": "source_literal_not_found_in_raw_shell",
+            }
+        ],
+    )
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(contract, raw_code, resolved, tmp_path / "run")
+
+    assert caught.value.code == "PATCH_TARGET_UNAVAILABLE"
+
+
+@pytest.mark.parametrize("bad_path", ["../run.sh", "/tmp/run.sh"])
+def test_render_rejects_code_traversal(tmp_path: Path, bad_path: str) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Ft.input.txt", "x\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="cat Ft.input.txt\n",
+        stdout=True,
+    )
+    contract["package_files"][0]["path"] = bad_path
+    _refresh_digest(contract, "contract_digest")
+    resolved["contract_digest"] = contract["contract_digest"]
+    _refresh_digest(resolved, "binding_digest")
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(contract, raw_code, resolved, tmp_path / "run")
+
+    assert caught.value.code == "UNSAFE_RELATIVE_PATH"
+
+
+def test_render_rejects_input_basename_and_code_collisions(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/run.sh", "not code\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="cat Ft.input.txt\n",
+        stdout=True,
+    )
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(contract, raw_code, resolved, tmp_path / "run")
+
+    assert caught.value.code == "RUNTIME_PATH_COLLISION"
+
+
+def test_replay_executes_two_step_file_contract_and_records_logs(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Sample.input.txt", "a\nb\n")
+    script = (
+        "cp Ft.input.txt Ft.tmp.txt\n"
+        "head -n 1 Ft.tmp.txt > Ft.output.txt\n"
+    )
+    script_hash = _sha256_bytes(script.encode())
+    outputs = [
+        {
+            "fact_id": "output:tmp",
+            "original_path": "Ft.tmp.txt",
+            "runtime_path": "Sample.tmp.txt",
+            "transformed": True,
+        },
+        {
+            "fact_id": "output:main",
+            "original_path": "Ft.output.txt",
+            "runtime_path": "Sample.output.txt",
+            "transformed": True,
+        },
+    ]
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        output_bindings=outputs,
+        patch_targets=[
+            _target(
+                binding_key="path:Ft.input.txt",
+                literal="Ft.input.txt",
+                kind="input_path",
+                script_hash=script_hash,
+                fact_ids=["input:1"],
+            ),
+            _target(
+                binding_key="path:Ft.tmp.txt",
+                literal="Ft.tmp.txt",
+                kind="output_path",
+                script_hash=script_hash,
+                count=2,
+                fact_ids=["output:tmp"],
+            ),
+            _target(
+                binding_key="path:Ft.output.txt",
+                literal="Ft.output.txt",
+                kind="output_path",
+                script_hash=script_hash,
+                fact_ids=["output:main"],
+            ),
+        ],
+    )
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+
+    result = replay_runtime_binding(rendered)
+
+    assert result["success"] is True
+    assert result["returncode"] == 0
+    assert result["contract_passed"] is True
+    assert result["missing_outputs"] == []
+    assert {item["runtime_path"] for item in result["outputs"]} == {
+        "output.tmp.txt",
+        "output.output.txt",
+    }
+    assert (tmp_path / "run/work/output.output.txt").read_text(
+        encoding="utf-8"
+    ) == "a\n"
+    for path in result["logs"].values():
+        assert Path(path).is_file()
+    events = [
+        json.loads(line)
+        for line in Path(result["logs"]["events"]).read_text(
+            encoding="utf-8"
+        ).splitlines()
+    ]
+    assert [item["event"] for item in events] == ["start", "finish"]
+    assert events[-1]["returncode"] == 0
+    assert events[-1]["contract_passed"] is True
+    assert events[-1]["missing_outputs"] == []
+    assert events[-1]["failure_type"] is None
+    result_path = tmp_path / "run/runtime_execution_result.json"
+    assert json.loads(result_path.read_text(encoding="utf-8")) == result
+
+
+def test_replay_stdout_contract_has_no_arbitrary_timeout(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Ft.input.txt", "a\nb\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="sleep 0.05\nwc -l Ft.input.txt\n",
+        stdout=True,
+    )
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+
+    started = time.monotonic()
+    result = replay_runtime_binding(rendered)
+
+    assert time.monotonic() - started >= 0.04
+    assert result["success"] is True
+    assert result["contract_passed"] is True
+    assert Path(result["logs"]["stdout"]).read_text(encoding="utf-8").strip() == "2 Ft.input.txt"
+
+
+def test_replay_rejects_a_detached_work_directory(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Ft.input.txt", "a\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="cat Ft.input.txt\n",
+        stdout=True,
+    )
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+    detached = tmp_path / "run/other"
+    detached.mkdir()
+    rendered["work_dir"] = str(detached)
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        replay_runtime_binding(rendered)
+
+    assert caught.value.code == "RENDERED_PACKAGE_INVALID"
+
+
+def test_replay_rejects_user_bash_env_and_scrubs_inherited_bash_env(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Ft.input.txt", "a\n")
+    injected = _write(
+        tmp_path,
+        "injected.sh",
+        f"printf injected > {tmp_path / 'injected.marker'}\n",
+    )
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="cat Ft.input.txt\n",
+        stdout=True,
+    )
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        replay_runtime_binding(rendered, env={"BASH_ENV": str(injected)})
+    assert caught.value.code == "UNSAFE_ENVIRONMENT"
+    assert not (tmp_path / "injected.marker").exists()
+
+    monkeypatch.setenv("BASH_ENV", str(injected))
+    result = replay_runtime_binding(rendered)
+    assert result["contract_passed"] is True
+    assert not (tmp_path / "injected.marker").exists()
+
+
+def test_render_rejects_resolved_with_deleted_outputs_even_after_rehash(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Sample.input.txt", "a\n")
+    script = "cp Ft.input.txt Ft.output.txt\n"
+    script_hash = _sha256_bytes(script.encode())
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        output_bindings=[
+            {
+                "fact_id": "output:1",
+                "original_path": "Ft.output.txt",
+                "runtime_path": "Sample.output.txt",
+                "transformed": True,
+            }
+        ],
+        patch_targets=[
+            _target(
+                binding_key="path:Ft.input.txt",
+                literal="Ft.input.txt",
+                kind="input_path",
+                script_hash=script_hash,
+                fact_ids=["input:1"],
+            ),
+            _target(
+                binding_key="path:Ft.output.txt",
+                literal="Ft.output.txt",
+                kind="output_path",
+                script_hash=script_hash,
+                fact_ids=["output:1"],
+            ),
+        ],
+    )
+    resolved["output_bindings"] = []
+    _refresh_digest(resolved, "binding_digest")
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(contract, raw_code, resolved, tmp_path / "run")
+
+    assert caught.value.code == "RESOLUTION_CANONICAL_MISMATCH"
+
+
+def test_render_rejects_tampered_contract_and_reconstructed_package_digest(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Ft.input.txt", "a\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="cat Ft.input.txt\n",
+        stdout=True,
+    )
+    contract["outputs"]["stdout"]["present"] = False
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(contract, raw_code, resolved, tmp_path / "run-a")
+    assert caught.value.code == "CONTRACT_DIGEST_MISMATCH"
+
+    contract["outputs"]["stdout"]["present"] = True
+    contract["package_digest"] = "0" * 64
+    _refresh_digest(contract, "contract_digest")
+    resolved["package_digest"] = contract["package_digest"]
+    resolved["contract_digest"] = contract["contract_digest"]
+    _refresh_digest(resolved, "binding_digest")
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(contract, raw_code, resolved, tmp_path / "run-b")
+    assert caught.value.code == "PACKAGE_DIGEST_MISMATCH"
+
+
+def test_render_rejects_a_wrong_command_anchor(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Sample.input.txt", "a\n")
+    script = "cp Ft.input.txt Ft.output.txt\n"
+    script_hash = _sha256_bytes(script.encode())
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        output_bindings=[
+            {
+                "fact_id": "output:1",
+                "original_path": "Ft.output.txt",
+                "runtime_path": "Sample.output.txt",
+                "transformed": True,
+            }
+        ],
+        patch_targets=[
+            _target(
+                binding_key="path:Ft.input.txt",
+                literal="Ft.input.txt",
+                kind="input_path",
+                script_hash=script_hash,
+                fact_ids=["input:1"],
+            ),
+            _target(
+                binding_key="path:Ft.output.txt",
+                literal="Ft.output.txt",
+                kind="output_path",
+                script_hash=script_hash,
+                fact_ids=["output:1"],
+            ),
+        ],
+    )
+    contract["patch_targets"][0]["anchors"][0]["command_digest"] = "0" * 64
+    _refresh_digest(contract, "contract_digest")
+    resolved["contract_digest"] = contract["contract_digest"]
+    _refresh_digest(resolved, "binding_digest")
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(contract, raw_code, resolved, tmp_path / "run")
+
+    assert caught.value.code == "PATCH_ANCHOR_MISMATCH"
+
+
+def test_render_rejects_symlinked_raw_code(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Ft.input.txt", "a\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="cat Ft.input.txt\n",
+        stdout=True,
+    )
+    external = _write(tmp_path, "external/run.sh", "cat Ft.input.txt\n")
+    (raw_code / "run.sh").unlink()
+    (raw_code / "run.sh").symlink_to(external)
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(contract, raw_code, resolved, tmp_path / "run")
+
+    assert caught.value.code == "SOURCE_SYMLINK_UNSAFE"
+
+
+def test_render_rejects_option_like_runtime_input_basename(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/--help", "a\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="cat Ft.input.txt\n",
+        stdout=True,
+        unpatchable_targets=[
+            {
+                "binding_key": "path:Ft.input.txt",
+                "fact_ids": ["input:1"],
+                "original_literal": "Ft.input.txt",
+                "patch_kind": "input_path",
+                "reason": "source_literal_not_found_in_raw_shell",
+            }
+        ],
+    )
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(contract, raw_code, resolved, tmp_path / "run")
+
+    assert caught.value.code == "UNSAFE_INPUT_BASENAME"
+
+
+@pytest.mark.parametrize(
+    "mutation",
+    ["work_script", "disk_record", "actual_command", "output_list"],
+)
+def test_replay_rejects_runtime_package_tampering(
+    tmp_path: Path, mutation: str
+) -> None:
+    case_root = tmp_path / mutation
+    raw_code = case_root / "raw_code"
+    runtime_input = _write(case_root, "runtime/Ft.input.txt", "a\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="cat Ft.input.txt\n",
+        stdout=True,
+    )
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, case_root / "run"
+    )
+    if mutation == "work_script":
+        (case_root / "run/work/run.sh").write_text("echo changed\n", encoding="utf-8")
+        expected_code = "WORK_PACKAGE_CHANGED"
+    elif mutation == "disk_record":
+        path = case_root / "run/runtime_binding_record.json"
+        disk = json.loads(path.read_text(encoding="utf-8"))
+        disk["actual_command"] = ":"
+        path.write_text(json.dumps(disk), encoding="utf-8")
+        expected_code = "RECORD_DIGEST_MISMATCH"
+    elif mutation == "actual_command":
+        rendered["actual_command"] = ":"
+        _refresh_digest(rendered, "record_digest")
+        expected_code = "RECORD_MISMATCH"
+    else:
+        rendered["expected_outputs"] = [
+            {
+                "fact_id": "invented",
+                "original_path": "invented.txt",
+                "runtime_path": "invented.txt",
+            }
+        ]
+        _refresh_digest(rendered, "record_digest")
+        expected_code = "RECORD_MISMATCH"
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        replay_runtime_binding(rendered)
+
+    assert caught.value.code == expected_code
+
+
+def test_replay_rejects_runtime_input_content_drift(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Ft.input.txt", "before\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="cat Ft.input.txt\n",
+        stdout=True,
+    )
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+    runtime_input.write_text("after\n", encoding="utf-8")
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        replay_runtime_binding(rendered)
+
+    assert caught.value.code == "INPUT_CONTENT_CHANGED"
+
+
+def test_replay_does_not_search_a_valid_tool_path_for_bash(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Ft.input.txt", "a\n")
+    marker = tmp_path / "fake-bash.marker"
+    fake_bash = _write(
+        tmp_path,
+        "fake-bin/bash",
+        f"#!/bin/sh\nprintf fake > {marker}\n",
+    )
+    fake_bash.chmod(0o755)
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="printf 'ok\\n'\n",
+        stdout=True,
+    )
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+
+    explicit = replay_runtime_binding(
+        rendered, env={"PATH": str(fake_bash.parent)}
+    )
+    assert explicit["contract_passed"] is True
+    assert not marker.exists()
+    assert explicit["bash_path"] in {"/usr/bin/bash", "/bin/bash"}
+    assert explicit["tool_path_entries"] == [str(fake_bash.parent.resolve())]
+    assert len(explicit["tool_path_digest"]) == 64
+
+
+def test_replay_allows_a_valid_explicit_path_for_external_tools(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Ft.input.txt", "a\n")
+    dummy = _write(
+        tmp_path,
+        "tools/dummy_tool",
+        "#!/bin/sh\nprintf 'dummy-ok\\n'\n",
+    )
+    dummy.chmod(0o755)
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="dummy_tool\n",
+        stdout=True,
+    )
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+
+    result = replay_runtime_binding(
+        rendered,
+        env={"PATH": os.pathsep.join([str(dummy.parent), "/usr/bin", "/bin"])},
+    )
+
+    assert result["contract_passed"] is True
+    assert Path(result["logs"]["stdout"]).read_text(encoding="utf-8").strip() == "dummy-ok"
+    assert result["tool_path_entries"][0] == str(dummy.parent.resolve())
+
+
+@pytest.mark.parametrize("tool_path", ["relative/bin:/usr/bin", ":/usr/bin", ""])
+def test_replay_rejects_relative_or_empty_explicit_tool_path(
+    tmp_path: Path, tool_path: str
+) -> None:
+    case_root = tmp_path / hashlib.sha256(tool_path.encode()).hexdigest()[:8]
+    raw_code = case_root / "raw_code"
+    runtime_input = _write(case_root, "runtime/Ft.input.txt", "a\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="printf 'ok\\n'\n",
+        stdout=True,
+    )
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, case_root / "run"
+    )
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        replay_runtime_binding(rendered, env={"PATH": tool_path})
+
+    assert caught.value.code == "UNSAFE_TOOL_PATH"
+
+
+def test_symlink_runtime_input_keeps_its_lexical_new_name(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    target = _write(tmp_path, "runtime/underlying-old-name.txt", "value\n")
+    runtime_input = tmp_path / "runtime/Sample.input.txt"
+    runtime_input.symlink_to(target)
+    script = "cp Ft.input.txt Ft.output.txt\n"
+    script_hash = _sha256_bytes(script.encode())
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        output_bindings=[
+            {
+                "fact_id": "output:1",
+                "original_path": "Ft.output.txt",
+                "runtime_path": "Sample.output.txt",
+                "transformed": True,
+            }
+        ],
+        patch_targets=[
+            _target(
+                binding_key="path:Ft.input.txt",
+                literal="Ft.input.txt",
+                kind="input_path",
+                script_hash=script_hash,
+                fact_ids=["input:1"],
+            ),
+            _target(
+                binding_key="path:Ft.output.txt",
+                literal="Ft.output.txt",
+                kind="output_path",
+                script_hash=script_hash,
+                fact_ids=["output:1"],
+            ),
+        ],
+    )
+
+    assert resolved["input_bindings"][0]["runtime_path"] == str(runtime_input.absolute())
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+    assert rendered["input_materialization"][0]["materialized_path"] == "Sample.input.txt"
+    result = replay_runtime_binding(rendered)
+    assert result["contract_passed"] is True
+    assert (tmp_path / "run/work/output.output.txt").read_text(encoding="utf-8") == "value\n"
+
+
+def test_explicit_output_reference_covers_its_implicit_multi_outputs(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Sample.input.txt", "value\n")
+    script = (
+        "tool() { cp \"$1\" \"$3.a\"; cp \"$1\" \"$3.b\"; }\n"
+        "tool Ft.input.txt --out Ft.prefix\n"
+    )
+    script_hash = _sha256_bytes(script.encode())
+    reference = {
+        "fact_id": "reference:prefix",
+        "step_id": "step_003",
+        "kind": "flag_value",
+        "flag": "--out",
+        "path": "Ft.prefix",
+        "value": "Ft.prefix",
+        "value_role": "output_reference",
+    }
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        path_references=[reference],
+        output_bindings=[
+            {
+                "fact_id": "output:a",
+                "original_path": "Ft.prefix.a",
+                "runtime_path": "Sample.prefix.a",
+                "transformed": True,
+            },
+            {
+                "fact_id": "output:b",
+                "original_path": "Ft.prefix.b",
+                "runtime_path": "Sample.prefix.b",
+                "transformed": True,
+            },
+        ],
+        patch_targets=[
+            _target(
+                binding_key="path:Ft.input.txt",
+                literal="Ft.input.txt",
+                kind="input_path",
+                script_hash=script_hash,
+                fact_ids=["input:1"],
+            ),
+            _target(
+                binding_key="path_reference:reference:prefix",
+                literal="Ft.prefix",
+                kind="output_reference_path",
+                script_hash=script_hash,
+                fact_ids=["reference:prefix"],
+            ),
+        ],
+    )
+
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+    result = replay_runtime_binding(rendered)
+
+    assert result["contract_passed"] is True
+    assert {item["runtime_path"] for item in result["outputs"]} == {
+        "output.prefix.a",
+        "output.prefix.b",
+    }
+
+
+def test_patched_input_path_covers_an_implicit_sidecar_output(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Sample.input.fa", "value\n")
+    script = (
+        "indexer() { cp \"$1\" \"$1.idx\"; }\n"
+        "indexer Ft.input.fa\n"
+    )
+    script_hash = _sha256_bytes(script.encode())
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        original_input="Ft.input.fa",
+        output_bindings=[
+            {
+                "fact_id": "output:index",
+                "original_path": "Ft.input.fa.idx",
+                "runtime_path": "Sample.input.fa.idx",
+                "transformed": True,
+            }
+        ],
+        patch_targets=[
+            _target(
+                binding_key="path:Ft.input.fa",
+                literal="Ft.input.fa",
+                kind="input_path",
+                script_hash=script_hash,
+                fact_ids=["input:1"],
+            )
+        ],
+    )
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+    result = replay_runtime_binding(rendered)
+    assert result["contract_passed"] is True
+    assert (tmp_path / "run/work/Sample.input.fa.idx").is_file()
+
+
+def test_direct_output_patch_takes_priority_over_input_root_coverage(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Runtime.input", "value\n")
+    script = "cp Ft.input Ft.input.id\n"
+    script_hash = _sha256_bytes(script.encode())
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        original_input="Ft.input",
+        output_bindings=[
+            {
+                "fact_id": "output:id",
+                "original_path": "Ft.input.id",
+                "runtime_path": "Runtime.input.id",
+                "transformed": True,
+            }
+        ],
+        patch_targets=[
+            _target(
+                binding_key="path:Ft.input",
+                literal="Ft.input",
+                kind="input_path",
+                script_hash=script_hash,
+                fact_ids=["input:1"],
+            ),
+            _target(
+                binding_key="path:Ft.input.id",
+                literal="Ft.input.id",
+                kind="output_path",
+                script_hash=script_hash,
+                fact_ids=["output:id"],
+            ),
+        ],
+    )
+
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+    result = replay_runtime_binding(rendered)
+
+    assert result["contract_passed"] is True
+    assert (tmp_path / "run/work/output.id").read_text(
+        encoding="utf-8"
+    ) == "value\n"
+    assert {item["binding_key"] for item in rendered["patch_diff"]} == {
+        "path:Ft.input",
+        "path:Ft.input.id",
+    }
+
+
+def test_unrelated_implicit_output_remains_blocked(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Sample.input.fa", "value\n")
+    script = (
+        "maker() { cp \"$1\" \"${1%%.*}.report\"; }\n"
+        "maker Ft.input.fa\n"
+    )
+    script_hash = _sha256_bytes(script.encode())
+    contract, _resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        original_input="Ft.input.fa",
+        output_bindings=[
+            {
+                "fact_id": "output:report",
+                "original_path": "Ft.report",
+                "runtime_path": "Sample.report",
+                "transformed": True,
+            }
+        ],
+        patch_targets=[
+            _target(
+                binding_key="path:Ft.input.fa",
+                literal="Ft.input.fa",
+                kind="input_path",
+                script_hash=script_hash,
+                fact_ids=["input:1"],
+            )
+        ],
+    )
+    resolved = resolve_runtime_bindings(contract, {"input:1": runtime_input}, {})
+    assert resolved["status"] == "resolved"
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(contract, raw_code, resolved, tmp_path / "run")
+
+    assert caught.value.code == "PATCH_TARGET_UNAVAILABLE"
+
+
+def test_unpatchable_path_reference_reuses_same_literal_output_patch(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Sample.input.txt", "value\n")
+    script = (
+        "cp Ft.input.txt Ft.result.txt\n"
+        "test -s Ft.result.txt\n"
+    )
+    script_hash = _sha256_bytes(script.encode())
+    reference = {
+        "fact_id": "reference:result",
+        "step_id": "step_001",
+        "kind": "positional",
+        "flag": None,
+        "path": "Ft.result.txt",
+        "value": "Ft.result.txt",
+        "value_role": "output_reference",
+    }
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        path_references=[reference],
+        output_bindings=[
+            {
+                "fact_id": "output:result",
+                "original_path": "Ft.result.txt",
+                "runtime_path": "Sample.result.txt",
+                "transformed": True,
+            }
+        ],
+        patch_targets=[
+            _target(
+                binding_key="path:Ft.input.txt",
+                literal="Ft.input.txt",
+                kind="input_path",
+                script_hash=script_hash,
+                fact_ids=["input:1"],
+            ),
+            _target(
+                binding_key="path:Ft.result.txt",
+                literal="Ft.result.txt",
+                kind="output_path",
+                script_hash=script_hash,
+                count=2,
+                fact_ids=["output:result"],
+            ),
+        ],
+        unpatchable_targets=[
+            {
+                "binding_key": "path_reference:reference:result",
+                "fact_ids": ["reference:result"],
+                "anchors": [],
+                "original_literal": "Ft.result.txt",
+                "patch_kind": "output_reference_path",
+                "reason": "source_literal_ambiguous",
+            }
+        ],
+    )
+
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+    result = replay_runtime_binding(rendered)
+
+    assert result["contract_passed"] is True
+    output_patch = next(
+        item
+        for item in rendered["patch_diff"]
+        if item["binding_key"] == "path:Ft.result.txt"
+    )
+    assert output_patch["covered_binding_keys"] == [
+        "path_reference:reference:result"
+    ]
+    assert output_patch["covered_fact_ids"] == ["reference:result"]
+
+
+def test_same_literal_alias_with_different_replacement_fails_closed(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Sample.input.txt", "value\n")
+    script = (
+        "cp Ft.input.txt Ft.result.txt\n"
+        "test -s Ft.result.txt\n"
+    )
+    script_hash = _sha256_bytes(script.encode())
+    parameter = {
+        "fact_id": "parameter:conflict",
+        "kind": "positional",
+        "flag": None,
+        "original_value": "Ft.result.txt",
+        "runtime_value": "Other.result.txt",
+        "changed": True,
+    }
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script=script,
+        path_references=[
+            {
+                "fact_id": "reference:result",
+                "step_id": "step_001",
+                "kind": "positional",
+                "flag": None,
+                "path": "Ft.result.txt",
+                "value": "Ft.result.txt",
+                "value_role": "output_reference",
+            }
+        ],
+        parameter_bindings=[parameter],
+        output_bindings=[
+            {
+                "fact_id": "output:result",
+                "original_path": "Ft.result.txt",
+                "runtime_path": "Sample.result.txt",
+                "transformed": True,
+            }
+        ],
+        patch_targets=[
+            _target(
+                binding_key="path:Ft.input.txt",
+                literal="Ft.input.txt",
+                kind="input_path",
+                script_hash=script_hash,
+                fact_ids=["input:1"],
+            ),
+            _target(
+                binding_key="path:Ft.result.txt",
+                literal="Ft.result.txt",
+                kind="output_path",
+                script_hash=script_hash,
+                count=2,
+                fact_ids=["output:result"],
+            ),
+            _target(
+                binding_key="parameter:parameter:conflict",
+                literal="Ft.result.txt",
+                kind="parameter_value",
+                script_hash=script_hash,
+                count=2,
+                fact_ids=["parameter:conflict"],
+            ),
+        ],
+        unpatchable_targets=[
+            {
+                "binding_key": "path_reference:reference:result",
+                "fact_ids": ["reference:result"],
+                "anchors": [],
+                "original_literal": "Ft.result.txt",
+                "patch_kind": "output_reference_path",
+                "reason": "source_literal_ambiguous",
+            }
+        ],
+    )
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        render_runtime_package(contract, raw_code, resolved, tmp_path / "run")
+
+    assert caught.value.code == "PATCH_REPLACEMENT_CONFLICT"
+
+
+def test_replay_rejects_an_extra_glob_visible_work_file(tmp_path: Path) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Ft.input.txt", "a\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="cat *.txt\n",
+        stdout=True,
+    )
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+    (tmp_path / "run/work/undeclared.txt").write_text(
+        "must not become input\n", encoding="utf-8"
+    )
+
+    with pytest.raises(RuntimeBindingError) as caught:
+        replay_runtime_binding(rendered)
+
+    assert caught.value.code == "WORK_TREE_CHANGED"
+
+
+def test_replay_isolates_symlink_input_before_source_overwrite(
+    tmp_path: Path,
+) -> None:
+    raw_code = tmp_path / "raw_code"
+    runtime_input = _write(tmp_path, "runtime/Ft.input.txt", "external\n")
+    contract, resolved = _contract_and_resolved(
+        raw_code,
+        runtime_input,
+        script="printf 'job-only\\n' > Ft.input.txt\ncat Ft.input.txt\n",
+        stdout=True,
+    )
+    rendered = render_runtime_package(
+        contract, raw_code, resolved, tmp_path / "run"
+    )
+    assert (tmp_path / "run/work/Ft.input.txt").is_symlink()
+
+    result = replay_runtime_binding(rendered)
+
+    materialized = tmp_path / "run/work/Ft.input.txt"
+    assert result["contract_passed"] is True
+    assert runtime_input.read_text(encoding="utf-8") == "external\n"
+    assert materialized.is_file() and not materialized.is_symlink()
+    assert materialized.read_text(encoding="utf-8") == "job-only\n"
+    assert result["execution_inputs"] == [
+        {
+            "materialized_path": "Ft.input.txt",
+            "mode": "isolated_copy",
+            "source_path": str(runtime_input.resolve()),
+        }
+    ]
+    assert result["execution_work_tree"]["Ft.input.txt"]["type"] == "regular"
diff --git a/tests/unit/test_extension_stage_lightweight_semantic_model.py b/tests/unit/test_extension_stage_lightweight_semantic_model.py
new file mode 100644
index 000000000..2c431aaef
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_semantic_model.py
@@ -0,0 +1,472 @@
+from __future__ import annotations
+
+from copy import deepcopy
+import importlib
+from pathlib import Path
+
+import pytest
+
+from gfa_core.extension_stage_lightweight.converter import build_execution_facts
+from gfa_core.extension_stage_lightweight.evidence import run_raw_baseline
+
+
+def _write(root: Path, relative: str, content: str) -> Path:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def _semantic_model():
+    return importlib.import_module("gfa_core.extension_stage_lightweight.semantic_model")
+
+
+def _facts(tmp_path: Path) -> dict:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(raw_code, "run.sh", "cp input.fa result.txt\n")
+    _write(raw_data, "input.fa", ">a\nAAAA\n")
+    evidence = run_raw_baseline(
+        command="bash run.sh",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+    return build_execution_facts(evidence)
+
+
+def _facts_with_generated_input(tmp_path: Path) -> dict:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(
+        raw_code,
+        "run.sh",
+        "cp input.fa intermediate.fa\ncp intermediate.fa result.fa\n",
+    )
+    _write(raw_data, "input.fa", ">a\nAAAA\n")
+    evidence = run_raw_baseline(
+        command="bash run.sh",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+    return build_execution_facts(evidence)
+
+
+def _candidate(facts: dict) -> dict:
+    command = facts["commands"][0]
+    return {
+        "facts_sha256": facts["facts_sha256"],
+        "function_summary": "Copy an uploaded FASTA file to a result file.",
+        "inputs": [
+            {
+                "fact_id": command["inputs"][0]["fact_id"],
+                "role": "input_sequences",
+                "description": "Uploaded FASTA sequences.",
+                "replaceability": "replaceable",
+            }
+        ],
+        "parameters": [
+            {
+                "fact_id": command["parameters"][0]["fact_id"],
+                "display_name": "result file",
+                "description": "Output filename from the original command.",
+            }
+        ],
+        "outputs": [
+            {
+                "fact_id": facts["outputs"]["files"][0]["fact_id"],
+                "description": "Copied FASTA result.",
+                "result_role": "final",
+            }
+        ],
+    }
+
+
+def test_valid_candidate_references_only_locked_fact_ids(tmp_path: Path) -> None:
+    model = _semantic_model()
+    facts = _facts(tmp_path)
+    candidate = _candidate(facts)
+
+    assert model.validate_semantic_candidate(facts, candidate) == []
+    merged = model.merge_semantics(facts, candidate)
+
+    assert merged == {
+        "execution_facts": facts,
+        "semantics": candidate,
+    }
+    assert merged["execution_facts"] is not facts
+    assert merged["semantics"] is not candidate
+
+
+def test_candidate_rejects_fact_digest_mismatch(tmp_path: Path) -> None:
+    model = _semantic_model()
+    facts = _facts(tmp_path)
+    candidate = _candidate(facts)
+    candidate["facts_sha256"] = "0" * 64
+
+    errors = model.validate_semantic_candidate(facts, candidate)
+
+    assert any(
+        error["field"] == "facts_sha256" and error["code"] == "facts_mismatch"
+        for error in errors
+    )
+
+
+def test_candidate_rejects_missing_duplicate_and_unknown_fact_ids(
+    tmp_path: Path,
+) -> None:
+    model = _semantic_model()
+    facts = _facts(tmp_path)
+    candidate = _candidate(facts)
+    input_id = candidate["inputs"][0]["fact_id"]
+    parameter_id = candidate["parameters"][0]["fact_id"]
+    candidate["inputs"].append(deepcopy(candidate["inputs"][0]))
+    candidate["parameters"] = []
+    candidate["outputs"][0]["fact_id"] = "output:file:999"
+
+    errors = model.validate_semantic_candidate(facts, candidate)
+
+    assert any(
+        error["code"] == "duplicate_fact_id" and input_id in error["message"]
+        for error in errors
+    )
+    assert any(
+        error["code"] == "missing_fact_id" and parameter_id in error["message"]
+        for error in errors
+    )
+    assert any(
+        error["code"] == "unknown_fact_id" and "output:file:999" in error["message"]
+        for error in errors
+    )
+
+
+def test_candidate_rejects_fields_that_could_rewrite_facts(tmp_path: Path) -> None:
+    model = _semantic_model()
+    facts = _facts(tmp_path)
+    candidate = _candidate(facts)
+    candidate["original_command"] = "rm -rf result.txt"
+    candidate["inputs"][0]["path"] = "invented.fa"
+    candidate["parameters"][0]["flag"] = "--invented"
+    candidate["outputs"][0]["path"] = "invented.out"
+
+    errors = model.validate_semantic_candidate(facts, candidate)
+    fields = {error["field"] for error in errors if error["code"] == "unknown_field"}
+
+    assert fields == {
+        "original_command",
+        "inputs[0].path",
+        "parameters[0].flag",
+        "outputs[0].path",
+    }
+    with pytest.raises(model.SemanticCandidateError) as raised:
+        model.merge_semantics(facts, candidate)
+    assert raised.value.errors == errors
+
+
+def test_semantic_revision_does_not_mutate_execution_facts(tmp_path: Path) -> None:
+    model = _semantic_model()
+    facts = _facts(tmp_path)
+    original_facts = deepcopy(facts)
+    candidate = _candidate(facts)
+    revised = deepcopy(candidate)
+    revised["inputs"][0]["description"] = "A user-selected sequence file."
+    revised["inputs"][0]["replaceability"] = "fixed_resource"
+    revised["outputs"][0]["result_role"] = "intermediate"
+
+    merged = model.merge_semantics(facts, revised)
+
+    assert facts == original_facts
+    assert merged["execution_facts"] == original_facts
+    assert merged["execution_facts"]["facts_sha256"] == facts["facts_sha256"]
+    assert merged["semantics"] == revised
+
+
+@pytest.mark.parametrize(
+    ("section", "field", "bad_value"),
+    [
+        ("inputs", "replaceability", "sometimes"),
+        ("outputs", "result_role", "pretty"),
+    ],
+)
+def test_candidate_rejects_unknown_semantic_enum_values(
+    tmp_path: Path,
+    section: str,
+    field: str,
+    bad_value: str,
+) -> None:
+    model = _semantic_model()
+    facts = _facts(tmp_path)
+    candidate = _candidate(facts)
+    candidate[section][0][field] = bad_value
+
+    errors = model.validate_semantic_candidate(facts, candidate)
+
+    assert any(error["code"] == "invalid_value" for error in errors)
+
+
+def test_candidate_accepts_generated_for_step_output_reused_as_input(
+    tmp_path: Path,
+) -> None:
+    model = _semantic_model()
+    facts = _facts_with_generated_input(tmp_path)
+    inputs = []
+    parameters = []
+    for command in facts["commands"]:
+        for item in command["inputs"]:
+            inputs.append(
+                {
+                    "fact_id": item["fact_id"],
+                    "role": "sequence file",
+                    "description": "Sequence data consumed by this step.",
+                    "replaceability": (
+                        "generated"
+                        if item["source"] == "generated_input"
+                        else "replaceable"
+                    ),
+                }
+            )
+        for item in command["parameters"]:
+            parameters.append(
+                {
+                    "fact_id": item["fact_id"],
+                    "display_name": "output filename",
+                    "description": "Output filename fixed by the original command.",
+                }
+            )
+    candidate = {
+        "facts_sha256": facts["facts_sha256"],
+        "function_summary": "Copy a sequence file through an intermediate file.",
+        "inputs": inputs,
+        "parameters": parameters,
+        "outputs": [
+            {
+                "fact_id": item["fact_id"],
+                "description": "Observed file produced by the command.",
+                "result_role": "final",
+            }
+            for item in facts["outputs"]["files"]
+        ],
+    }
+
+    assert any(item["replaceability"] == "generated" for item in inputs)
+    assert model.validate_semantic_candidate(facts, candidate) == []
+
+
+def test_candidate_rejects_replaceability_that_conflicts_with_input_source(
+    tmp_path: Path,
+) -> None:
+    model = _semantic_model()
+    facts = _facts_with_generated_input(tmp_path)
+    inputs = []
+    parameters = []
+    sources = {}
+    for command in facts["commands"]:
+        for item in command["inputs"]:
+            sources[item["fact_id"]] = item["source"]
+            inputs.append(
+                {
+                    "fact_id": item["fact_id"],
+                    "role": "sequence file",
+                    "description": "Sequence data consumed by this step.",
+                    "replaceability": (
+                        "generated"
+                        if item["source"] == "generated_input"
+                        else "replaceable"
+                    ),
+                }
+            )
+        for item in command["parameters"]:
+            parameters.append(
+                {
+                    "fact_id": item["fact_id"],
+                    "display_name": "output filename",
+                    "description": "Output filename fixed by the original command.",
+                }
+            )
+    candidate = {
+        "facts_sha256": facts["facts_sha256"],
+        "function_summary": "Copy a sequence file through an intermediate file.",
+        "inputs": inputs,
+        "parameters": parameters,
+        "outputs": [
+            {
+                "fact_id": item["fact_id"],
+                "description": "Observed file produced by the command.",
+                "result_role": "final",
+            }
+            for item in facts["outputs"]["files"]
+        ],
+    }
+
+    generated_index = next(
+        index
+        for index, item in enumerate(candidate["inputs"])
+        if sources[item["fact_id"]] == "generated_input"
+    )
+    external_index = next(
+        index
+        for index, item in enumerate(candidate["inputs"])
+        if sources[item["fact_id"]] != "generated_input"
+    )
+    candidate["inputs"][generated_index]["replaceability"] = "replaceable"
+    candidate["inputs"][external_index]["replaceability"] = "generated"
+
+    errors = model.validate_semantic_candidate(facts, candidate)
+
+    assert {
+        error["field"]
+        for error in errors
+        if error["code"] == "input_source_mismatch"
+    } == {
+        f"inputs[{generated_index}].replaceability",
+        f"inputs[{external_index}].replaceability",
+    }
+
+
+def test_system_binding_makes_invalid_model_references_repairable(
+    tmp_path: Path,
+) -> None:
+    model = _semantic_model()
+    facts = _facts_with_generated_input(tmp_path)
+    inputs = []
+    parameters = []
+    for command in facts["commands"]:
+        for item in command["inputs"]:
+            inputs.append(
+                {
+                    "fact_id": item["fact_id"],
+                    "role": "sequence file",
+                    "description": "Sequence data consumed by this step.",
+                    "replaceability": "replaceable",
+                }
+            )
+        for item in command["parameters"]:
+            parameters.append(
+                {
+                    "fact_id": item["fact_id"],
+                    "display_name": "output filename",
+                    "description": "Output filename fixed by the original command.",
+                }
+            )
+    candidate = {
+        "facts_sha256": facts["facts_sha256"],
+        "function_summary": "Copy a sequence file through an intermediate file.",
+        "inputs": inputs + [deepcopy(inputs[0])],
+        "parameters": parameters,
+        "outputs": [
+            {
+                "fact_id": "step_001:parameter:002",
+                "description": "Wrongly referenced output.",
+                "result_role": "final",
+            }
+        ],
+    }
+
+    bound, audit = model.bind_fact_derived_semantics(facts, candidate)
+
+    generated_ids = {
+        item["fact_id"]
+        for command in facts["commands"]
+        for item in command["inputs"]
+        if item["source"] == "generated_input"
+    }
+    assert all(
+        item["replaceability"] == "generated"
+        for item in bound["inputs"]
+        if item["fact_id"] in generated_ids
+    )
+    assert len(bound["inputs"]) == len(inputs)
+    assert bound["outputs"] == []
+    assert {item["action"] for item in audit} == {
+        "bind_generated_input",
+        "discard_duplicate_reference",
+        "discard_unknown_reference",
+    }
+    errors = model.validate_semantic_candidate(facts, bound)
+    assert all(error["code"] == "missing_fact_id" for error in errors)
+
+
+def test_system_binding_completes_omitted_locked_fact_rows(tmp_path: Path) -> None:
+    model = _semantic_model()
+    facts = _facts_with_generated_input(tmp_path)
+    input_fact = facts["commands"][1]["inputs"][0]
+    parameter_fact = facts["commands"][1]["parameters"][0]
+    output_fact = facts["outputs"]["files"][1]
+    candidate = {
+        "facts_sha256": facts["facts_sha256"],
+        "function_summary": "A valid model-provided summary.",
+        "inputs": [
+            {
+                "fact_id": facts["commands"][0]["inputs"][0]["fact_id"],
+                "role": "model-provided input role",
+                "description": "Model-provided input description.",
+                "replaceability": "fixed_resource",
+            }
+        ],
+        "parameters": [
+            {
+                "fact_id": facts["commands"][0]["parameters"][0]["fact_id"],
+                "display_name": "Model-provided parameter name",
+                "description": "Model-provided parameter description.",
+            }
+        ],
+        "outputs": [
+            {
+                "fact_id": facts["outputs"]["files"][0]["fact_id"],
+                "description": "Model-provided output description.",
+                "result_role": "final",
+            }
+        ],
+    }
+    provided_rows = {
+        section: deepcopy(candidate[section])
+        for section in ("inputs", "parameters", "outputs")
+    }
+    original_candidate = deepcopy(candidate)
+
+    bound, audit = model.bind_fact_derived_semantics(facts, candidate)
+
+    assert candidate == original_candidate
+    assert bound["inputs"] == provided_rows["inputs"] + [
+        {
+            "fact_id": input_fact["fact_id"],
+            "role": f"Locked input: {input_fact['path']}.",
+            "description": f"Observed input file: {input_fact['path']}.",
+            "replaceability": "generated",
+        },
+    ]
+    assert bound["parameters"] == provided_rows["parameters"] + [
+        {
+            "fact_id": parameter_fact["fact_id"],
+            "display_name": f"Locked parameter: {parameter_fact['value']}.",
+            "description": (
+                f"Observed command parameter: {parameter_fact['value']}."
+            ),
+        }
+    ]
+    assert bound["outputs"] == provided_rows["outputs"] + [
+        {
+            "fact_id": output_fact["fact_id"],
+            "description": f"Observed output file: {output_fact['path']}.",
+            "result_role": "unknown",
+        }
+    ]
+    assert audit == [
+        {
+            "action": "complete_missing_semantic_row",
+            "section": "inputs",
+            "fact_id": input_fact["fact_id"],
+        },
+        {
+            "action": "complete_missing_semantic_row",
+            "section": "parameters",
+            "fact_id": parameter_fact["fact_id"],
+        },
+        {
+            "action": "complete_missing_semantic_row",
+            "section": "outputs",
+            "fact_id": output_fact["fact_id"],
+        },
+    ]
+    assert model.validate_semantic_candidate(facts, bound) == []
diff --git a/tests/unit/test_extension_stage_lightweight_semantic_repair.py b/tests/unit/test_extension_stage_lightweight_semantic_repair.py
new file mode 100644
index 000000000..c2428b6e1
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_semantic_repair.py
@@ -0,0 +1,477 @@
+from __future__ import annotations
+
+from copy import deepcopy
+import importlib
+import json
+from pathlib import Path
+from types import SimpleNamespace
+
+from gfa_core.extension_stage_lightweight.converter import build_execution_facts
+from gfa_core.extension_stage_lightweight.evidence import run_raw_baseline
+from gfa_core.extension_stage_lightweight.semantic_model import (
+    validate_semantic_candidate,
+)
+
+
+def _module():
+    return importlib.import_module(
+        "gfa_core.extension_stage_lightweight.semantic_repair"
+    )
+
+
+def _write(root: Path, relative: str, content: str) -> Path:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def _facts(tmp_path: Path) -> dict:
+    raw_code = tmp_path / "raw_code"
+    raw_data = tmp_path / "raw_test_data"
+    _write(raw_code, "run.sh", "cp model.hmm result.txt\n")
+    _write(raw_data, "model.hmm", "HMMER3/f\n")
+    evidence = run_raw_baseline(
+        command="bash run.sh",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        run_dir=tmp_path / "baseline",
+    )
+    return build_execution_facts(evidence)
+
+
+def _candidate(facts: dict) -> dict:
+    command = facts["commands"][0]
+    return {
+        "facts_sha256": facts["facts_sha256"],
+        "function_summary": "Copy an HMM model to an observed result file.",
+        "inputs": [
+            {
+                "fact_id": command["inputs"][0]["fact_id"],
+                "role": "hmm_model",
+                "description": "Uploaded HMM model.",
+                "replaceability": "replaceable",
+            }
+        ],
+        "parameters": [
+            {
+                "fact_id": command["parameters"][0]["fact_id"],
+                "display_name": "result file",
+                "description": "Output filename from the original command.",
+            }
+        ],
+        "outputs": [
+            {
+                "fact_id": facts["outputs"]["files"][0]["fact_id"],
+                "description": "Observed copied result.",
+                "result_role": "final",
+            }
+        ],
+    }
+
+
+def _patch(facts: dict, *, section: str, fact_id: str, fields: dict) -> dict:
+    return {
+        "facts_sha256": facts["facts_sha256"],
+        "changes": [
+            {
+                "section": section,
+                "fact_id": fact_id,
+                "fields": fields,
+            }
+        ],
+    }
+
+
+def test_automatic_repair_binds_generated_input_from_locked_facts() -> None:
+    module = _module()
+    facts = {
+        "facts_sha256": "a" * 64,
+        "commands": [
+            {
+                "inputs": [
+                    {"fact_id": "step_001:input:001", "source": "baseline_input"}
+                ],
+                "parameters": [],
+            },
+            {
+                "inputs": [
+                    {"fact_id": "step_002:input:001", "source": "generated_input"}
+                ],
+                "parameters": [],
+            },
+        ],
+        "outputs": {
+            "files": [{"fact_id": "output:file:001"}],
+            "stdout": {"present": False},
+        },
+    }
+    candidate = {
+        "facts_sha256": facts["facts_sha256"],
+        "function_summary": "Process an uploaded sequence through two steps.",
+        "inputs": [
+            {
+                "fact_id": "step_001:input:001",
+                "role": "uploaded sequence",
+                "description": "User-provided sequence file.",
+                "replaceability": "replaceable",
+            }
+        ],
+        "parameters": [],
+        "outputs": [
+            {
+                "fact_id": "output:file:001",
+                "description": "Final processed sequence.",
+                "result_role": "final",
+            }
+        ],
+    }
+
+    def generator(context: dict, attempt: int):
+        return (
+            _patch(
+                facts,
+                section="inputs",
+                fact_id="step_002:input:001",
+                fields={
+                    "role": "intermediate sequence",
+                    "description": "Sequence generated by the previous step.",
+                    "replaceability": "replaceable",
+                },
+            ),
+            {"request_id": "repair-generated"},
+        )
+
+    repaired, history = module.repair_semantic_candidate(
+        execution_facts=facts,
+        candidate=candidate,
+        validation_errors=validate_semantic_candidate(facts, candidate),
+        patch_generator=generator,
+    )
+
+    assert repaired["inputs"][1]["replaceability"] == "generated"
+    assert history[0]["status"] == "success"
+    assert history[0]["metadata"]["fact_derived_semantic_bindings"][0][
+        "action"
+    ] == "bind_generated_input"
+
+
+def test_automatic_repair_changes_only_the_failed_field(tmp_path: Path) -> None:
+    module = _module()
+    facts = _facts(tmp_path)
+    candidate = _candidate(facts)
+    parameter_id = candidate["parameters"][0]["fact_id"]
+    candidate["parameters"][0].pop("description")
+    before = deepcopy(candidate)
+    errors = validate_semantic_candidate(facts, candidate)
+    seen_contexts: list[dict] = []
+
+    def generator(context: dict, attempt: int):
+        seen_contexts.append(context)
+        return (
+            _patch(
+                facts,
+                section="parameters",
+                fact_id=parameter_id,
+                fields={"description": "Output filename from the original command."},
+            ),
+            {"request_id": "repair-1"},
+        )
+
+    repaired, history = module.repair_semantic_candidate(
+        execution_facts=facts,
+        candidate=candidate,
+        validation_errors=errors,
+        patch_generator=generator,
+    )
+
+    assert candidate == before
+    assert repaired["parameters"][0]["description"].startswith("Output filename")
+    unchanged = deepcopy(repaired)
+    unchanged["parameters"][0].pop("description")
+    assert unchanged == before
+    assert seen_contexts[0]["allowed_targets"] == [
+        {
+            "section": "parameters",
+            "fact_id": parameter_id,
+            "field": "description",
+        }
+    ]
+    assert history == [
+        {
+            "attempt": 1,
+            "mode": "automatic",
+            "status": "success",
+            "diff": [
+                {
+                    "section": "parameters",
+                    "fact_id": parameter_id,
+                    "field": "description",
+                    "before": None,
+                    "after": "Output filename from the original command.",
+                }
+            ],
+            "metadata": {"request_id": "repair-1"},
+            "errors": [],
+        }
+    ]
+
+
+def test_user_feedback_repairs_semantics_and_records_exact_diff(
+    tmp_path: Path,
+) -> None:
+    module = _module()
+    facts = _facts(tmp_path)
+    original_facts = deepcopy(facts)
+    candidate = _candidate(facts)
+    original_candidate = deepcopy(candidate)
+    input_id = candidate["inputs"][0]["fact_id"]
+
+    def generator(context: dict, attempt: int):
+        assert context["user_feedback"] == "HMM 文件是固定资源，不是每次替换的输入"
+        return (
+            _patch(
+                facts,
+                section="inputs",
+                fact_id=input_id,
+                fields={
+                    "description": "Bundled HMM model used by this analysis.",
+                    "replaceability": "fixed_resource",
+                },
+            ),
+            {},
+        )
+
+    repaired, history = module.repair_semantic_candidate(
+        execution_facts=facts,
+        candidate=candidate,
+        user_feedback="HMM 文件是固定资源，不是每次替换的输入",
+        patch_generator=generator,
+    )
+
+    assert facts == original_facts
+    assert candidate == original_candidate
+    assert repaired["inputs"][0]["replaceability"] == "fixed_resource"
+    assert repaired["parameters"] == original_candidate["parameters"]
+    assert repaired["outputs"] == original_candidate["outputs"]
+    assert {item["field"] for item in history[0]["diff"]} == {
+        "description",
+        "replaceability",
+    }
+    assert history[0]["mode"] == "user_feedback"
+
+
+def test_automatic_repair_rejects_unrelated_semantic_changes(
+    tmp_path: Path,
+) -> None:
+    module = _module()
+    facts = _facts(tmp_path)
+    candidate = _candidate(facts)
+    parameter_id = candidate["parameters"][0]["fact_id"]
+    input_id = candidate["inputs"][0]["fact_id"]
+    candidate["parameters"][0].pop("description")
+    original = deepcopy(candidate)
+
+    def generator(context: dict, attempt: int):
+        return (
+            {
+                "facts_sha256": facts["facts_sha256"],
+                "changes": [
+                    {
+                        "section": "parameters",
+                        "fact_id": parameter_id,
+                        "fields": {"description": "Correct repair."},
+                    },
+                    {
+                        "section": "inputs",
+                        "fact_id": input_id,
+                        "fields": {"description": "Unrequested rewrite."},
+                    },
+                ],
+            },
+            {},
+        )
+
+    repaired, history = module.repair_semantic_candidate(
+        execution_facts=facts,
+        candidate=candidate,
+        validation_errors=validate_semantic_candidate(facts, candidate),
+        patch_generator=generator,
+        max_attempts=1,
+    )
+
+    assert repaired == original
+    assert history[-1]["status"] == "needs_user_confirmation"
+    assert any("not allowed" in error["message"] for error in history[-1]["errors"])
+
+
+def test_repair_rejects_fact_rewrites_and_unknown_ids(tmp_path: Path) -> None:
+    module = _module()
+    facts = _facts(tmp_path)
+    candidate = _candidate(facts)
+    original = deepcopy(candidate)
+
+    invalid_patches = [
+        {
+            "facts_sha256": facts["facts_sha256"],
+            "original_command": "invented command",
+            "changes": [],
+        },
+        _patch(
+            facts,
+            section="inputs",
+            fact_id="step_999:input:999",
+            fields={"description": "Invented input."},
+        ),
+        _patch(
+            facts,
+            section="inputs",
+            fact_id=candidate["inputs"][0]["fact_id"],
+            fields={"path": "invented.fa", "flag": "--invented"},
+        ),
+    ]
+
+    for invalid in invalid_patches:
+        repaired, history = module.repair_semantic_candidate(
+            execution_facts=facts,
+            candidate=candidate,
+            user_feedback="revise this",
+            patch_generator=lambda context, attempt, patch=invalid: (patch, {}),
+            max_attempts=1,
+        )
+        assert repaired == original
+        assert history[-1]["status"] == "needs_user_confirmation"
+        assert history[-1]["errors"]
+
+
+def test_repair_stops_after_twenty_invalid_attempts(tmp_path: Path) -> None:
+    module = _module()
+    facts = _facts(tmp_path)
+    candidate = _candidate(facts)
+    calls: list[int] = []
+
+    def generator(context: dict, attempt: int):
+        calls.append(attempt)
+        return ({"facts_sha256": "wrong", "changes": []}, {})
+
+    repaired, history = module.repair_semantic_candidate(
+        execution_facts=facts,
+        candidate=candidate,
+        user_feedback="revise this",
+        patch_generator=generator,
+        max_attempts=100,
+    )
+
+    assert repaired == candidate
+    assert calls == list(range(1, 21))
+    assert len(history) == 20
+    assert history[-1]["status"] == "needs_user_confirmation"
+    assert history[-1]["errors"]
+
+
+def test_default_deepseek_generator_requests_only_an_allowed_patch(
+    tmp_path: Path,
+) -> None:
+    module = _module()
+    facts = _facts(tmp_path)
+    candidate = _candidate(facts)
+    parameter_id = candidate["parameters"][0]["fact_id"]
+    candidate["parameters"][0].pop("description")
+    patch = _patch(
+        facts,
+        section="parameters",
+        fact_id=parameter_id,
+        fields={"description": "Output filename from the original command."},
+    )
+    api_patch = deepcopy(patch)
+    api_patch.pop("facts_sha256")
+    requests: list[dict] = []
+
+    class FakeCompletions:
+        def create(self, **kwargs):
+            requests.append(kwargs)
+            return SimpleNamespace(
+                id="repair-request-1",
+                choices=[
+                    SimpleNamespace(
+                        message=SimpleNamespace(content=json.dumps(api_patch))
+                    )
+                ],
+                usage=SimpleNamespace(
+                    prompt_tokens=30,
+                    completion_tokens=20,
+                    total_tokens=50,
+                ),
+            )
+
+    fake_client = SimpleNamespace(
+        chat=SimpleNamespace(completions=FakeCompletions())
+    )
+    env_file = _write(
+        tmp_path,
+        ".env",
+        "NEW_API_KEY=secret-test-key\n"
+        "NEW_API_BASE_URL=https://api.example.test/v1\n"
+        "NEW_API_MODEL=deepseek-test\n",
+    )
+
+    repaired, history = module.repair_semantic_candidate(
+        execution_facts=facts,
+        candidate=candidate,
+        validation_errors=validate_semantic_candidate(facts, candidate),
+        raw_code=tmp_path / "raw_code",
+        environ={"BBAV5_PROJECT_ENV_FILE": str(env_file)},
+        client_factory=lambda config: fake_client,
+    )
+
+    assert repaired["parameters"][0]["description"].startswith("Output filename")
+    request = requests[0]
+    assert request["temperature"] == 0
+    assert request["max_tokens"] == 6000
+    assert "Return only a semantic patch" in request["messages"][0]["content"]
+    payload = json.loads(request["messages"][1]["content"])
+    assert "facts_sha256" not in payload["required_patch_shape"]
+    assert payload["allowed_targets"] == [
+        {
+            "section": "parameters",
+            "fact_id": parameter_id,
+            "field": "description",
+        }
+    ]
+    assert payload["execution_facts"] == facts
+    assert payload["candidate"] == candidate
+    assert "secret-test-key" not in json.dumps(request)
+    assert history[0]["metadata"]["request_id"] == "repair-request-1"
+
+
+def test_deepseek_repair_error_keeps_auditable_raw_response(tmp_path: Path) -> None:
+    module = _module()
+    facts = _facts(tmp_path)
+    candidate = _candidate(facts)
+    candidate["parameters"][0].pop("description")
+
+    class FakeCompletions:
+        def create(self, **kwargs):
+            return SimpleNamespace(
+                id="invalid-repair-1",
+                choices=[SimpleNamespace(message=SimpleNamespace(content="[]"))],
+                usage=None,
+            )
+
+    env_file = _write(tmp_path, ".env", "NEW_API_KEY=secret-test-key\n")
+    repaired, history = module.repair_semantic_candidate(
+        execution_facts=facts,
+        candidate=candidate,
+        raw_code=tmp_path / "raw_code",
+        environ={"BBAV5_PROJECT_ENV_FILE": str(env_file)},
+        client_factory=lambda config: SimpleNamespace(
+            chat=SimpleNamespace(completions=FakeCompletions())
+        ),
+        max_attempts=1,
+    )
+
+    assert repaired == candidate
+    assert history[0]["status"] == "needs_user_confirmation"
+    assert history[0]["metadata"]["request_id"] == "invalid-repair-1"
+    assert history[0]["metadata"]["raw_response"] == "[]"
+    assert history[0]["errors"][0]["code"] == "invalid_json"
diff --git a/tests/unit/test_extension_stage_lightweight_service.py b/tests/unit/test_extension_stage_lightweight_service.py
new file mode 100644
index 000000000..c351c8513
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_service.py
@@ -0,0 +1,576 @@
+from __future__ import annotations
+
+from pathlib import Path
+import threading
+import time
+
+import pytest
+
+
+def _write(root: Path, relative: str, content: str) -> Path:
+    path = root / relative
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    return path
+
+
+def _semantic_from_facts(facts: dict) -> dict:
+    return {
+        "facts_sha256": facts["facts_sha256"],
+        "function_summary": "Count FASTA records or copy one FASTA file.",
+        "inputs": [
+            {
+                "fact_id": item["fact_id"],
+                "role": "analysis_input",
+                "description": "Input supplied to the original command.",
+                "replaceability": "generated"
+                if item["source"] == "generated_input"
+                else "replaceable",
+            }
+            for command in facts["commands"]
+            for item in command["inputs"]
+        ],
+        "parameters": [
+            {
+                "fact_id": item["fact_id"],
+                "display_name": item["flag"] or "command value",
+                "description": "Original command parameter.",
+            }
+            for command in facts["commands"]
+            for item in command["parameters"]
+        ],
+        "outputs": [
+            {
+                "fact_id": item["fact_id"],
+                "description": "Observed analysis result.",
+                "result_role": "final",
+            }
+            for item in facts["outputs"]["files"]
+        ]
+        + (
+            [
+                {
+                    "fact_id": facts["outputs"]["stdout"]["fact_id"],
+                    "description": "Direct textual result.",
+                    "result_role": "final",
+                }
+            ]
+            if facts["outputs"]["stdout"].get("present")
+            else []
+        ),
+    }
+
+
+def _service(tmp_path: Path):
+    from gfa_core.extension_stage_lightweight.service import LightweightExtensionService
+
+    return LightweightExtensionService(
+        tmp_path / "store",
+        semantic_generator=lambda facts, _raw_code: (_semantic_from_facts(facts), {}),
+    )
+
+
+def _package(tmp_path: Path, *, stdout_only: bool) -> tuple[Path, Path, str]:
+    raw_code = tmp_path / "source" / "raw_code"
+    raw_data = tmp_path / "source" / "raw_test_data"
+    _write(raw_data, "input.fa", ">a\nAAAA\n>b\nBBBB\n")
+    if stdout_only:
+        _write(raw_code, "count.sh", "grep -c '^>' input.fa\n")
+        return raw_code, raw_data, "bash count.sh"
+    _write(raw_code, "copy.sh", "cp input.fa result.fa\n")
+    return raw_code, raw_data, "bash copy.sh"
+
+
+def _published_copy_service(tmp_path: Path):
+    service = _service(tmp_path)
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=False)
+    service.upload(
+        extension_id="copy_fasta",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        original_command=command,
+        operation_token="upload-1",
+    )
+    service.confirm("copy_fasta", operation_token="confirm-1")
+    service.validate("copy_fasta", operation_token="validate-1")
+    service.review_result("copy_fasta", operation_token="review-1")
+    service.publish("copy_fasta", operation_token="publish-1")
+    return service
+
+
+def test_stdout_lifecycle_records_reviewed_validation_and_publishes(tmp_path: Path) -> None:
+    service = _service(tmp_path)
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+
+    created = service.upload(
+        extension_id="count_fasta",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        original_command=command,
+        operation_token="upload-1",
+    )
+    assert created["status"] == "confirmation_pending"
+    assert service.get("count_fasta")["execution_facts"]["original_command"] == command
+
+    service.confirm("count_fasta", operation_token="confirm-1")
+    validation = service.validate("count_fasta", operation_token="validate-1")
+    state = service.get("count_fasta")
+    assert validation["status"] == "result_review_pending"
+    assert state["validation_runs"][0]["contract_passed"] is True
+    assert state["validation_runs"][0]["projection"]["stdout"]["present"] is True
+
+    service.review_result("count_fasta", operation_token="review-1")
+    published = service.publish("count_fasta", operation_token="publish-1")
+    assert published["status"] == "published"
+    assert service.get("count_fasta")["published_validation_run_id"] == validation["run_id"]
+    assert service.help("count_fasta")["original_command"] == command
+
+
+def test_published_run_requires_job_context_and_projects_into_job_workspace(
+    tmp_path: Path,
+) -> None:
+    service = _published_copy_service(tmp_path)
+    input_root = tmp_path / "input"
+    workspace_root = tmp_path / "workspace"
+    runtime_input = _write(input_root, "job_1/different_name.fa", ">x\nTTTT\n")
+    _write(workspace_root, "job_1/.keep", "")
+
+    with pytest.raises(ValueError, match="run_job_id"):
+        service.run(
+            "copy_fasta",
+            input_overrides={"input.fa": runtime_input},
+            operation_token="run-missing-context",
+        )
+    with pytest.raises(ValueError, match="selected job"):
+        service.run(
+            "copy_fasta",
+            input_overrides={"input.fa": _write(tmp_path, "outside.fa", ">z\n")},
+            run_job_id="job_1",
+            input_root=input_root,
+            workspace_root=workspace_root,
+            operation_token="run-outside",
+        )
+
+    result = service.run(
+        "copy_fasta",
+        input_overrides={"input.fa": runtime_input},
+        run_job_id="job_1",
+        input_root=input_root,
+        workspace_root=workspace_root,
+        operation_token="run-1",
+    )
+    runtime = service.get("copy_fasta")["runtime_runs"][-1]
+    output = Path(runtime["projection"]["files"][0]["absolute_path"])
+    assert runtime["success"] is True
+    assert output.read_text(encoding="utf-8") == ">x\nTTTT\n"
+    assert output.is_relative_to(
+        workspace_root / "job_1" / "extension_runs" / "copy_fasta"
+    )
+
+
+def test_published_run_rejects_symlink_escape_from_selected_job(tmp_path: Path) -> None:
+    service = _published_copy_service(tmp_path)
+    input_root = tmp_path / "input"
+    workspace_root = tmp_path / "workspace"
+    outside = _write(input_root, "job_2/secret.fa", ">secret\n")
+    link = input_root / "job_1/link.fa"
+    link.parent.mkdir(parents=True, exist_ok=True)
+    link.symlink_to(outside)
+    _write(workspace_root, "job_1/.keep", "")
+
+    with pytest.raises(ValueError, match="selected job"):
+        service.run(
+            "copy_fasta",
+            input_overrides={"input.fa": link},
+            run_job_id="job_1",
+            input_root=input_root,
+            workspace_root=workspace_root,
+            operation_token="run-symlink-escape",
+        )
+
+
+def test_fact_dispute_requires_rebuild_and_duplicate_token_uses_one_run(
+    tmp_path: Path,
+) -> None:
+    service = _service(tmp_path)
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+    service.upload(
+        extension_id="count_fasta",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        original_command=command,
+        operation_token="upload-1",
+    )
+    disputed = service.revise(
+        "count_fasta",
+        feedback="The original input path is wrong.",
+        revision_target="execution_facts.path",
+        operation_token="revise-1",
+    )
+    assert disputed["status"] == "rebuild_required"
+    with pytest.raises(ValueError, match="rebuild"):
+        service.confirm("count_fasta", operation_token="confirm-1")
+    service.rebuild("count_fasta", operation_token="rebuild-1")
+    service.confirm("count_fasta", operation_token="confirm-2")
+    first = service.validate("count_fasta", operation_token="validate-once")
+    second = service.validate("count_fasta", operation_token="validate-once")
+    assert first == second
+    assert len(service.get("count_fasta")["validation_runs"]) == 1
+
+
+def test_concurrent_same_token_starts_validation_once(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    service = _service(tmp_path)
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+    service.upload(
+        extension_id="count_fasta", raw_code=raw_code, raw_data=raw_data,
+        original_command=command, operation_token="upload-1",
+    )
+    service.confirm("count_fasta", operation_token="confirm-1")
+    real_execute = service._execute
+    entered = threading.Event()
+    release = threading.Event()
+    calls = 0
+
+    def slow_execute(*args, **kwargs):
+        nonlocal calls
+        calls += 1
+        entered.set()
+        assert release.wait(timeout=3)
+        return real_execute(*args, **kwargs)
+
+    monkeypatch.setattr(service, "_execute", slow_execute)
+    results: list[dict] = []
+    first = threading.Thread(
+        target=lambda: results.append(service.validate("count_fasta", operation_token="once"))
+    )
+    first.start()
+    assert entered.wait(timeout=3)
+    second = threading.Thread(
+        target=lambda: results.append(service.validate("count_fasta", operation_token="once"))
+    )
+    second.start()
+    second.join(timeout=3)
+    release.set()
+    first.join(timeout=3)
+    assert calls == 1
+    assert {result["run_id"] for result in results} == {results[0]["run_id"]}
+
+
+def test_stop_can_use_persisted_process_without_waiting_for_long_baseline(
+    tmp_path: Path,
+) -> None:
+    service = _service(tmp_path)
+    raw_code = tmp_path / "source" / "raw_code"
+    raw_data = tmp_path / "source" / "raw_test_data"
+    raw_code.mkdir(parents=True)
+    raw_data.mkdir(parents=True)
+    _write(raw_code, "sleep.sh", "sleep 10\nprintf 'late result\\n'\n")
+    outcome: list[dict] = []
+    thread = threading.Thread(
+        target=lambda: outcome.append(
+            service.upload(
+                extension_id="slow", raw_code=raw_code, raw_data=raw_data,
+                original_command="bash sleep.sh", operation_token="upload-1",
+            )
+        )
+    )
+    thread.start()
+    deadline = time.monotonic() + 3
+    while time.monotonic() < deadline:
+        try:
+            state = service.get("slow")
+        except ValueError:
+            time.sleep(0.02)
+            continue
+        if state.get("active_process"):
+            break
+        time.sleep(0.02)
+    assert service.get("slow")["active_process"]["operation_token"] == "upload-1"
+    stopped = service.stop("slow", operation_token="upload-1")
+    thread.join(timeout=5)
+    assert stopped["stopped"] is True
+    assert not service.get("slow").get("active_process")
+    assert outcome[0]["status"] == "baseline_failed"
+
+
+def test_initial_semantic_failure_is_persisted_and_rebuildable(tmp_path: Path) -> None:
+    from gfa_core.extension_stage_lightweight.service import LightweightExtensionService
+
+    failing = LightweightExtensionService(
+        tmp_path / "store",
+        semantic_generator=lambda _facts, _raw_code: (_ for _ in ()).throw(RuntimeError("semantic down")),
+    )
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+    first = failing.upload(
+        extension_id="count_fasta", raw_code=raw_code, raw_data=raw_data,
+        original_command=command, operation_token="upload-1",
+    )
+    assert first["status"] == "build_failed"
+    assert failing.get("count_fasta")["error"]["phase"] == "semantic_candidate"
+    failing.semantic_generator = lambda facts, _raw_code: (_semantic_from_facts(facts), {})
+    rebuilt = failing.rebuild("count_fasta", operation_token="rebuild-1")
+    assert rebuilt["status"] == "confirmation_pending"
+
+
+def test_semantic_retry_reuses_baseline_and_locked_execution_facts(tmp_path: Path) -> None:
+    from gfa_core.extension_stage_lightweight.service import LightweightExtensionService
+
+    calls = 0
+
+    def semantic_generator(facts: dict, _raw_code: Path):
+        nonlocal calls
+        calls += 1
+        if calls == 1:
+            raise RuntimeError("truncated semantic JSON")
+        return _semantic_from_facts(facts), {"attempt": calls}
+
+    service = LightweightExtensionService(
+        tmp_path / "store", semantic_generator=semantic_generator
+    )
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+    first = service.upload(
+        extension_id="count_retry",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        original_command=command,
+        operation_token="upload-1",
+    )
+    failed = service.get("count_retry")
+    baseline_run_dir = failed["baseline"]["run_dir"]
+    facts_sha256 = failed["execution_facts"]["facts_sha256"]
+
+    retried = service.retry_semantic("count_retry", operation_token="semantic-2")
+    record = service.get("count_retry")
+
+    assert first["status"] == "build_failed"
+    assert retried["status"] == "confirmation_pending"
+    assert calls == 2
+    assert record["baseline"]["run_dir"] == baseline_run_dir
+    assert record["execution_facts"]["facts_sha256"] == facts_sha256
+    assert record["semantic_metadata"] == {"attempt": 2}
+
+
+def test_semantic_retry_recovers_facts_from_saved_legacy_baseline(tmp_path: Path) -> None:
+    from gfa_core.extension_stage_lightweight.service import LightweightExtensionService
+
+    service = LightweightExtensionService(
+        tmp_path / "store",
+        semantic_generator=lambda _facts, _raw_code: (_ for _ in ()).throw(
+            RuntimeError("semantic down")
+        ),
+    )
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+    service.upload(
+        extension_id="legacy_failure",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        original_command=command,
+        operation_token="upload-1",
+    )
+    legacy = service.get("legacy_failure")
+    baseline_run_dir = legacy["baseline"]["run_dir"]
+    legacy.pop("execution_facts")
+    service._write_record("legacy_failure", legacy)
+    service.semantic_generator = lambda facts, _raw_code: (
+        _semantic_from_facts(facts),
+        {},
+    )
+
+    retried = service.retry_semantic(
+        "legacy_failure", operation_token="semantic-legacy"
+    )
+    record = service.get("legacy_failure")
+
+    assert retried["status"] == "confirmation_pending"
+    assert record["baseline"]["run_dir"] == baseline_run_dir
+    assert record["execution_facts"]["facts_sha256"]
+
+
+def test_semantic_retry_is_noop_after_candidate_already_succeeded(
+    tmp_path: Path,
+) -> None:
+    calls = 0
+
+    def semantic_generator(facts: dict, _raw_code: Path):
+        nonlocal calls
+        calls += 1
+        return _semantic_from_facts(facts), {}
+
+    from gfa_core.extension_stage_lightweight.service import LightweightExtensionService
+
+    service = LightweightExtensionService(
+        tmp_path / "store", semantic_generator=semantic_generator
+    )
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+    service.upload(
+        extension_id="already_ready",
+        raw_code=raw_code,
+        raw_data=raw_data,
+        original_command=command,
+        operation_token="upload-1",
+    )
+
+    retried = service.retry_semantic(
+        "already_ready", operation_token="semantic-noop"
+    )
+
+    assert retried["status"] == "confirmation_pending"
+    assert calls == 1
+    assert service.get("already_ready")["status"] == "confirmation_pending"
+
+
+def test_operation_records_are_small_references_not_record_snapshots(tmp_path: Path) -> None:
+    service = _service(tmp_path)
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+    service.upload(
+        extension_id="count_fasta", raw_code=raw_code, raw_data=raw_data,
+        original_command=command, operation_token="upload-1",
+    )
+    operation = service.get("count_fasta")["operations"]["upload-1"]
+    assert set(operation) <= {"action", "state", "response", "run_id"}
+    assert "baseline" not in operation["response"]
+
+
+def test_unresolved_binding_finishes_validation_without_leaving_running(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    service = _service(tmp_path)
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+    service.upload(extension_id="count_fasta", raw_code=raw_code, raw_data=raw_data, original_command=command, operation_token="upload-1")
+    service.confirm("count_fasta", operation_token="confirm-1")
+    monkeypatch.setattr(
+        service,
+        "_execute",
+        lambda *_args, run_id, **_kwargs: {
+            "run_id": run_id,
+            "success": False,
+            "contract_passed": False,
+            "binding": {"status": "blocked"},
+            "projection": {"files": [], "stdout": {"present": False}},
+        },
+    )
+
+    response = service.validate("count_fasta", operation_token="validate-1")
+
+    assert response["status"] == "validation_failed"
+    state = service.get("count_fasta")
+    assert state["active_process"] is None
+    assert state["operations"]["validate-1"]["state"] == "completed"
+
+
+def test_early_stop_is_recorded_before_identity_and_honoured_on_callback(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    import gfa_core.extension_stage_lightweight.service as service_module
+
+    service = _service(tmp_path)
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+    service.upload(extension_id="count_fasta", raw_code=raw_code, raw_data=raw_data, original_command=command, operation_token="upload-1")
+    service.confirm("count_fasta", operation_token="confirm-1")
+    entered = threading.Event()
+    release = threading.Event()
+    monkeypatch.setattr(service, "_execute", lambda *_args, run_id, **_kwargs: (entered.set(), release.wait(3), {"run_id": run_id, "success": False, "contract_passed": False, "projection": {"files": [], "stdout": {"present": False}}})[2])
+    stopped: list[dict] = []
+    monkeypatch.setattr(service_module, "stop_process_group", lambda identity, **_kwargs: stopped.append(identity) or True)
+    worker = threading.Thread(target=lambda: service.validate("count_fasta", operation_token="validate-1"))
+    worker.start()
+    assert entered.wait(timeout=3)
+
+    pending = service.stop("count_fasta", operation_token="validate-1")
+    assert pending["stopped"] is False
+    assert service.get("count_fasta")["operations"]["validate-1"]["stop_requested"] is True
+    identity = {"pid": 11, "pgid": 11, "pid_start_time": 1, "supervisor_token": "x"}
+    service._mark_process("count_fasta", token="validate-1", phase="validation", identity=identity)
+    release.set()
+    worker.join(timeout=3)
+
+    assert stopped == [identity]
+    assert service.get("count_fasta")["active_process"] is None
+
+
+def test_run_rejects_unsafe_job_id_before_path_resolution(tmp_path: Path) -> None:
+    service = _published_copy_service(tmp_path)
+    input_root = tmp_path / "input"
+    workspace_root = tmp_path / "workspace"
+    _write(input_root, "job_1/input.fa", ">x\n")
+    _write(workspace_root, "job_1/.keep", "")
+
+    with pytest.raises(ValueError, match="run_job_id"):
+        service.run(
+            "copy_fasta", input_overrides={"input.fa": input_root / "job_1/input.fa"},
+            run_job_id="../job_1", input_root=input_root, workspace_root=workspace_root,
+            operation_token="run-1",
+        )
+
+
+def test_validation_failure_can_retry_or_rebuild(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    service = _service(tmp_path)
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+    service.upload(extension_id="count_fasta", raw_code=raw_code, raw_data=raw_data, original_command=command, operation_token="upload-1")
+    service.confirm("count_fasta", operation_token="confirm-1")
+    actual = service._execute
+    failed = False
+
+    def fail_once(*args, run_id, **kwargs):
+        nonlocal failed
+        if not failed:
+            failed = True
+            return {"run_id": run_id, "success": False, "contract_passed": False, "projection": {"files": [], "stdout": {"present": False}}}
+        return actual(*args, run_id=run_id, **kwargs)
+
+    monkeypatch.setattr(service, "_execute", fail_once)
+    assert service.validate("count_fasta", operation_token="validate-fail")["status"] == "validation_failed"
+    assert service.validate("count_fasta", operation_token="validate-retry")["status"] == "result_review_pending"
+
+    rebuilder = _service(tmp_path / "rebuild-case")
+    rebuild_code, rebuild_data, rebuild_command = _package(tmp_path / "rebuild-case", stdout_only=True)
+    rebuilder.upload(extension_id="count_fasta", raw_code=rebuild_code, raw_data=rebuild_data, original_command=rebuild_command, operation_token="upload-1")
+    rebuilder.confirm("count_fasta", operation_token="confirm-1")
+    monkeypatch.setattr(rebuilder, "_execute", lambda *_args, run_id, **_kwargs: {"run_id": run_id, "success": False, "contract_passed": False, "projection": {"files": [], "stdout": {"present": False}}})
+    assert rebuilder.validate("count_fasta", operation_token="validate-fail")["status"] == "validation_failed"
+    assert rebuilder.rebuild("count_fasta", operation_token="rebuild-1")["status"] == "confirmation_pending"
+
+
+def test_concurrent_duplicate_upload_token_reuses_reserved_operation(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    service = _service(tmp_path)
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+    actual = service._run_baseline_operation
+    entered = threading.Event()
+    release = threading.Event()
+
+    def slow_baseline(*args, **kwargs):
+        entered.set()
+        assert release.wait(timeout=3)
+        return actual(*args, **kwargs)
+
+    monkeypatch.setattr(service, "_run_baseline_operation", slow_baseline)
+    results: list[dict] = []
+    first = threading.Thread(target=lambda: results.append(service.upload(extension_id="count_fasta", raw_code=raw_code, raw_data=raw_data, original_command=command, operation_token="upload-1")))
+    first.start()
+    assert entered.wait(timeout=3)
+    second = threading.Thread(target=lambda: results.append(service.upload(extension_id="count_fasta", raw_code=raw_code, raw_data=raw_data, original_command=command, operation_token="upload-1")))
+    second.start()
+    second.join(timeout=3)
+    release.set()
+    first.join(timeout=3)
+
+    assert len(results) == 2
+    assert {item["run_id"] for item in results} == {results[0]["run_id"]}
+
+
+@pytest.mark.parametrize("token", ["", "   "])
+def test_upload_rejects_blank_token_before_creating_extension_directory(
+    tmp_path: Path, token: str
+) -> None:
+    service = _service(tmp_path)
+    raw_code, raw_data, command = _package(tmp_path, stdout_only=True)
+
+    with pytest.raises(ValueError, match="operation_token"):
+        service.upload(
+            extension_id="count_fasta", raw_code=raw_code, raw_data=raw_data,
+            original_command=command, operation_token=token,
+        )
+
+    assert not service.extension_dir("count_fasta").exists()
diff --git a/tests/unit/test_extension_stage_lightweight_shell_binding.py b/tests/unit/test_extension_stage_lightweight_shell_binding.py
new file mode 100644
index 000000000..3f118e301
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_shell_binding.py
@@ -0,0 +1,57 @@
+from pathlib import Path
+
+from gfa_core.extension_stage_lightweight.command_model import build_command_model
+
+
+def _state(*paths: str) -> dict[str, dict[str, object]]:
+    return {path: {"kind": "file", "size": 1, "sha256": path} for path in paths}
+
+
+def test_exact_output_reference_wins_over_prefix_match(tmp_path: Path) -> None:
+    (tmp_path / "run.sh").write_text(
+        """tool --out result.tbl input.dat
+filter result.tbl > result.tbl.filtered
+""",
+        encoding="utf-8",
+    )
+
+    model = build_command_model(
+        command="bash run.sh",
+        work_dir=tmp_path,
+        before_files=_state("run.sh", "input.dat"),
+        output_files=["result.tbl", "result.tbl.filtered"],
+        code_files=["run.sh"],
+    )
+
+    assert model["commands"][0]["outputs"] == ["result.tbl"]
+    assert model["commands"][1]["outputs"] == ["result.tbl.filtered"]
+
+
+def test_shell_positional_argument_is_bound_through_simple_variable(tmp_path: Path) -> None:
+    (tmp_path / "count.sh").write_text(
+        """#!/usr/bin/env bash
+set -euo pipefail
+if [ "$#" -ne 1 ]; then echo usage >&2; exit 1; fi
+input=$1
+awk '/^>/{n++} END{print n+0}' "$input"
+""",
+        encoding="utf-8",
+    )
+
+    model = build_command_model(
+        command="bash count.sh Ath.genome.fasta",
+        work_dir=tmp_path,
+        before_files=_state("count.sh", "Ath.genome.fasta"),
+        output_files=[],
+        code_files=["count.sh"],
+    )
+
+    assert [command["tool"] for command in model["commands"]] == ["awk"]
+    assert model["commands"][0]["inputs"] == [
+        {
+            "path": "Ath.genome.fasta",
+            "source": "baseline_input",
+            "flag": None,
+            "token_index": 2,
+        }
+    ]
diff --git a/tests/unit/test_extension_stage_lightweight_shell_pipeline.py b/tests/unit/test_extension_stage_lightweight_shell_pipeline.py
new file mode 100644
index 000000000..40dfac85c
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_shell_pipeline.py
@@ -0,0 +1,41 @@
+from pathlib import Path
+
+from gfa_core.extension_stage_lightweight.command_model import build_command_model
+
+
+def test_shell_pipeline_is_modelled_as_separate_executables(tmp_path: Path) -> None:
+    (tmp_path / "run.sh").write_text(
+        """hmmsearch --cut_tc --domtblout hits.tbl model.hmm proteins.fa
+awk '$7<0.01 {print $0}' hits.tbl > filtered.tbl
+awk '{print $1}' filtered.tbl | sort -u > ids.txt
+""",
+        encoding="utf-8",
+    )
+    before = {
+        name: {"kind": "file", "size": 1, "sha256": name}
+        for name in ("run.sh", "model.hmm", "proteins.fa")
+    }
+
+    model = build_command_model(
+        command="bash run.sh",
+        work_dir=tmp_path,
+        before_files=before,
+        output_files=["hits.tbl", "filtered.tbl", "ids.txt"],
+        code_files=["run.sh"],
+    )
+
+    assert [command["tool"] for command in model["commands"]] == [
+        "hmmsearch",
+        "awk",
+        "awk",
+        "sort",
+    ]
+    assert model["commands"][1]["inputs"][0]["path"] == "hits.tbl"
+    assert model["commands"][2]["inputs"][0]["path"] == "filtered.tbl"
+    assert model["commands"][3]["parameters"][0] == {
+        "kind": "switch",
+        "flag": "-u",
+        "value": "-u",
+        "token_index": 1,
+    }
+    assert model["commands"][3]["outputs"] == ["ids.txt"]
diff --git a/tests/unit/test_extension_stage_lightweight_target_launchers.py b/tests/unit/test_extension_stage_lightweight_target_launchers.py
new file mode 100644
index 000000000..be63e6a3b
--- /dev/null
+++ b/tests/unit/test_extension_stage_lightweight_target_launchers.py
@@ -0,0 +1,25 @@
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+WEB = ROOT / "start_plantai_9000.sh"
+WORKER = ROOT / "start_celery_9000.sh"
+
+
+def test_target_launchers_share_lightweight_extension_runtime_roots() -> None:
+    web = WEB.read_text(encoding="utf-8")
+    worker = WORKER.read_text(encoding="utf-8")
+
+    for name in (
+        "BBAV5_PROJECT_ENV_FILE",
+        "BBAV5_LIGHTWEIGHT_EXTENSION_STORE",
+        "BBAV5_LIGHTWEIGHT_INPUT",
+        "BBAV5_LIGHTWEIGHT_WORKSPACE",
+    ):
+        assert name in web
+        assert name in worker
+
+    assert 'export BBAV5_QUEUE_PREFIX="plantai_dev_9000"' in web
+    assert 'export BBAV5_REDIS_URL="redis://localhost:6379/10"' in web
+    assert 'BBAV5_QUEUE_PREFIX="plantai_dev_9000"' in worker
+    assert 'BBAV5_REDIS_URL="redis://localhost:6379/10"' in worker
diff --git a/tests/unit/test_frontend_cpu_monitor_contract.py b/tests/unit/test_frontend_cpu_monitor_contract.py
new file mode 100644
index 000000000..1d1e8556b
--- /dev/null
+++ b/tests/unit/test_frontend_cpu_monitor_contract.py
@@ -0,0 +1,13 @@
+from pathlib import Path
+
+
+INDEX_HTML = Path(__file__).resolve().parents[2] / "apps" / "web" / "vue3" / "index.html"
+
+
+def test_cpu_monitor_polls_lightweight_resource_endpoint_independently():
+    source = INDEX_HTML.read_text(encoding="utf-8")
+
+    assert "const refreshResourceUsage = async () =>" in source
+    assert "fetch('/api/resource/status', { cache: 'no-store' })" in source
+    assert "resourceMonitorTimer = setInterval(refreshResourceUsage, 1000)" in source
+    assert "clearInterval(resourceMonitorTimer)" in source
diff --git a/tests/unit/test_frontend_execution_indicator_recovery.py b/tests/unit/test_frontend_execution_indicator_recovery.py
new file mode 100644
index 000000000..e8f45dc00
--- /dev/null
+++ b/tests/unit/test_frontend_execution_indicator_recovery.py
@@ -0,0 +1,40 @@
+from pathlib import Path
+
+
+INDEX_HTML = Path(__file__).resolve().parents[2] / "apps" / "web" / "vue3" / "index.html"
+MAIN_PY = Path(__file__).resolve().parents[2] / "apps" / "web" / "vue3" / "main.py"
+
+
+def test_execution_indicator_recovers_current_job_tasks_from_backend_runtime():
+    source = INDEX_HTML.read_text(encoding="utf-8")
+
+    assert "resource_tasks: []" in source
+    assert "runtimeOverview.resource_tasks = Array.isArray(data.resource_tasks) ? data.resource_tasks : [];" in source
+    assert "const currentJobRuntimeTasks = computed" in source
+    assert "String(task.job_id || '') === currentJobId" in source
+    assert "const executionIndicatorTask = computed" in source
+
+
+def test_execution_indicator_visibility_and_stop_use_recovered_backend_task():
+    source = INDEX_HTML.read_text(encoding="utf-8")
+
+    assert 'v-if="showExecutionIndicator"' in source
+    assert "const showExecutionIndicator = computed" in source
+    assert "executionIndicatorTask.value" in source
+    assert "currentJobRuntimeTasks.value.forEach" in source
+    assert "task.task_id" in source
+
+
+def test_execution_indicator_clears_only_after_backend_task_is_terminal():
+    source = INDEX_HTML.read_text(encoding="utf-8")
+
+    assert "const ACTIVE_RUNTIME_TASK_STATUSES" in source
+    assert "'queued', 'pending', 'running', 'started', 'waiting_resource', 'retry'" in source
+    assert "ACTIVE_RUNTIME_TASK_STATUSES.has" in source
+
+
+def test_runtime_overview_does_not_truncate_active_resource_tasks():
+    source = MAIN_PY.read_text(encoding="utf-8")
+
+    assert 'overview["resource_tasks"] = resource.get("tasks", [])' in source
+    assert 'resource.get("tasks", [])[:20]' not in source
diff --git a/tests/unit/test_gene_family_scope_reference_roots.py b/tests/unit/test_gene_family_scope_reference_roots.py
new file mode 100644
index 000000000..62d27236b
--- /dev/null
+++ b/tests/unit/test_gene_family_scope_reference_roots.py
@@ -0,0 +1,11 @@
+from gfa_core.gene_family_scope import reference_search_roots
+
+
+def test_reference_search_roots_reads_configured_root(monkeypatch, tmp_path) -> None:
+    reference_root = tmp_path / "references"
+    reference_root.mkdir()
+    monkeypatch.setenv("PLANTAI_REF_DATA_ROOT", str(reference_root))
+
+    roots = reference_search_roots(tmp_path / "input")
+
+    assert reference_root.resolve() in roots
diff --git a/tests/unit/test_persistent_conversation_job_isolation.py b/tests/unit/test_persistent_conversation_job_isolation.py
new file mode 100644
index 000000000..661eb8eec
--- /dev/null
+++ b/tests/unit/test_persistent_conversation_job_isolation.py
@@ -0,0 +1,53 @@
+from pathlib import Path
+
+from gfa_core.mas.agent_state_repository import SQLiteAgentStateRepository
+from gfa_core.mas.persistent_conversation import PersistentConversationStore
+
+
+def _store(tmp_path: Path) -> PersistentConversationStore:
+    repository = SQLiteAgentStateRepository(tmp_path / "agent-state.sqlite3")
+    repository.initialize()
+    return PersistentConversationStore(repository)
+
+
+def test_rebind_to_different_job_creates_empty_conversation_and_preserves_old(tmp_path: Path) -> None:
+    store = _store(tmp_path)
+    old_turn = store.begin_turn(
+        session_id="old-session",
+        job_id="job_old",
+        query="旧 job 的问题",
+        client_history=[],
+    )
+
+    new_conversation_id = store.rebind_job(
+        session_id=old_turn.conversation_id,
+        job_id="job_new",
+    )
+
+    assert new_conversation_id != old_turn.conversation_id
+    old_conversation = store.repository.get_conversation(old_turn.conversation_id)
+    new_conversation = store.repository.get_conversation(new_conversation_id)
+    assert old_conversation is not None and old_conversation.job_id == "job_old"
+    assert new_conversation is not None and new_conversation.job_id == "job_new"
+    assert [message.content for message in store.repository.list_recent_messages(old_turn.conversation_id)] == ["旧 job 的问题"]
+    assert store.repository.list_recent_messages(new_conversation_id) == ()
+    ledger = store.repository.get_goal_ledger(new_conversation_id)
+    assert ledger is not None
+    assert ledger.user_terms == {"active_job_id": "job_new"}
+
+
+def test_rebind_to_same_job_keeps_conversation_identity(tmp_path: Path) -> None:
+    store = _store(tmp_path)
+    turn = store.begin_turn(
+        session_id="same-session",
+        job_id="job_same",
+        query="当前 job 的问题",
+        client_history=[],
+    )
+
+    conversation_id = store.rebind_job(
+        session_id=turn.conversation_id,
+        job_id="job_same",
+    )
+
+    assert conversation_id == turn.conversation_id
diff --git a/tests/unit/test_result_browser_persistence.py b/tests/unit/test_result_browser_persistence.py
new file mode 100644
index 000000000..f5c969be0
--- /dev/null
+++ b/tests/unit/test_result_browser_persistence.py
@@ -0,0 +1,77 @@
+import asyncio
+import json
+import os
+from pathlib import Path
+
+
+def test_result_browser_prefers_latest_manifest_and_shows_subfamily_evidence(monkeypatch, tmp_path):
+    from apps.web.vue3 import main as web_main
+
+    workspace_root = tmp_path / "workspace"
+    final_dir = workspace_root / "job-results" / "final"
+    final_dir.mkdir(parents=True)
+    image = final_dir / "Target.PEBP.target-Os.ref-At.subfamily_evidence.motif.png"
+    image.write_bytes(b"png")
+
+    success = final_dir / "Target.PEBP.target-Os.ref-At.subfamily_evidence.motif.manifest.json"
+    success.write_text(
+        json.dumps(
+            {
+                "stage": "motif",
+                "status": "success",
+                "prefix": "Os.PEBP",
+                "output_prefix": "Target.PEBP.target-Os.ref-At.subfamily_evidence",
+                "scope_id": "PEBP.target-Os.ref-At.target_plus_reference",
+                "scope_mode": "target_plus_reference",
+                "analysis_route": "subfamily_evidence",
+                "result_group": "motif_subfamily_evidence",
+                "elapsed_sec": 3.0,
+                "artifacts": {
+                    "motif_plot_png": {
+                        "artifact": "motif_plot",
+                        "path": f"final/{image.name}",
+                        "type": "image",
+                    }
+                },
+            }
+        ),
+        encoding="utf-8",
+    )
+    failed = final_dir / "Os.PEBP.target_only.motif.manifest.json"
+    failed.write_text(
+        json.dumps(
+            {
+                "stage": "motif",
+                "status": "failed",
+                "prefix": "Os.PEBP",
+                "scope_id": "PEBP.target-Os.target_only",
+                "analysis_route": "multi_species",
+                "parameters": {"error": "old failed attempt"},
+                "artifacts": {},
+            }
+        ),
+        encoding="utf-8",
+    )
+    os.utime(failed, (1, 1))
+    os.utime(success, (2, 2))
+
+    monkeypatch.setattr(web_main, "WORKSPACE_ROOT", workspace_root)
+    result = asyncio.run(web_main.get_results(job_id="job-results", stage="motif"))
+
+    assert result["motif"]["status"] == "success"
+    assert image.name in json.dumps(result["motif"], ensure_ascii=False)
+
+
+def test_result_panel_has_three_persistent_workflow_groups():
+    html = (Path(__file__).resolve().parents[2] / "apps/web/vue3/index.html").read_text(encoding="utf-8")
+
+    assert "RNA-seq" in html
+    assert "基因家族" in html
+    assert "WGS2GWAS（遗传变异与群体分析）" in html
+    assert "const resultGroups = computed" in html
+    assert "const groupStages = stages.filter(stage => resultGroupNameForStage(stage.name) === group.name);" in html
+    assert "wgsPopulationGwasResultRank(a.name) - wgsPopulationGwasResultRank(b.name)" in html
+    assert "name: 'wgs_qc'" in html
+    assert "name: 'wgs_maf_missing_filter'" in html
+    assert "await refreshResults(completedJobId, stageName);" in html
+    assert "await refreshResults(latestConversation.job_id);" in html
diff --git a/tests/unit/test_stage_tool_tree_passthrough.py b/tests/unit/test_stage_tool_tree_passthrough.py
new file mode 100644
index 000000000..e8ef93ce9
--- /dev/null
+++ b/tests/unit/test_stage_tool_tree_passthrough.py
@@ -0,0 +1,62 @@
+import asyncio
+import json
+import sys
+import types
+from dataclasses import dataclass
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from gfa_core.mas.tools.stage_tools import StageTool, StageToolExecutor  # noqa: E402
+
+
+def test_stage_tool_executor_passes_preflight_tree_to_backend(monkeypatch, tmp_path):
+    captured = {}
+
+    @dataclass
+    class FakeJobInfo:
+        job_id: str
+        input_dir: str
+        workspace_dir: str
+        logs_dir: str
+        created_at: str
+
+    def fake_run_stage(**kwargs):
+        captured.update(kwargs)
+        final_dir = Path(kwargs["job"].workspace_dir) / "final"
+        final_dir.mkdir(parents=True, exist_ok=True)
+        manifest = final_dir / "Target.PEBP.motif.manifest.json"
+        manifest.write_text(
+            json.dumps({"status": "success", "stage": "motif", "prefix": "Target.PEBP"}),
+            encoding="utf-8",
+        )
+        return "motif completed", manifest
+
+    fake_module = types.ModuleType("apps.web.pipeline_backend")
+    fake_module.JobInfo = FakeJobInfo
+    fake_module.run_stage = fake_run_stage
+    monkeypatch.setitem(sys.modules, "apps.web.pipeline_backend", fake_module)
+
+    selected_tree = tmp_path / "Target.PEBP.subfamily_evidence.tree.nwk"
+    selected_tree.write_text("(Os1,At1);\n", encoding="utf-8")
+
+    result = asyncio.run(
+        StageToolExecutor(project_root=tmp_path).execute(
+            stage_tool=StageTool(
+                id="motif",
+                name="Motif",
+                script="apps/cli/run_motif.py",
+                category="gene_family",
+                description="test",
+            ),
+            job_id="job_tree_passthrough",
+            prefix="Target.PEBP",
+            extra_params={"treeFile": str(selected_tree), "cpu": 2},
+        )
+    )
+
+    assert result["status"] == "success"
+    assert captured["tree_file"] == str(selected_tree)
diff --git a/tests/unit/test_subfamily_prediction_plan.py b/tests/unit/test_subfamily_prediction_plan.py
index 9e9ffe889..f8f77efad 100755
--- a/tests/unit/test_subfamily_prediction_plan.py
+++ b/tests/unit/test_subfamily_prediction_plan.py
@@ -1,5 +1,13 @@
 import importlib.util
+import json
 from pathlib import Path
+from types import SimpleNamespace
+
+from gfa_core.gene_family_stage_context import (
+    enrich_stage_params_with_context,
+    infer_analysis_route,
+)
+from gfa_core.mas.artifact_resolver import ArtifactResolver
 
 
 def _load_vue3_main():
@@ -40,3 +48,285 @@ def test_subfamily_prediction_plan_uses_per_target_evidence_route():
     assert detail_by_id["reference_classification"]["params"]["analysisRoute"] == "subfamily_prediction"
     assert plan["total_stages"] == 7
     assert intent["primary_stage"] == "reference_classification"
+
+
+def test_subfamily_request_roles_do_not_promote_reference_to_target(monkeypatch):
+    main = _load_vue3_main()
+    monkeypatch.setattr(
+        main,
+        "_configured_species_scope",
+        lambda _job_id: {
+            "targetSpecies": ["Os"],
+            "referenceSpecies": ["At"],
+            "comparativeSpecies": [],
+        },
+    )
+    monkeypatch.setattr(
+        main,
+        "_extract_species_codes_from_text_for_job",
+        lambda _job_id, _message: ["Os", "At"],
+    )
+
+    roles = main._resolve_subfamily_request_species_roles(
+        "job-real",
+        "执行目标物种 Os 和参考物种 At 的亚家族分类",
+        {
+            "target_species": ["Os"],
+            "reference_species": ["At"],
+            "params": {"targetSpecies": ["Os"], "referenceSpecies": ["At"]},
+        },
+    )
+
+    assert roles == {
+        "target_species": ["Os"],
+        "reference_species": ["At"],
+        "comparative_species": [],
+        "classification_species": ["Os"],
+    }
+
+
+def test_generic_target_reference_scope_does_not_guess_subfamily_from_stage_name():
+    scope = {
+        "scope_mode": "target_plus_reference",
+        "target_species": ["Ft"],
+        "reference_species": ["At"],
+        "comparative_species": [],
+    }
+
+    assert infer_analysis_route("phylogeny", scope) == "multi_species"
+    assert infer_analysis_route("motif", scope) == "multi_species"
+
+
+def test_newick_manifest_artifact_satisfies_tree_requirement():
+    assert ArtifactResolver._kind_matches("tree", "newick") is True
+
+
+def test_semantic_preflight_materializes_selected_tree(monkeypatch):
+    main = _load_vue3_main()
+
+    class Selected:
+        path = "/workspace/final/Target.PEBP.subfamily_evidence.tree.nwk"
+
+    class Decision:
+        resolved = True
+        selected = Selected()
+        candidates = []
+
+        def to_dict(self):
+            return {
+                "resolved": True,
+                "selected": {
+                    "path": self.selected.path,
+                    "kind": "newick",
+                    "source": "artifact:phylogeny:tree",
+                },
+                "candidates": [],
+            }
+
+    class Resolver:
+        def __init__(self, _context):
+            pass
+
+        def resolve_stage(self, stage, species="", family=""):
+            return {
+                "family_members_pep": Decision(),
+                "tree": Decision(),
+            }
+
+    context = SimpleNamespace(
+        family="PEBP",
+        target_species=["Os"],
+        reference_species=["At"],
+        comparative_species=[],
+        config_path="/workspace/input/config.xlsx",
+    )
+    monkeypatch.setattr(main, "build_project_context", lambda **_kwargs: context)
+    monkeypatch.setattr(main, "ArtifactResolver", Resolver)
+    monkeypatch.setattr(
+        main,
+        "_validate_gene_family_stage_context",
+        lambda **_kwargs: {"valid": True, "issues": [], "evidence": {}},
+    )
+
+    result = main._api_semantic_preflight(
+        "job-direct-motif",
+        "motif",
+        "Os.PEBP",
+        {
+            "geneFamily": "PEBP",
+            "targetSpecies": ["Os"],
+            "referenceSpecies": ["At"],
+            "scopeMode": "target_plus_reference",
+            "analysisRoute": "subfamily_evidence",
+        },
+    )
+
+    assert result["valid"] is True
+    assert result["materialized_params"]["treeFile"] == Selected.path
+
+
+def test_scoped_tree_resolution_prefers_preflight_selected_tree(tmp_path):
+    from apps.web import pipeline_backend
+
+    workspace = tmp_path / "workspace"
+    final_dir = workspace / "final"
+    final_dir.mkdir(parents=True)
+    scope_file = final_dir / "Os.PEBP.scope.json"
+    scope_file.write_text(
+        json.dumps({
+            "scope_id": "PEBP.target-Os.ref-At.target_plus_reference",
+            "scope_mode": "target_plus_reference",
+            "target_species": ["Os"],
+            "reference_species": ["At"],
+        }),
+        encoding="utf-8",
+    )
+    selected_tree = final_dir / "Target.PEBP.subfamily_evidence.tree.nwk"
+    selected_tree.write_text("(Os1,At1);\n", encoding="utf-8")
+
+    resolved, _scope = pipeline_backend.resolve_scoped_tree_from_phylogeny(
+        workspace,
+        final_dir,
+        "Os.PEBP",
+        scope_file,
+        explicit_tree_file=str(selected_tree),
+    )
+
+    assert resolved == selected_tree.resolve()
+
+
+def test_explicit_subfamily_and_regular_routes_remain_separate():
+    shared = {
+        "geneFamily": "SPL",
+        "targetSpecies": ["Ft", "Os"],
+        "referenceSpecies": ["At"],
+        "scopeMode": "target_plus_reference",
+        "analysisMode": "joint_multi_species",
+    }
+
+    evidence = enrich_stage_params_with_context(
+        "motif",
+        "Target.SPL",
+        {**shared, "analysisRoute": "subfamily_evidence"},
+    )
+    prediction = enrich_stage_params_with_context(
+        "reference_classification",
+        "Target.SPL",
+        {**shared, "analysisRoute": "subfamily_prediction"},
+    )
+    regular = enrich_stage_params_with_context("motif", "Target.SPL", shared)
+
+    assert evidence["analysisRoute"] == "subfamily_evidence"
+    assert evidence["memberSetId"].endswith(":subfamily_evidence:domain_refined")
+    assert evidence["analysisMode"] == "joint_multi_species"
+    assert prediction["analysisRoute"] == "subfamily_prediction"
+    assert regular["analysisRoute"] == "multi_species"
+    assert regular["memberSetId"].endswith(":multi_species:all_members")
+
+
+def test_direct_motif_request_uses_job_subfamily_state(monkeypatch):
+    main = _load_vue3_main()
+    monkeypatch.setattr(
+        main,
+        "_load_identify_species_selection",
+        lambda _job_id: {
+            "groups": {
+                "target": [{"species": "Ft"}],
+                "reference": [{"species": "At"}],
+                "comparative": [],
+            }
+        },
+    )
+    monkeypatch.setattr(main, "_gene_family_from_config", lambda _path: "SPL")
+    monkeypatch.setattr(main, "_confirmed_subfamily_species", lambda _job_id, _family: [])
+    monkeypatch.setattr(main, "_extract_species_codes_from_text_for_job", lambda _job_id, _text: [])
+    monkeypatch.setattr(
+        main,
+        "_subfamily_state_for_targets",
+        lambda _job_id, _species, _family: {
+            "all_confirmed": False,
+            "by_species": {"Ft": {"status": "not_classified"}},
+            "issues": [{"code": "subfamily_classification_missing"}],
+        },
+    )
+    monkeypatch.setattr(
+        main,
+        "_validate_gene_family_stage_context",
+        lambda **_kwargs: {"valid": True, "issues": [], "evidence": {}},
+    )
+
+    contextual = main._resolve_contextual_gene_family_request(
+        "job-direct-motif",
+        "执行 Motif 分析",
+        "Ft.SPL",
+        requested_stages=["motif"],
+    )
+
+    assert contextual["stages"] == ["motif"]
+    assert contextual["targetSpecies"] == ["Ft"]
+    assert contextual["referenceSpecies"] == ["At"]
+    assert contextual["contextGate"]["needs_subfamily_decision"] is True
+
+
+def test_direct_stage_preserves_species_roles_from_intent_when_selector_is_empty(monkeypatch):
+    main = _load_vue3_main()
+    monkeypatch.setattr(main, "_load_identify_species_selection", lambda _job_id: {})
+    monkeypatch.setattr(main, "_gene_family_from_config", lambda _path: "PEBP")
+    monkeypatch.setattr(main, "_confirmed_subfamily_species", lambda _job_id, _family: [])
+    monkeypatch.setattr(main, "_extract_species_codes_from_text_for_job", lambda _job_id, _text: [])
+    monkeypatch.setattr(
+        main,
+        "_subfamily_state_for_targets",
+        lambda _job_id, _species, _family: {
+            "all_confirmed": False,
+            "by_species": {"Os": {"status": "not_classified"}},
+            "issues": [],
+        },
+    )
+    monkeypatch.setattr(
+        main,
+        "_validate_gene_family_stage_context",
+        lambda **_kwargs: {"valid": True, "issues": [], "evidence": {}},
+    )
+
+    contextual = main._resolve_contextual_gene_family_request(
+        "job-direct-motif",
+        "执行 Motif 分析",
+        "Os.PEBP",
+        requested_stages=["motif"],
+        request_intent={
+            "target_species": ["Os"],
+            "reference_species": ["At"],
+            "params": {
+                "targetSpecies": ["Os"],
+                "referenceSpecies": ["At"],
+            },
+        },
+    )
+
+    assert contextual["targetSpecies"] == ["Os"]
+    assert contextual["referenceSpecies"] == ["At"]
+    assert contextual["scopeMode"] == "target_plus_reference"
+
+    request = SimpleNamespace(
+        job_id="job-direct-motif",
+        message="执行 Motif 分析",
+        prefix="Os.PEBP",
+        intent={
+            "stages": ["motif"],
+            "params": {
+                "targetSpecies": ["Os"],
+                "referenceSpecies": ["At"],
+            },
+        },
+    )
+    response = main._build_contextual_gene_family_plan_response(
+        request,
+        "session-direct-motif",
+        contextual,
+    )
+    details = {item["id"]: item for item in response["plan"]["all_stages_detail"]}
+
+    assert details["phylogeny"]["params"]["analysisRoute"] == "subfamily_evidence"
+    assert details["motif"]["params"]["analysisRoute"] == "subfamily_evidence"
+    assert details["phylogeny"]["params"]["memberSetId"] == details["motif"]["params"]["memberSetId"]