Skip to content

feat(control-plane,rfc): add L0 session & quota fabric contract for single-workbench convergence - #8886

Open
loopx-agent wants to merge 2 commits into
mainfrom
codex/calli-session-fabric-convergence-20261117
Open

loopx-agent wants to merge 2 commits into
mainfrom
codex/calli-session-fabric-convergence-20261117

Conversation

@loopx-agent

@loopx-agent loopx-agent commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Goal / Source

Converge the Calli/LooChat workbench and session-fabric proposals (#8778, #8782–#8784, #8843) into a minimal, independently reviewable L0 Session & Quota Fabric contract slice rooted in the existing single Goal Workbench (apps/presentation/dashboard) rather than introducing a second 40k–192k LOC frontend app or duplicated task/daemon authority.

Current Gap

Observable Result

  • Extracted zero-import loopx/control_plane/collaboration/session_quota_fabric_contract.ts as the single TypeScript owner for SAFE_HOST_ALIAS / isSafeHostAlias, boundary-anchored public-safety credential/path guards (assertPublicSafeFabricText), SESSION_MODES, closed fabric vocabularies, and decodeSshHostObservationWith.
  • Updated loopx/control_plane/collaboration/session_quota_fabric.ts to import/re-export contract owners, add projectSshHostCatalogRequest, and align evaluateGovernedSessionHandover strictly with observation.handover_eligible and observation.availability (unknown/available -> no_handover_needed; exhausted triggers gate/fence even below threshold_ratio; near_limit requires used_ratio >= threshold_ratio).
  • Replaced naive .includes("sk-") substring detection with boundary-anchored credential/token regexes so legitimate OpenSSH aliases (desk-box, task-worker, disk-01, kiosk-2) pass while real secret prefixes and private paths fail closed.
  • Wired production owners across TypeScript, Python, and dashboard:
  • Registered session_mode (reused from loopx/chat_store.py / loopx/chat_manager.py) and the four session_quota_fabric closed sets in loopx/semantics/vocabulary_v0.json (docs/reference/glossary.md, examples/semantic-vocabulary-drift-smoke.py, tests/architecture/test_semantic_vocabulary_drift.py), and synchronized bilingual RFC docs/architecture/rfcs/session-and-quota-fabric-v0.md + .zh-CN.md (plus README.md, STATUS.md, STATUS.zh-CN.md).
  • Resolved all 4 blocking findings from review 5948223455 on rebased head a88a364b6acc4da1c00ab5a0b13a7c5fed865212 (rebased onto origin/main 3a1f5ea78788f72d88e6174f622f848f8d7c767c).

Verification (Head a88a364b6acc4da1c00ab5a0b13a7c5fed865212)

  • npm run typecheck:control-plane: exit 0
  • node --no-warnings --experimental-sqlite --experimental-strip-types --test tests/control_plane_ts/session_quota_fabric.test.ts tests/control_plane_ts/effect_runtime_handler_loading.test.ts tests/control_plane_ts/content_digest_single_owner.test.ts: 29 passed, 0 failed
  • (cd apps/presentation/dashboard && ./node_modules/.bin/tsc --noEmit && npm run smoke:status-sources): status source catalog smoke: ok
  • uv run --extra test python -m pytest -n 3 -q tests/architecture/test_semantic_vocabulary_drift.py tests/architecture/test_cross_runtime_value_notes.py tests/architecture/test_semantic_bindings.py tests/architecture/test_semantic_development_probe.py tests/architecture/test_control_plane_import_boundaries.py tests/architecture/test_rfc_status_index.py tests/test_status_server_ssh_hosts.py tests/test_manager_channel_binding.py tests/test_attached_session_broker.py tests/control_plane/test_effect_runtime_integration.py: 452 passed, 1 skipped (tests/control_plane/test_effect_runtime_integration.py:75: Linux thread-group leader exit on macOS)
  • uv run --extra test python scripts/generate_semantic_inventory.py --changed-from origin/main & uv run --extra test python examples/semantic-vocabulary-drift-smoke.py: ok (34/34 vocabularies, 62/62 owner symbols, 0 unregistered changed semantic carriers)
  • uv run --extra test python scripts/check_rfc_bilingual.py --base origin/main --head HEAD: RFC bilingual diff check passed.
  • uv run --extra test ruff check ... & uv run --extra test mypy --strict --follow-imports=silent loopx/control_plane/status/ssh_host_catalog.py tests/test_status_server_ssh_hosts.py: passed (0 issues)
  • uv run --extra test loopx canary premerge --tier quick --from-git-diff --git-diff-base origin/main --goal-id personal-loopx-maintenance: passed (gate.merge_gate_passed=true, receipt cqr_a99f3fe45b253b53dd23, scope_fingerprint=a99f3fe45b253b53dd23bc642b499069ba0930c0078b212bd9e96dd33e05b3e5)
  • uv run --extra test loopx --format json check --scan-path ... (20 changed files): ok=true, errors=0, public_boundary_scan.ok=true (6 non-literal credential pattern mentions in session-and-quota-fabric-v0.md/.zh-CN.md downgraded to warnings)
  • Note on global RFC index smoke (scripts/generate_rfc_status_index.py --check / examples/docs-governance-smoke.py): fails on pre-existing untouched origin/main files (monorepo-distribution-split-v0.md/.zh-CN.md dated log heading); all PR feat(control-plane,rfc): add L0 session & quota fabric contract for single-workbench convergence #8886 RFC files and tests/architecture/test_rfc_status_index.py (13 passed) pass.

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · Google Gemini (self_reported)

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

针对精确头 096c7a7d7a03c95731f8d29361b160777d857942(base 31944d835466c29f18f843ea92de75b49e7c0c62)的审查结论:暂不建议合入(REQUEST_CHANGES)。本 PR 提出的“先收敛 L0 底座契约、嵌入单一 Goal 工作台、拒绝 4 万–19.2 万行第二前端”路线与维护者在 #8778 / #8843 的架构关切方向一致,双语 RFC 同步与基础测试也已就绪;但代码实现层存在四项明确的阻塞缺陷,必须在合入前修复。

动机 / Motivation

在多个本地与 SSH 远端主机间调度多 CLI Agent 会话并处理额度切换的 Goal 运维者与 Dashboard 前端调用方。
改前独立工作台提案(#8778、#8783、#8784、#8843)试图引入 4 万至 19.2 万行规模的第二套前端壳层与独立 Node 守护进程,从而与 LoopX Core 单写者任务权威和既有单一 Goal 工作台产生分裂;本 PR 拟先抽离零 I/O 的 L0 会话与额度底座契约及双语收敛 RFC,为后续直接嵌入现有工作台铺路。
双语 RFC 索引与 TypeScript 单元测试(4 条)在孤立夹具下通过,但当前实现存在多处可验证缺陷导致 L0 契约尚不能安全投入下游接入:第一,新模块在全仓无任何生产调用方且既有前端客户端 parseConfiguredSshHostCatalog 会静默丢弃附加的 observation 字段;第二,额度交接评估在 availability 为 available 或 exhausted 时与 decodeSessionQuotaWindowObservation 的 handover_eligible 规则相互矛盾;第三,按子串匹配 sk- 的硬编码黑名单会误杀合法 SSH 主机别名(如 desk-box)与模型名;第四,新增 5 组闭集词表未对齐现有 CHAT_SESSION_MODE 属主或语义注册表。
本 PR 明确不搬迁第二套前端壳层或 Node SQLite 守护进程,也不修改 codex_attached_api.py 与常驻 SSH 进程监督逻辑。

改动思路 / Approach

收敛选项 核心路径 当前 PR(096c7a7d7a)落地点与核验差距
方案 C(拒绝) 独立 apps/workbench / calli-workbench + Node 守护进程 引入第二套导航、样式与任务权威;本 PR 通过 RFC 明确拒绝
方案 B(选定) 独立 L0 契约模块 session_quota_fabric.ts + 后续嵌入 GoalAgentWorkPage 仅落地无调用方的纯 TS 文件:/ssh-hosts 仍由 Python 产出,Dashboard 客户端剥离除 alias 外所有字段,且存在 available/exhausted 判定矛盾与 sk- 子串误杀

将多主机观测与额度交接从庞大的第二套前端壳层解耦为独立 L0 控制面契约是正确的架构收敛方向,但当前实现在没有任何真实生产调用方的情况下提前落地了与现有前端解析器断链、内部资格判断自相矛盾、且通过脆弱子串黑名单误杀合法输入并重复定义未注册词表的孤立编解码文件。
当前 PR 应作为有价值的收敛 RFC 优先对齐语义注册表与既有属主,并修复交接一致性漏洞、子串误杀与生产接入边界(至少将 observation 投影与 handover 校验挂接到真实控制面入口或经验证的消费契约),而不是合入一个无调用方且存在逻辑漏洞的 TypeScript 模块。

从控制面职责划分看,loopx/control_plane/status/ssh_host_catalog.py 已经承担 /ssh-hosts(ssh_host_catalog_v0)的唯一生产产出,而 loopx/control_plane/effect_runtime_handlers.ts 是 Python 控制面调用 TypeScript 纯决策核的统一注册入口。本 PR 仅在 loopx/control_plane/collaboration/session_quota_fabric.ts 编写纯函数,既未注册到 effect_runtime_handlers.ts,也未与 apps/presentation/dashboard/src/data/ssh-host-catalog.ts 的消费者投影对齐,属于典型的“无生产调用方的孤立编解码层”。

具体改动 / Changes

对照既有核心契约 docs/architecture/rfcs/agent-session-execution-modes-v0.md(基线修订 31944d835466c29f18f843ea92de75b49e7c0c62)及 #8778 评审讨论中的收敛目标映射如下:

  • SESSION-MODE-EXPLICIT(managed_runtime / attached_host 模式显式持久化且禁止隐式切换):not_met — 虽然 evaluateGovernedSessionHandover 拒绝跨模式切换,但 SESSION_FABRIC_EXECUTION_MODES 重复定义了 loopx/chat_store.py 已有的 CHAT_SESSION_MODE_MANAGED / CHAT_SESSION_MODE_ATTACHED,且未绑定至既有绑定/租约校验入口。
  • L0-SSH-CATALOG-PARITY(复用 ssh_host_catalog_v0 并在关闭态保持 { alias } 字节级对等):not_met — projectSshHostCatalogPayload 仅存在于无调用方的 TypeScript 模块中,一方面因 FORBIDDEN_SECRET_PATTERNS 含 "sk-" 子串拒绝了 ssh_host_catalog.py 合法放行的别名(如 desk-box),另一方面现网消费者 parseConfiguredSshHostCatalog 仍会丢弃所有 observation 字段。
  • L0-QUOTA-HANDOVER-GATE(未知额度 fail-closed、遵守共享 Gate 与 Turn/租约围栏):not_met — evaluateGovernedSessionHandover 在 availability === "available" 且 used_ratio >= threshold_ratio 时仍误放行交接,并在 availability === "exhausted" 且 used_ratio < threshold_ratio 时错误拒止交接,与 decodeSessionQuotaWindowObservation 的 handover_eligible 语义冲突。
  • RFC-CONVERGENCE-DOCS(双语收敛 RFC 论证 A/B/C 方案取舍并同步索引):implemented — docs/architecture/rfcs/session-and-quota-fabric-v0.md 与 .zh-CN.md 同步更新 README.md、STATUS.md 与 STATUS.zh-CN.md,并通过 check_rfc_bilingual.py 与 docs-governance-smoke.py。

关键代码讲解

  1. assertPublicSafeText(loopx/control_plane/collaboration/session_quota_fabric.ts):对 alias、profile_id、goal_id、todo_id、agent_id 与 eligible_models[] 执行不区分大小写的子串包含检查 FORBIDDEN_SECRET_PATTERNS(含家目录路径前缀、.ssh/、"sk-"、"ghp_"、"bearer ")。因 "sk-" 未做词边界或前缀锚定,任何合法主机别名或标识中的 "desk-"、"task-"、"disk-"、"flask-"、"kiosk-" 均会被当成凭据拒绝。
  2. projectSshHostCatalogPayload(loopx/control_plane/collaboration/session_quota_fabric.ts):校验主机别名列表后将 decodeSshHostObservation 解码结果增量并入 hosts 数组,遇到未配置别名或重复观测时抛 EffectRuntimeRequestError。但在实际代码库中 /ssh-hosts 仅由 Python ssh_host_catalog.py 服务,且前端 ssh-host-catalog.ts 只保留 { alias },该函数目前没有任何生产调用方。
  3. decodeSessionQuotaWindowObservation(loopx/control_plane/collaboration/session_quota_fabric.ts):校验不透明 profile_id(拒绝 @ 与 /)、availability 四态及 used_ratio 范围(unknown 时强制 null),并显式推导 handover_eligible: availability === "near_limit" || availability === "exhausted"。
  4. evaluateGovernedSessionHandover(loopx/control_plane/collaboration/session_quota_fabric.ts):禁止 from_session_mode !== to_session_mode 与同 profile_id 交接,并按 ask_before_switch(user_gate_required)和 current_turn_fenced && previous_lease_released(await_turn_fence -> ready_for_lease_reacquisition)做前置判断。但其第 302 行只判断 observation.availability === "unknown" || (observation.used_ratio ?? 0) < threshold,完全忽略了第 253 行已计算出的 observation.handover_eligible。

对主干的风险 / Risks

阻塞问题 1:evaluateGovernedSessionHandover 与 decodeSessionQuotaWindowObservation 对 available / exhausted 的交接资格判断自相矛盾

  • Problem: decodeSessionQuotaWindowObservation(L253)规定只有 near_limit 与 exhausted 具备交接资格(handover_eligible: true),但 evaluateGovernedSessionHandover(L302)完全不检查 observation.handover_eligible 或 available / exhausted 状态,只判断 availability === "unknown" || (observation.used_ratio ?? 0) < threshold。
  • Evidence: 对精确头运行反例实测:
    • 当传入 availability: "available", used_ratio: 0.95, threshold_ratio: 0.9(处于可用态)时,解码结果为 handover_eligible = false,而 evaluateGovernedSessionHandover 却输出 disposition: "ready_for_lease_reacquisition", ready_for_reacquisition: true(越权触发交接);
    • 当传入 availability: "exhausted", used_ratio: 0.5, threshold_ratio: 0.9(例如触发硬限流或日额度归零但窗口占比低于阈值)时,解码结果为 handover_eligible = true,而 evaluateGovernedSessionHandover 却输出 disposition: "no_handover_needed", ready_for_reacquisition: false(将已耗尽的会话卡死在无交接状态)。
  • Impact: 下游接入时会在可用状态下错误切号,并在按次数/余额硬耗尽场景下拒绝切换导致长程任务饥饿。
  • Fix: 在 evaluateGovernedSessionHandover 中统一依据 observation.availability 与 threshold_ratio 协同判定(unknown 与 available(除非契约明确规定)不得触发切换,或显式复用 observation.handover_eligible 并在 exhausted 时直接进入交接门控),并补充上述两项反向单元测试。重跑命令:node --no-warnings --experimental-sqlite --experimental-strip-types --test tests/control_plane_ts/session_quota_fabric.test.ts。

阻塞问题 2:assertPublicSafeText 的 "sk-" 子串匹配会拒绝合法 OpenSSH 主机别名与模型名称

  • Problem: FORBIDDEN_SECRET_PATTERNS(session_quota_fabric.ts:61,103)通过 .includes("sk-") 拦截密钥,同时作用于 SSH alias、profile_id、goal_id、todo_id、agent_id 与 eligible_models[]。
  • Evidence: 反例实测 projectSshHostCatalogPayload(["desk-box"]) 直接抛出 EffectRuntimeRequestError: configured_aliases[0] must not contain private paths or credentials。同理,任何包含 desk-、task-、disk-、flask-、kiosk- 的合法 ~/.ssh/config Host 别名或标识符都会被误杀,而基线 loopx/control_plane/status/ssh_host_catalog.py 对 desk-box 完全放行,破坏 ssh_host_catalog_v0 基线兼容性。
  • Impact: 正常用户的 SSH 别名或含 task- 前缀的 ID 接入该契约即发生阻断式误报拒绝。
  • Fix: 改用明确的边界或前缀/token 格式校验(如仅拒绝独立边界开头的 sk- / sk-proj- / sk-ant- 等真实凭据前缀模式或将敏感检测限定于前缀位置),并补充 desk-box、task-worker 等负向放行回归测试。重跑命令:node --no-warnings --experimental-sqlite --experimental-strip-types --test tests/control_plane_ts/session_quota_fabric.test.ts。

阻塞问题 3:scope_fit 未满足——模块在生产路径无任何调用方,且既有 SSH 前端解析器会丢弃 observation

  • Problem: 全仓检索 session_quota_fabric 仅在 tests/control_plane_ts/session_quota_fabric.test.ts 中出现;loopx/control_plane/effect_runtime_handlers.ts 未注册任何处理器,loopx/control_plane/status/ssh_host_catalog.py(唯一服务 /ssh-hosts 的后端)未接入该契约,且 apps/presentation/dashboard/src/data/ssh-host-catalog.ts:27-33 的 parseConfiguredSshHostCatalog 只映射 [{ alias }] 而主动丢弃所有额外字段。
  • Evidence: rg -n "session_quota_fabric" 仅命中本文件与自身单测;RFC §4 自述将 session_quota_fabric.ts 归为 M0 已交付边界,但 scope_fit 规则要求新增控制面契约模块具备真实生产调用入口或明确的兼容契约,仅靠单元测试覆盖不构成可交付行为。
  • Impact: 合入一个没有任何现网调用方、且与当前前端解析器和后端 /ssh-hosts 路径尚未打通的孤立文件,容易在 M1/M2 到来前产生契约漂移(正如当前 desk-box 与 available/exhausted 问题未暴露在真实链路中)。
  • Fix: 至少将 L0 编解码/投影通过 loopx/control_plane/effect_runtime_handlers.ts 注册为真实的内部处理器(或同步在 ssh-host-catalog.ts 对齐可选 observation 透传测试),若定位为纯设计提案阶段则应先只保留收敛 RFC 并延迟死代码落地。重跑命令:npm run typecheck:control-plane && node --no-warnings --experimental-sqlite --experimental-strip-types --test tests/control_plane_ts/session_quota_fabric.test.ts。

阻塞问题 4:repository_reuse 与 semantic_alignment——新增 5 组闭集词表既重复既有名词又未完成语义注册

语义与 CI 对齐

  • Problem: scripts/generate_semantic_inventory.py --changed-from 31944d835466c29f18f843ea92de75b49e7c0c62 在 session_quota_fabric.ts 检出 5 个未注册的 typescript_const_array 词表候选:SESSION_FABRIC_EXECUTION_MODES(managed_runtime, attached_host)、SESSION_FABRIC_HANDOVER_DISPOSITIONS、SESSION_FABRIC_QUOTA_AVAILABILITIES、SESSION_FABRIC_SSH_CONNECTION_STATES、SESSION_FABRIC_SSH_FAILURE_CODES。
  • Evidence: 其中 SESSION_FABRIC_EXECUTION_MODES 与 loopx/chat_store.py:50-51 的既有权威常量 CHAT_SESSION_MODE_MANAGED = "managed_runtime" / CHAT_SESSION_MODE_ATTACHED = "attached_host" 完全重义重复;而 RFC 将本模块定位为 Python 与 TypeScript 跨运行时 M0/M1/M2 共享契约,却未在 loopx/semantics/vocabulary_v0.json 中登记这些跨端词表或记录单源归属。此外,本模块在 session_quota_fabric.ts:59 再次复制了 SAFE_HOST_ALIAS 正则(已存在于 ssh_host_catalog.py:11 与 ssh-host-catalog.ts:12)。
  • Impact: 后续 M1 Python 端接入时极易出现手写字符串漂移或双权威定义。
  • Fix: 在 loopx/semantics/vocabulary_v0.json(及 docs/architecture/rfcs/semantic-vocabulary-convergence-v0.md 锚点)中显式登记或复用现有 session_mode 属主,说明每个新增闭集归属并消解 generate_semantic_inventory.py 候选决策。重跑命令:uv run --extra test python examples/semantic-vocabulary-drift-smoke.py && uv run --extra test python -m pytest -q tests/architecture/test_semantic_vocabulary_drift.py。

我的整体评价 / Verdict

  • 长程与用户体验影响(outcome_impact):long_horizon = regression、user_experience = not_yet_proven(visual_review = not_applicable,理由:本 PR 仅新增 TypeScript 契约文件与 RFC 文档,未修改 apps/presentation/dashboard 等任何渲染页面;unverified_scope = none)。如果下游按当前代码接入,exhausted 且 used_ratio < threshold 的会话会被错误判定为 no_handover_needed 而长期饥饿卡死,而 desk-box 等合法 SSH 主机别名会被 sk- 子串规则错误拦截。
  • 兼容性、代码体积与工程比例:compatibility_assessment = not_yet_proven(声称与 ssh_host_catalog_v0 对等但未在现网消费路径打通且因 sk- 子串破坏既有合法别名集),code_volume = partly_avoidable,change_proportionality = disproportionate、architecture_assessment = simplify_now、default_off_isolation = not_isolated(合法基线别名 desk-box 在调用投影时即崩溃)、authority_semantics = aligned。
  • 本地与 CI 验证汇总:
    • npm run typecheck:control-plane:PASS
    • node --no-warnings --experimental-sqlite --experimental-strip-types --test tests/control_plane_ts/session_quota_fabric.test.ts:PASS(4 passed, 0 failed)
    • uv run --extra test python scripts/check_rfc_bilingual.py --base 31944d835466c29f18f843ea92de75b49e7c0c62 --head HEAD:PASS
    • uv run --extra test python scripts/generate_rfc_status_index.py --check & examples/docs-governance-smoke.py:PASS
    • uv run --extra test loopx canary premerge --tier quick --from-git-diff --git-diff-base 31944d835466c29f18f843ea92de75b49e7c0c62:PASS(3 catalog canaries + public boundary passed, failures=0)
    • uv run --extra test python -m pytest -q --no-cov tests/architecture/test_semantic_vocabulary_drift.py -k test_semantic_vocabulary_registry_matches_the_code:PASS(1 passed),但 scripts/generate_semantic_inventory.py --changed-from 31944d83... 报出 5 个未登记闭集候选。
    • 精确头反例测试(desk-box 别名、available 高占用与 exhausted 低占用):FAIL(复现误杀与交接逻辑矛盾)。
    • 远端 CI 诊断行:checks 因 dashboard-acceptance 被跳过而失败、browser (3/3) 与 chat-bundle-browser (3) 失败(本 PR 未改动浏览器或前端文件)。
  • 语义词表决策:unknown(当前新增 5 个 as const 闭集未在 vocabulary_v0.json 登记,且 SESSION_FABRIC_EXECUTION_MODES 与 chat_store.py 重复)。
  • 后续复审所需证据:修复 available/exhausted 与 handover_eligible 判定一致性、替换 "sk-" 宽泛子串黑名单、打通真实生产调用锚点(或将本 PR 纯化为 RFC 文档切片),并在 vocabulary_v0.json 完成语义词表收敛注册。

English verdict: REQUEST_CHANGES on 096c7a7: evaluateGovernedSessionHandover contradicts decodeSessionQuotaWindowObservation.handover_eligible on available/exhausted windows, FORBIDDEN_SECRET_PATTERNS substring "sk-" rejects valid SSH host aliases like desk-box, session_quota_fabric.ts has zero production callers, and its five new closed-set vocabularies are unregistered/duplicate.

…ingle-workbench convergence

Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
Signed-off-by: LoopX Agent <337587101+loopx-agent@users.noreply.github.com>
@loopx-agent
loopx-agent force-pushed the codex/calli-session-fabric-convergence-20261117 branch from 096c7a7 to a88a364 Compare November 19, 2026 20:16

@loopx-agent loopx-agent left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewer: model_agent · Gemini · Google (self_reported)
Approval conclusion (author-owned PR; GitHub blocks formal self-approval)

动机 / Motivation

面向用户与触发任务: 在单一 Goal 工作台与多配置会话管理场景中,需要选择本机配置好的 SSH 主机并在账户配额临近耗尽时执行受治理切换的操作者,以及调用 ssh_host_catalog_v0 与 effect_runtime_handlers 的前端和 Python 控制面调用方。

改前改后场景与实际代价: 改动前,工作台与协调草案若直接叠加独立壳层或散落子串过滤,既会把含 sk- 子串的合法 OpenSSH 别名(如 desk-box、task-worker)误杀或缺少标准化的 SSH 失败码与配额窗口结构,又可能在配额仍处于 available 但使用率较高时误触发交接,或缺少 effect_runtime 与工作台的数据透传路径;改动后,通过共享的零导入 L0 契约与已注册 effect_runtime 处理器,调用方在未传入 L0 观测数据时保持完全一致的 { alias } 兼容输出,仅在显式提供观测数据时输出经校验的 observation 并严格按 handover_eligible 与 availability 计算交接门禁与回合围栏。

可观测改进与边界: 新增并接入零导入 L0 会话与配额契约(7 类 SSH 失败码、4 类配额状态、4 类交接处置与边界锚定脱敏校验),注册两个 collaboration.session_fabric.* 运行时操作并在 Python ssh_host_catalog_payload(..., observations=...) 与前端 parseConfiguredSshHostCatalog 完成可验证透传;未传 observations 时输出与基线字节级等价,传入异常凭证、跨别名或矛盾配额状态时 fail-closed 拒绝。 本 PR 不引入新的独立前端应用或后台 SSH/配额守护进程,不自动执行远程 ssh 探测、配额抓取或跨 attached_host/managed_runtime 静默切流,也不直接修改现网租约或自动合并工作。

当前增量定位与剩余缺口: L0 静态契约、runtime handler 注册、可选 observations 投影及默认关闭兼容性已在当前提交落地;实际 SSH 探针采集进程、真实账号配额窗抓取器以及工作台前端的交互面板渲染留在后续增量中接入。

改动思路 / Approach

本 PR 按「纯契约单源 -> 受控运行时边界 -> 默认关闭生产透传」组织,入口和所有权清晰:

  1. 单源纯契约层(session_quota_fabric_contract.ts):统一托管 SAFE_HOST_ALIAS、isSafeHostAlias、assertPublicSafeFabricText、SESSION_MODES、4 组 Fabric 闭合枚举以及与宿主运行时无关的 decodeSshHostObservationWith,供 Node test、前端 CommonJS smoke 与控制面复用,消除跨层正则/枚举副本。
  2. 策略与状态计算层(session_quota_fabric.ts):projectSshHostCatalogPayload 与 projectSshHostCatalogRequest 只对显式传入且在 configured_aliases 白名单内的主机合并观测,evaluateGovernedSessionHandover 只基于输入状态做纯计算,不触发网络或租约变更。
  3. 运行时注册与生产接线(effect_runtime_handlers.ts、ssh_host_catalog.py、ssh-host-catalog.ts):在 handler 注册表绑定两项延迟加载操作;Python ssh_host_catalog_payload 在 observations 缺失或为空时直接走纯 Python 原路径返回 { alias },仅在显式提供 observations 时才调用 TypeScript 所有者投影;前端解析器则在同一条读取链上按需校验并保留 observation 字段。

架构合理性与当前边界: 将纯编码器、正则与受约束词汇抽离到零导入 session_quota_fabric_contract.ts,由控制面逻辑与前端 dashboard 共用同一套校验真理,避免多处复制正则;运行期仅在显式请求时经 effect_runtime 调度,保持热路径与默认关闭路径零开销、无外部 I/O 副作用。 当前 PR 边界限定为 L0 纯契约校验、effect_runtime 处理器注册、ssh_host_catalog_v0 可选 observations 透传以及双语 RFC/语义词表对齐,不涉及远程 SSH 主动探测或 UI 视图组件改动。 所有状态均由调用方观测快照或主机配置显式推导,不存在隐式全局状态、后台常驻轮询或静默故障降级;若传入未知别名、格式错误的时间戳、非法 used_ratio 或越界路径/凭证,各层统一 fail-closed 抛错。

具体改动 / Changes

修订基准与核查条目: 对照前序评审基线 https://github.com/loopx-project/loopx/pull/8886#pullrequestreview-5948223455(对应审查基线修订 096c7a7d7a03c95731f8d29361b160777d857942)逐条核实,RF-1、RF-2、RF-3、RF-4 四项阻塞问题在当前精确提交 a88a364b6acc4da1c00ab5a0b13a7c5fed865212 均已修复闭环:

  • RF-1(交接资格与配额状态一致性):evaluateGovernedSessionHandover 先校验 !observation.handover_eligible(unknown/available 恒返回 no_handover_needed),再将 near_limit 约束为 (used_ratio ?? 0) >= threshold_ratio,而 exhausted 即使 used_ratio < threshold_ratio 也会进入 user_gate_required / await_turn_fence / ready_for_lease_reacquisition。
  • RF-2(替换朴素 "sk-" 子串检测并单源化 SAFE_HOST_ALIAS):改用词/分隔符边界锚定的凭证与敏感路径正则,并统一复用 session_quota_fabric_contract.ts::SAFE_HOST_ALIAS,允许 desk-box、task-worker、disk-01、kiosk-2 等合法 OpenSSH 别名同时阻断真实私钥前缀与本机路径。
  • RF-3(真实生产接线与默认关闭 { alias } 等价):在 effect_runtime_handlers.ts 注册 collaboration.session_fabric.project_ssh_host_catalog 与 collaboration.session_fabric.evaluate_governed_session_handover,通过 ssh_host_catalog.py 可选 observations 参数与 dashboard/src/data/ssh-host-catalog.ts 完成端到端透传并保留未启用时的等价性。
  • RF-4(语义词表与双语 RFC 对齐):复用 loopx/chat_store.py::CHAT_SESSION_MODES 对应的规范词表 session_mode(managed_runtime、attached_host),在 loopx/semantics/vocabulary_v0.json 与双语 RFC(session-and-quota-fabric-v0.md/.zh-CN.md)完整注册并同步术语与测试。

关键代码讲解

  1. loopx/control_plane/collaboration/session_quota_fabric_contract.ts::assertPublicSafeFabricText(第 101 行)与 SAFE_HOST_ALIAS(第 48 行):使用边界锚定模式检测私有绝对路径与 sk-...、ghp_、github_pat_、bearer 凭证,避免子串误判并让控制面与前端共用同一个 isSafeHostAlias 与 decodeSshHostObservationWith 解码器。
  2. loopx/control_plane/collaboration/session_quota_fabric.ts::evaluateGovernedSessionHandover(第 201 行):强制校验 from_session_mode === to_session_mode 防止静默切换执行模式,先判 !observation.handover_eligible 再区分 near_limit 阈值比较与 exhausted 无条件门禁/围栏判定(ask_before_switch -> current_turn_fenced && previous_lease_released)。
  3. loopx/control_plane/status/ssh_host_catalog.py::ssh_host_catalog_payload(第 108 行)与 project_ssh_host_catalog(第 85 行):默认 observations=None 时零依赖返回 {"ok": True, "schema_version": "ssh_host_catalog_v0", "hosts": [{"alias": alias}]};仅在传入非空 observations 时才通过 effect_runtime_result("collaboration.session_fabric.project_ssh_host_catalog", ...) 委托 TypeScript 所有者校验合并。
  4. apps/presentation/dashboard/src/data/ssh-host-catalog.ts::parseConfiguredSshHostCatalog(第 24 行):复用同一零导入解码器校验可选 record.observation,强制要求 observation.alias === alias 并在未提供或为 null 时保持纯 { alias } 输出结构。
  5. loopx/control_plane/effect_runtime_handlers.ts(第 700–701 行):注册按需懒加载的两个 collaboration.session_fabric.* handler,确保未触发该能力时零额外模块加载成本。

对主干的风险 / Risks

  • 负向与失效边界分析:
    • 若 observation.alias 不在已配置 SSH host 白名单内、observation.alias !== alias、携带重复观测或含私有路径/sk-... 凭证,TS 与前端解码器均在边界处直接抛错阻断(EffectRuntimeRequestError / ValueError / Error),不会污染白名单或透传伪造别名。
    • 若跨调用传递不一致的 from_session_mode !== to_session_mode、相同 from/to profile、未满足回合围栏/租约释放或 availability === "unknown",交接判定严格 fail-closed 拒绝或阻断 ready_for_reacquisition: true。
  • Default-Off 隔离与生产调用归属(scope_fit): 默认不传 observations 时,ssh_host_catalog_payload 与 parseConfiguredSshHostCatalog 的输出字段与改动前 { alias } 严格一致且不启动 Node effect_runtime;生产调用路径已通过已注册的 effect_runtime_handlers.ts、Python status 目录及 dashboard 数据解析器闭环接入。
  • 权限语义(authority_semantics): 公开 Schema(session_fabric_ssh_observation_v0、session_quota_window_observation_v0、governed_session_handover_proposal_v0、governed_session_handover_result_v0)只描述只读观测与交接前置评估,不授予后台独立执行、租约抢占或静默切流权限。
  • 本地验证与比例性评价: 改动集中在 L0 契约、单源复用、两个运行时 handler 与测试/双语文档(20 文件 +1801/-40,主体为契约测试、RFC 与词表 JSON),与解决多 PR 架构分叉及修复审查 5948223455 4 项阻塞结论的目标成比例。

语义与 CI 对齐

  • 受影响共享词表为既有 session_mode(复用 loopx/chat_store.py::CHAT_SESSION_MODES)以及新增的 4 个 Fabric 闭合枚举(session_fabric_ssh_connection_state、session_fabric_ssh_failure_code、session_fabric_quota_availability、session_fabric_handover_disposition),全部登记于 loopx/semantics/vocabulary_v0.json 与 docs/reference/glossary.md。
  • 在 a88a364b6acc4da1c00ab5a0b13a7c5fed865212 上执行 scripts/generate_semantic_inventory.py --changed-from origin/main(6 个候选载体 100% 精确匹配已登记词表,0 未注册项)与 examples/semantic-vocabulary-drift-smoke.py(34/34 词表、62/62 归属符号)均通过。
  • 双语 RFC diff 检查 scripts/check_rfc_bilingual.py --base origin/main --head HEAD 通过;注:scripts/generate_rfc_status_index.py --check 与 examples/docs-governance-smoke.py 当前在基线 origin/main 上存在既有的无关前置失败(monorepo-distribution-split-v0.md/.zh-CN.md 日期标题应置于 ledger/),本 PR 自身新增 RFC 与 STATUS 索引及 tests/architecture/test_rfc_status_index.py(13 passed)均通过。

我的整体评价 / Verdict

  • 目标收益与权衡: 对长程可靠性(long_horizon)与开发者/操作者体验(user_experience)均构成正向收敛——把多套冲突工作台方案收口到现有单工作台 L0 契约与既有 effect_runtime / ssh_host_catalog_v0 边界上,显著降低后期多壳并行与跨层正则分叉风险。
  • 视觉检查说明(visual_review): 本次仅修改 dashboard 数据解析模块 apps/presentation/dashboard/src/data/ssh-host-catalog.ts 及其 smoke 测试,未修改任何页面布局、样式或可渲染 UI 组件。 未验证范围:无新增可渲染前端视觉界面;dashboard 数据解析与默认关闭等价性已通过 tsc --noEmit 与 npm run smoke:status-sources 验证。
  • 兼容性、体量与边界总结: 复用既有 session_mode 与 ssh_host_catalog_v0 所有权,default_off_isolation 验证默认关闭路径零行为漂移;authority_semantics 与公开边界对齐;未见冗余抽象或过度膨胀。
  • 当前精确头校验汇总(a88a364b6acc4da1c00ab5a0b13a7c5fed865212):
    • npm run typecheck:control-plane:通过;node --experimental-strip-types --test(session_quota_fabric + effect_runtime_handler_loading + content_digest_single_owner):29 passed, 0 failed。
    • Dashboard tsc --noEmit && npm run smoke:status-sources:status source catalog smoke: ok。
    • pytest(架构词表/导入边界/RFC 索引/ssh_hosts/broker/effect_runtime):452 passed, 1 skipped(tests/control_plane/test_effect_runtime_integration.py:75 Linux-only 用例在 macOS 跳过)。
    • ruff check 与 mypy --strict --follow-imports=silent(修改的 Python 生产及测试文件):0 错误;loopx check --scan-path(全部 20 个改动文件):ok=true, errors=0, public_boundary_scan.ok=true;Goal 绑定 CQR(cqr_a99f3fe45b253b53dd23)与 canary premerge --tier quick 全部通过;未等待远程 CI(遵循目标策略 wait_for_ci: false)。
  • 残余风险: 低(仅待后续增量接入真实 SSH/配额采集器,且基线 origin/main 的无关 RFC ledger 报错需由对应 RFC PR 单独修复)。

English verdict: APPROVE — All four blocking findings from review 5948223455 are verified resolved on exact head a88a364: handover evaluation strictly honors handover_eligible and availability counterfactuals, assertPublicSafeFabricText uses boundary-anchored patterns sharing SAFE_HOST_ALIAS, typed effect_runtime handlers wire cleanly through Python ssh_host_catalog_payload and dashboard parseConfiguredSshHostCatalog with byte-identical { alias } default-off parity, and semantic vocabularies reuse session_mode with 0 unregistered carriers. Local TS/Node, dashboard, pytest (452 passed, 1 macOS-skipped Linux-only case), ruff, strict mypy, bilingual RFC diff, public-boundary scan, CQR, and canary premerge quick-tier all passed on this head.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant