q2c 0.1.1__py3-none-any.whl

q2c/__init__.py

@@ -0,0 +1,27 @@
+"""q2c — 可靠的 AI 编码 Agent 交接桥（协议 q2c/1；版本号只在 q2c/_version.py 一处）。
+
+产品边界（PROTOCOL.md §0）：q2c 保证**交接**，不保证**结果**。
+本包只含传输事实：投递／关联／幂等／送达确认／重投／会话映射／适配器／产物引用／
+传输恢复／通信跟踪／传输安全。工作流状态、项目调度、CI 真相、代码质量判断、
+评审批准、放行决定一律不在本包（分类依据见仓库根 Q2C-BOUNDARY-AUDIT.md）。
+"""
+
+from .protocol import (  # noqa: F401
+    PROTOCOL_VERSION,
+    ENVELOPE_FIELDS,
+    MESSAGE_TYPES,
+    TRANSPORT_STATES,
+    TERMINAL_STATES,
+    FAILURE_CLASSES,
+    ARTIFACT_TYPES,
+    FORBIDDEN_VALUES,
+    ProtocolError,
+    Envelope,
+    ArtifactRef,
+    make_request,
+    next_state,
+)
+
+from ._version import __version__  # 唯一真源在 q2c/_version.py（打包从这里取，别再写一遍）
+
+__all__ = ["__version__", "PROTOCOL_VERSION"]

q2c/__main__.py

@@ -0,0 +1,8 @@
+"""`python3 -m q2c …` 的入口。与 `bin/q2c` 等价。"""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

q2c/_version.py

@@ -0,0 +1,16 @@
+"""版本号的**唯一真源**。
+
+为什么单独一枚文件（2026-10-04）：`pyproject.toml` 与 `q2c/__init__.py` 原先各写了一遍
+`0.1.0`。那是双真源——发版时改一处忘一处，PyPI 上标的版本和代码里跑的版本就不是同一个，
+而 `q2c version` 打出来的还是"看着对"的那一个，没人会发现问题。
+
+现在 `pyproject.toml` 用 `[tool.setuptools.dynamic] version = {attr = "q2c._version.__version__"}`
+**从这一行取**，不再自己写。取的是字面量（setuptools 走 AST 读，不 import），
+所以这个文件必须只有一行赋值、不许 import 别的东西——
+`tests/test_packaging.py::test_dynamic_version_resolves_to_the_one_literal` 钉的就是这个形状。
+
+协议版本不在这里：`q2c/1` 由 `q2c/protocol.py::PROTOCOL_VERSION` 单独管（两者编号独立，
+见 PROTOCOL.md §9 与 CHANGELOG 抬头那句）。
+"""
+
+__version__ = "0.1.1"

q2c/ack.py

@@ -0,0 +1,297 @@
+#!/usr/bin/env python3
+"""送达确认（transport ACK）的判据。
+
+分工写死在这里，因为混过一次：
+  · **适配器**负责"把对侧的回执解析成事实"（provider 的字段名、JSONL 形状都在适配器里）；
+  · **本模块**负责"这些事实够不够格叫送达"（六条判据，PROTOCOL.md §4.2）。
+判据放核心、解析放适配器，是为了让六条规则对 Codex 与 Qoder 是**同一套尺**，
+也让"摘掉某一条闸"这种反证能落在一个确定的位置。
+
+四条来自真事故的形状判据（不是质量判断）：
+
+- **退 0 ≠ 送达**：`/bin/true` 也退 0，它什么人都没叫到。
+- **结构化字段，不是子串**：正文里出现过 `ACKED`、或出现字面量 `"type":"result"`，
+  都不构成成功证据（真反例：`is_error=true`、退出码 7、正文同样带着 ACKED 的回执）。
+- **身份要相等**：回执自报的会话号必须等于我要送达的那一个，拿别人的"成功"顶替不算。
+- **绑定串要逐字整行回出**：不回＝证明不了它核读的是本轮那一份（复述上一轮形状一样能全对）。
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+ACK_TOKEN = "ACKED"
+BIND_PREFIX = "Q2C-BIND"
+BIND_LABEL = BIND_PREFIX + ":"
+# 绑定行的**唯一**写法：`Q2C-BIND: <nonce>` 独立整行。
+# 只留一种形状是有意的：上一版同时认 "BIND: " 与 "REVIEW-BIND: "，
+# 于是"少写一个前缀"这种漂移不会被发现。
+BIND_PREFIXES = (BIND_LABEL + " ",)
+
+# 六条判据的失败原因码（写进 trace 的 failure_class 之外的细项，便于人查）
+REASON_OK = "ok"
+REASON_RC = "NONZERO_EXIT"
+REASON_NO_RECORD = "NO_STRUCTURED_RECORD"
+REASON_SELF_ERROR = "RECEIVER_REPORTS_FAILURE"
+REASON_SESSION = "SESSION_IDENTITY_MISMATCH"
+REASON_NO_ACK_LINE = "ACK_LINE_MISSING"
+REASON_BIND = "BIND_NOT_ECHOED"
+REASON_TERMINAL = "NO_TERMINAL_EVENT"
+
+TERMINAL_COMPLETED = "completed"
+TERMINAL_FAILED = "failed"
+TERMINAL_ABSENT = "absent"
+TERMINAL_UNKNOWN = "unknown"
+TERMINAL_NOT_PROVIDED = ""      # 这一腿的对侧不提供终态证据（桩对侧就是这种）
+
+
+@dataclass
+class Receipt:
+    """适配器交回的一份"对侧回执事实"。
+
+    注意每个字段都是**事实**，不是结论：`self_reported_success` 是"对侧自己说它成功了"，
+    不是"这件事成功了"。是否采信由 `judge_ack` 判。
+    """
+
+    returncode: int | None = None
+    has_structured_record: bool = False
+    self_reported_success: bool = False
+    reported_session_id: str = ""
+    ack_line_present: bool = False
+    bind_echo: str = ""
+    result_body_present: bool = False
+    detail: str = ""
+    terminal: str = ""            # 对侧这一轮的收口读数：completed／failed／absent／unknown
+    body: str = ""                # 对侧答复的**原文**（从结构化记录里解出来的那一段）
+    rid: str = ""                 # 回执自报的请求号（通知通道用它证明"指名到这一笔"）
+    extra: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        return {
+            "returncode": self.returncode,
+            "has_structured_record": self.has_structured_record,
+            "self_reported_success": self.self_reported_success,
+            "reported_session_id": self.reported_session_id,
+            "ack_line_present": self.ack_line_present,
+            "bind_echo": self.bind_echo,
+            "result_body_present": self.result_body_present,
+            "terminal": self.terminal,
+            "body_bytes": len(self.body.encode("utf-8")),
+            "rid": self.rid,
+            "detail": self.detail,
+        }
+
+
+def full_lines(text: str) -> list:
+    return [ln.strip() for ln in (text or "").splitlines()]
+
+
+def has_ack_line(text: str) -> bool:
+    """要求**独立整行**等于 `ACKED`（去掉首尾空白后逐字相等）。"""
+    return ACK_TOKEN in full_lines(text)
+
+
+def extract_bind_echo(text: str) -> str:
+    """取逐字整行回出的那枚绑定串；带尾巴的、写在句子中间的都不算。"""
+    for ln in full_lines(text):
+        for pref in BIND_PREFIXES:
+            if ln.startswith(pref):
+                return ln[len(pref):].strip()
+    return ""
+
+
+def last_structured_record(stdout: str, want_type: str = "result") -> dict | None:
+    """从输出里取**最后一条可解析的** JSON 对象（其 `type` 等于 `want_type`）。
+
+    取"最后一条"是有理由的：CLI 在结果之后还会打话，取第一条会读到开场白。
+    解析失败的行直接跳过——**不返回半成品**，宁可为 `None`（`None` 在判据里是
+    "没有结构化回执"，与"有一个说失败的回执"是两条不同的路）。
+    """
+    rec = None
+    for ln in (stdout or "").splitlines():
+        t = ln.strip()
+        if not t.startswith("{"):
+            continue
+        try:
+            d = json.loads(t)
+        except ValueError:
+            continue
+        if isinstance(d, dict) and (want_type is None or d.get("type") == want_type):
+            rec = d
+    return rec
+
+
+def record_self_reports_success(rec: dict | None) -> bool:
+    """对侧自报成功＝`is_error` 恰为 False **且** `subtype` 恰为 "success"。
+
+    写 `is_error is not False` 而不是 `if rec.get("is_error")`：缺键、`null`、
+    字符串 `"false"` 都不是"没失败"。（真反例里正是缺键与字符串两种形状被旧写法放过。）
+    """
+    if not isinstance(rec, dict):
+        return False
+    return rec.get("is_error") is False and rec.get("subtype") == "success"
+
+
+def judge_ack(Receipt_, target_session_id: str, required_bind: str = "",
+              require_terminal: bool = False, require_ack_line: bool = True) -> tuple:
+    """PROTOCOL.md §4.2 的六道闸 ＋ 终态那一刀。返回 (acked, reason_code, why)。
+
+    顺序有讲究：先便宜的后花钱的；`REASON_RC` 在前是因为非零退出时
+    后面的字段全是不可信半成品。
+
+    `require_terminal` 由适配器的 `capabilities()["terminal_evidence"]` 决定：
+    真 CLI（Codex／Qoder）必须查"这一轮调用收口没有"——R19 独立复验用的就是普通流程复现：
+    事件流以 `turn.failed` 收尾、或根本没有终态，只要进程退 0、正文够长、绑定串对得上，
+    旧版照样登记完成。桩对侧没有事件流可查，不硬要求（否则测一条永远走不到的分支）。
+    """
+    r = Receipt_
+    if r.returncode != 0:
+        return False, REASON_RC, "回执进程退出码 %s" % (r.returncode,)
+    if require_terminal and r.terminal != TERMINAL_COMPLETED:
+        return False, REASON_TERMINAL, "这一轮调用没有合格终态（terminal=%r）⇒ 不采信为送达" % (
+            r.terminal or "未提供",)
+    if not r.has_structured_record:
+        return False, REASON_NO_RECORD, "无可解析的结构化回执（只有散文或被截断的输出）"
+    if not r.self_reported_success:
+        return False, REASON_SELF_ERROR, "对侧自报失败（is_error 非 False 或 subtype 非 success）"
+    if str(r.reported_session_id or "") != str(target_session_id or ""):
+        return False, REASON_SESSION, "会话身份不匹配：回执 %r ≠ 目标 %r" % (
+            r.reported_session_id, target_session_id)
+    if require_ack_line and not r.ack_line_present:
+        return False, REASON_NO_ACK_LINE, "缺约定确认行（要求独立整行 %s，正文含词不算）" % ACK_TOKEN
+    # 本轮派发文里要求过（required_bind 非空）才要回它；要求本身是硬的：
+    # 没有串可回的一律不算（不许把"那就免检"当默认）。
+    if required_bind and r.bind_echo != required_bind:
+        return False, REASON_BIND, "回执没有逐字整行回出本轮绑定串（got=%r want=%r）" % (
+            r.bind_echo, required_bind)
+    return True, REASON_OK, "ok"
+
+
+def scan_terminal(raw: str, completed=("turn.completed",), failed=("turn.failed", "error",
+                                                                   "cancelled")) -> str:
+    """从事件流里取**最后一个**终态读数：completed／failed／absent／unknown。
+
+    只看 `type` 字段落在名单里的那些行；取"最后"而不是"第一个"，因为一轮调用后面
+    可能还有收尾事件。已知局限（写进 ADAPTERS.md，不当能力报）：多轮共用一条流时，
+    这里归给"最后一次终态"，**上一轮的 `turn.completed` 会被这一轮读到**。
+    把这种借证挡在门外的是归属那一刀（本轮绑定串必须逐字回出）：
+    真腿第一跑里 Codex 回的就是**上一轮**那枚串，于是 `BIND_NOT_ECHOED` 拒了整腿
+    （原件 `evidence/real-legs/05-codex-stale-bind-*.txt`，反例格见
+    `tests/test_qoder_terminal_real_fixture.py::TestStaleAttributionFromRealLegs`）。
+    """
+    last = TERMINAL_ABSENT
+    for ln in (raw or "").splitlines():
+        t = ln.strip()
+        if not t.startswith("{"):
+            continue
+        try:
+            d = json.loads(t)
+        except ValueError:
+            last = TERMINAL_UNKNOWN
+            continue
+        if not isinstance(d, dict):
+            continue
+        ty = str(d.get("type") or "")
+        if ty in completed:
+            last = TERMINAL_COMPLETED
+        elif ty in failed:
+            last = TERMINAL_FAILED
+    return last
+
+
+def scan_result_frame_terminal(raw: str, want_type: str = "result") -> str:
+    """**单帧收口**形态的终态读法（与 `scan_terminal` 的事件流词表互不替换）。
+
+    有些对侧 CLI 不是一条事件流，而是最后打一条收口记录：
+    `{"type":"result","subtype":"success","is_error":false,…}` —— Qoder 公开 CLI 就是这种。
+    这里按"最后一条可解析的 `want_type` 记录"判：
+
+      · 自报成功（`record_self_reports_success`）⇒ `completed`；
+      · `is_error` 恰为 True，或 `subtype` 以 `error` 起头 ⇒ `failed`；
+      · 有这条记录但成功／失败读不出来 ⇒ `unknown`（两边都不折）；
+      · 根本没有这条记录 ⇒ `absent`。
+
+    为什么不让它去认 `turn.completed`：那是**另一家的词表**。把两套名单并成一套
+    （`completed=("turn.completed","result")`）看着省一行，实际后果是任何开场白里
+    出现 `{"type":"result"` 字样都会被读成"本轮跑完了"。两枚反例分别由
+    `tests/test_qoder_terminal_real_fixture.py` 的 test_08／test_09 钉住。
+    """
+    rec = last_structured_record(raw, want_type)
+    if rec is None:
+        return TERMINAL_ABSENT
+    if not isinstance(rec, dict):
+        return TERMINAL_UNKNOWN
+    if record_self_reports_success(rec):
+        return TERMINAL_COMPLETED
+    if rec.get("is_error") is True or str(rec.get("subtype") or "").startswith("error"):
+        return TERMINAL_FAILED
+    return TERMINAL_UNKNOWN
+
+
+def judge_result_shape(text: str) -> tuple:
+    """回复本体必须是"结论行＋绑定行之外还有非空正文"。
+
+    这里**没有字数下限**：长度是质量打分，非空是防空口令冒充回执。
+    审计 §C-3 第 5 条记着这个取舍（旧内核写的是 60 字）。
+    """
+    lines = [ln for ln in full_lines(text) if ln]
+    substance = [ln for ln in lines if ln != ACK_TOKEN and not any(ln.startswith(p) for p in BIND_PREFIXES)]
+    if not substance:
+        return False, "只有确认行与绑定行，没有正文"
+    return True, "ok"
+
+
+def receipt_from_cli_json(stdout: str, rc: int | None, want_type: str = "result",
+                          stream_terminal: str | None = None) -> Receipt:
+    """把一次 CLI 调用的 stdout 折成 `Receipt`（适配器与测试共用的参考实现）。
+
+    三个细节都是踩过坑的：
+      1. `ack_line_present`／`bind_echo` 只看**解析出来的那条记录内部**（`result` 字段），
+         不看整段 stdout——"在外面补一行"不能算过关；
+      2. JSON 里的 `result` 要先解码，`REVIEW-BIND`/`Q2C-BIND` 那行躺在字符串内部，
+         按 stdout 的物理行去找永远找不到；
+      3. `reported_session_id` 取记录里的字段，缺字段就当空（身份不相等 ⇒ 拒）。
+    """
+    rec = last_structured_record(stdout, want_type)
+    inner = ""
+    if isinstance(rec, dict):
+        val = rec.get("result")
+        inner = val if isinstance(val, str) else json.dumps(val, ensure_ascii=False)
+    return Receipt(
+        returncode=rc,
+        has_structured_record=rec is not None,
+        self_reported_success=record_self_reports_success(rec),
+        reported_session_id=str((rec or {}).get("session_id") or "") if isinstance(rec, dict) else "",
+        # 只认**解析出来的那条记录内部**。把正确的绑定串写在 JSON 之外的正文里不算过关
+        # （R17 第 4 条实测：旧写法把 stdout 与 result 拼起来找，等于"外面补一行"就能过）。
+        ack_line_present=has_ack_line(inner),
+        bind_echo=extract_bind_echo(inner),
+        result_body_present=bool(inner.strip()),
+        body=inner,
+        # 终态读数必须真的接进回执。2026-10-04 真腿第三跑就是死在这一格缺席：
+        # 这个参数从写下来那天起**没被用过**，于是凡走这条参考实现的腿 `terminal` 恒为 ''，
+        # 声明了 `terminal_evidence=True` 的适配器（Qoder）每次真投递都被终态那一刀判
+        # `NO_TERMINAL_EVENT terminal='未提供'`。传 None 才表示"这一腿不提供终态"。
+        terminal=(TERMINAL_NOT_PROVIDED if stream_terminal is None else stream_terminal),
+        rid=str((rec or {}).get("rid") or "") if isinstance(rec, dict) else "",
+        detail=str((rec or {}).get("subtype") or "") if isinstance(rec, dict) else "",
+    )
+
+
+def judge_notification_receipt(receipt: "Receipt", rc: int | None, request_id: str) -> tuple:
+    """失败通知那一路的送达判定：只认**指名到这一笔**的结构化回执。
+
+    三件同时成立才算送到：退出码 0、末行是可解析 JSON 且自报成功、`rid` 就是这一笔。
+    为什么不让"脚本跑完了"顶替回执：`/bin/true` 也退 0，但它什么人都没叫到——
+    在册那三条 REJECTED 就是死在这种"我叫过了"的自述上。
+    """
+    if rc != 0:
+        return False, "执行器退出码 %s" % (rc,)
+    if not receipt.has_structured_record:
+        return False, "执行器没有给出结构化回执（末行不是 JSON）"
+    if not receipt.self_reported_success:
+        return False, "回执自报失败（is_error 非 False 或 subtype 非 success）"
+    if str(receipt.rid or "") != str(request_id):
+        return False, "回执请求号不匹配：%r ≠ %r" % (receipt.rid, request_id)
+    return True, "ok"

q2c/adapters/__init__.py

@@ -0,0 +1,20 @@
+"""随包适配器注册表。
+
+用法：`from q2c import adapters; adapters.import_builtin(); adapters.build("codex", cfg)`。
+先 `import_builtin()` 再 `build()`，避免"哪个适配器在册"取决于 import 顺序。
+"""
+
+from .base import (  # noqa: F401
+    Adapter,
+    AdapterError,
+    Handle,
+    CONTRACT_METHODS,
+    STATUS_ALIVE,
+    STATUS_GONE,
+    STATUS_UNKNOWN,
+    STATUS_NEVER,
+    build,
+    known,
+    register,
+)
+from .base import import_builtin  # noqa: F401

q2c/adapters/_spawn.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""适配器共用的"起一次外部调用并把落盘件与退出码留住"的两拍工装。
+
+三个设计点都是踩出来的，别在单个适配器里各写一套：
+
+1. **退出码走侧件**（`<capture>.out.rc`）。父进程被杀之后，子进程可能还在跑、
+   最后跑完了也没人 `communicate()` 它；这时唯一能证明"它退了几"的就是它自己写完的侧件。
+2. **绝对解释器包装**（`/bin/zsh -c`）。裸 `zsh` 在受限 PATH 下起不来 ⇒ 捕获件是空的 ⇒
+   很容易被读成"对方没回话"（在册收尾项，产品里就地做掉）。
+3. **到点不杀**。返回 `IN_FLIGHT`，让上层决定等还是取消；超时即杀并记失败，
+   实测会把同一个请求推成两份对象、两枚绑定串、两条互相打脸的答复。
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+import shlex
+import subprocess
+import time
+
+from .. import security
+
+IN_FLIGHT = "IN_FLIGHT"
+DONE = "DONE"
+NO_RC = "NO_RC_RECORD"
+
+# 本进程起过、但还没回收的孩子。到点不杀 ⇒ 我们**故意**不等它，
+# 那它退出后就会挂在进程表里当僵尸；长活的调用者会越攒越多。
+# 所以下面每一条出口都先试着收一次（非阻塞）。
+_LIVE = {}          # pid → Popen：本进程起过、还没收到退出码的孩子
+
+
+def detach(p):
+    """我们**故意**不等的孩子：把 Popen 对象与这个责任解绑。
+
+    `Popen.__del__` 见到"还活着却没有 returncode"就报警。这不是我们的错——
+    到点不杀是协议规定（杀了会把同一请求推成两份对象两枚绑定串）。
+    解绑对象不等于放弃回收：pid 还留在 `_UNREAPED` 里，后续 `reap()` 用裸
+    `waitpid(WNOHANG)` 照样能收，进程表不会攒僵尸。
+    """
+    if p is None:
+        return
+    # `Popen.__del__` 的报警条件是"returncode 还是 None"。我们已经把管道关掉、
+    # 也确定不再对这个孩子负责（回收走 _UNREAPED＋裸 waitpid），所以这里声明
+    # "这个对象不再拥有孩子"——比伪造一个 returncode 干净，也比留着报警正确。
+    try:
+        p._child_created = False
+    except Exception:
+        pass
+
+
+def reap(pid):
+    """尽力回收一枚本进程起过的孩子（非阻塞）。收不到不算错——它可能还在跑。
+
+    走 `Popen.poll()` 而不是裸 `waitpid`：poll 会把退出码落回对象本身，
+    于是解释器回收时不会对着"我们故意没等"的孩子报 ResourceWarning，
+    也不会出现"我们收过、对象却以为孩子是活的"这种两处认知不一致。
+    """
+    if pid in (None, ""):
+        return False
+    p = _LIVE.get(int(pid)) if str(pid).lstrip("-").isdigit() else None
+    if p is None:
+        return False
+    try:
+        rc = p.poll()
+    except OSError:
+        rc = 0
+    if rc is None:
+        return False
+    _LIVE.pop(int(pid), None)
+    return True
+
+
+def reap_all():
+    """把本进程起过、还没收的孩子各试一次。长活的调用方靠它不攒僵尸。"""
+    for pid in list(_LIVE.keys()):
+        reap(pid)
+
+
+def _release_on_exit():
+    """退出兜底：收得掉的收掉；收不掉的声明"这个对象不再拥有孩子"。
+
+    到点不杀是协议规定，所以"还活着的孩子"是正常状态，
+    不该在解释器拆解阶段变成一屏 ResourceWarning。
+    """
+    for pid, p in list(_LIVE.items()):
+        if not reap(pid):
+            detach(p)
+    _LIVE.clear()
+
+
+atexit.register(_release_on_exit)
+
+
+def spawn(argv: list, env: dict, capture: str, timeout_s: float,
+          cwd: str = "") -> tuple:
+    """起一次调用并等它收口。返回 (phase, rc, pid, pid_start)。
+
+    phase ∈ {DONE, IN_FLIGHT}；DONE 时 rc 从侧件读（读不到 ⇒ None，**不折成 0**）。
+
+    这里刻意不用 `Popen.communicate(timeout=...)`：到点不杀是产品规定，
+    而留下一个 `returncode is None` 的 Popen 对象，解释器回收时会在 stderr 上
+    报 "subprocess is still running"（ResourceWarning），更糟的是它暗示"我们
+    以为自己还拥有这个孩子"。改成自己轮询＋`waitpid(WNOHANG)`：
+      · 父进程不欠任何人一个 reap（长活的桥不会攒僵尸进程）；
+      · 到点就返回 IN_FLIGHT，对象与子进程各走各的，靠退出码侧件会合。
+    """
+    os.makedirs(os.path.dirname(capture), exist_ok=True)
+    rc_path = rc_path_of(capture)
+    # 上一拍的原件**改名留住**再写新的：失败证据不许被下一次成功覆盖
+    security.refuse_overwrite(capture)
+    security.refuse_overwrite(rc_path)
+    inner = " ".join(shlex.quote(str(a)) for a in argv)
+    # POSIX 语法写侧件（`print -r --` 是 zsh 专有，bash/sh 上是另一种脾气）：
+    # 先写临时侧件再 mv，保证读到的 rc 件永远是完整一行。
+    wrapper = ("%s\nrc=$?\ntmp=%s.tmp\nprintf '%%s\\n' \"$rc\" > \"$tmp\"\n"
+               "mv -f \"$tmp\" %s\nexit $rc" % (inner, shlex.quote(rc_path), shlex.quote(rc_path)))
+    shell = security.posix_shell()
+    fh = open(capture, "w", encoding="utf-8")
+    kw = {"cwd": cwd} if cwd else {}
+    p = security.popen_group([shell, "-c", wrapper], stdout=fh, stderr=subprocess.STDOUT,
+                             text=True, env=env, **kw)
+    fh.close()
+    pid, pid_start = p.pid, security._proc_start_marker(p.pid) or ""
+    _LIVE[pid] = p
+    deadline = time.time() + max(float(timeout_s), 0.05)
+    while True:
+        reaped = reap(pid)
+        if reaped and os.path.isfile(rc_path):
+            return DONE, read_rc(capture), pid, pid_start
+        if reaped and not os.path.isfile(rc_path):
+            # 孩子没了却写不出退出码侧件：宁可报「没有 rc」，也不补一个 0 上去
+            return DONE, None, pid, pid_start
+        if time.time() >= deadline:
+            # 故意不等它：对象留在 _LIVE 里（有人引用就不会被回收），
+            # 下一次 reap()／退出兜底再收。
+            return IN_FLIGHT, None, pid, pid_start
+        time.sleep(0.02)
+
+
+def read_rc(capture: str):
+    """从侧件取退出码。缺件／非整数 ⇒ None（未知），绝不返回 0。"""
+    rc_path = rc_path_of(capture)
+    if not os.path.isfile(rc_path):
+        return None
+    try:
+        with open(rc_path, encoding="utf-8") as fh:
+            raw = (fh.read() or "").strip()
+    except OSError:
+        return None
+    if not raw or not raw.lstrip("-").isdigit():
+        return None
+    return int(raw)
+
+
+def collect(capture: str) -> tuple:
+    """不重投的前提下把已落盘的那一腿收回来。返回 (rc, raw_text)。
+
+    捕获件不在 ⇒ 抛，不返回空串（空串会被下游读成"对方回了个空"）。
+    """
+    if not os.path.isfile(capture):
+        raise FileNotFoundError(capture)
+    with open(capture, encoding="utf-8", errors="replace") as fh:
+        raw = fh.read()
+    return read_rc(capture), raw
+
+
+def rc_path_of(capture: str) -> str:
+    return capture + ".rc"