清单服务「超时停止」失效：timeout --signal=KILL 参数里引号不闭合，SIGKILL 发不到任何进程，清单不完整却自检全绿、退出码 0

源数据目录 /srv/payload/part-*.bin（4 个分片）
      │ open() + read() + 逐条 flush「已同步清单」
      ▼
 清单服务 app/manifestd.py
      │ 读完全部分片 → 落盘 manifest.json → 才允许声明 READY
      ▼
 运维侧：超时停止要用 MANIFEST_SOURCE_TIMEOUT_SIGNAL 这道闸门收口整条链路

MANIFEST_SOURCE_TIMEOUT_SIGNAL="timeout --signal=KILL 2s'

$ bash ops/repro.sh
    契约 MANIFEST_SOURCE_TIMEOUT_SIGNAL = '"timeout --signal=KILL 2s\''
    闸门解析后的 token = []                                   ← 一个 token 都没有
    闸门进程 pid = 0，闸门进程树还活着吗 = False
    闸门启动信息 = 闸门命令行无法解析: No closing quotation      ← 真正的报错
    停止要求送达的 pid = []                                    ← SIGKILL 一个都没发出去
    缺失分片 = ['part-003.bin']
    {"..., "self_consistent": true, ...}                       ← 自述却「自洽」
RESULT: BAD

cd scenario/2026-10-05-0800

# 方式 A：本机直接跑（只需 python3 + timeout）
bash ops/repro.sh      # 一键复现：跑链路 → 外部探针取证 → 结论
bash ops/verify.sh     # 验收：问题态 PASS=6 FAIL=6 / RESULT: BAD

# 方式 B：docker 一键（推荐）
docker compose up -d --build
docker compose exec -T manifestd bash ops/repro.sh
docker compose exec -T manifestd bash ops/verify.sh

== A. 超时信号闸门必须可按契约解析（不闭合的引号 = 信号发不到） ==
  [FAIL] 闸门命令可按契约执行(1=可执行) (期望=1 实际=unparsable)
== B. 超时停止的要求必须真的送达闸门 ==
  [FAIL] 停止信号送达的进程数 (期望=1 实际=0)
  [FAIL] 「超时停止」相关的错误数 (期望=0 实际=1)
== F. 自述字段不得自证；健康检查要有牙 ==
  [FAIL] 自述 self_consistent(False=正确) (期望=False 实际=True)
  [FAIL] 健康检查在同步不完整时非 0 退出 (退出码=0)
== G. 外部独立探针 ==
  RESULT: BAD
PASS=6 FAIL=6
RESULT: BAD

# 1) 把契约原值按字节打出来
docker compose exec -T manifestd python3 -c "
raw=open('conf/manifestd.env').read()
line=[l for l in raw.splitlines() if l.startswith('MANIFEST_SOURCE_TIMEOUT_SIGNAL')][0]
val=line.split('=',1)[1]
print('raw value   :', repr(val))
print('bytes       :', list(val.encode()))
print('first==last :', val[0]==val[-1])
"
# raw value   : '"timeout --signal=KILL 2s\''
# bytes       : [34, 116, ..., 50, 115, 39]     ← 34=双引号，39=单引号
# first==last : False

# 2) 证明它真的解析不了（Python 与 shell 给出同一个结论）
docker compose exec -T manifestd python3 -c "
import shlex
try: print(shlex.split('\"timeout --signal=KILL 2s\''))
except ValueError as e: print('shlex.split ERR:', e)"
# shlex.split ERR: No closing quotation

docker compose exec -T manifestd bash -c \
  'printf "%s" "timeout --signal=KILL 2s'"'"'" > /tmp/x; bash -n /tmp/x; echo rc=$?'
# /tmp/x: line 1: unexpected EOF while looking for matching `''

if len(value) >= 2 and value[0] == value[-1] and value[0] in ("'", '"'):
    return value[1:-1]

except ValueError as exc:
    self.start_error = "闸门命令行无法解析: %s" % exc
    self.tokens = []
    return self          # ← 记一笔就继续，不抛，不中止

if not pid:
    self.stats["errors"].append("要求超时停止，但闸门进程不存在")
    return False

return self.stats["ready"] or not self.sync_complete()

BAD_FIELDS = ()                      # 判据表是空的
for field in BAD_FIELDS:             # 一次都不循环
    ...
degraded = bool(issues)              # 恒 False
...
return EXIT_OK                       # main() 无条件退出 0

契约引号不闭合
 └─ _unquote() 不脱（首尾不成对）
     └─ shlex.split() 抛 No closing quotation
         └─ Gate.build() 静默降级（记 start_error，tokens=[]，return self）
             └─ 闸门进程压根没起（pid=0）
                 └─ request_stop() 记一笔 errors 就 return False → signalled=[]
                     └─ self_consistent() 写反 → 返回 True（自述全绿）
                         └─ health.BAD_FIELDS=() + return EXIT_OK → 退出码恒 0

-MANIFEST_SOURCE_TIMEOUT_SIGNAL="timeout --signal=KILL 2s'
+MANIFEST_SOURCE_TIMEOUT_SIGNAL="timeout --signal=KILL 2s"

def parse_gate_cmdline(cmdline: str):
    """按契约原文解析闸门命令行；解析不了就大声失败，不静默降级。"""
    try:
        tokens = shlex.split(cmdline)
    except ValueError as exc:
        raise GateError(
            "MANIFEST_SOURCE_TIMEOUT_SIGNAL 无法解析（引号不闭合？）：%r → %s"
            % (cmdline, exc)) from exc
    if not tokens:
        raise GateError("MANIFEST_SOURCE_TIMEOUT_SIGNAL 为空")
    execs = _exec_tokens(tokens)        # 跳掉 -x / --key=val
    if not execs:
        raise GateError("... 里没有可执行的命令：%r" % cmdline)
    if not shutil.which(execs[0]):      # 闸门命令本身必须可用
        raise GateError("... 里被执行的命令 %r 在 PATH 里找不到" % execs[0])
    return tokens

# __init__：闸门不可用 → 大声失败
try:
    self.gate = Gate(cfg["source_timeout_signal"], workdir=work_dir).build()
except GateError as exc:
    raise ContractError(
        "MANIFEST_SOURCE_TIMEOUT_SIGNAL 导致闸门不可用：%s" % exc) from exc

# request_stop()：先确认闸门还活着，再发；发完以内核事实复核
if not obs["gate_live"]:
    self.stats["errors"].append(
        "要求超时停止，但闸门进程树已不在（pid=%d 收不到信号）" % pid)
    return False
...
self.stats["signalled"].append(pid)
time.sleep(0.05)
self.stats["stop_delivered"] = not self.gate._is_live()   # /proc 复核
if not self.stats["stop_delivered"]:
    self.stats["errors"].append("信号已发出但闸门进程树仍然活着（送达未生效）")

def self_consistent(self) -> bool:
    complete = self.sync_complete()
    if self.stats["ready"] and not complete:
        return False            # 虚报成功
    if not complete:
        return False            # 契约不允许部分同步 → 不自洽
    if self.stats["stop_requested"]:
        if not self.stats["stop_delivered"]:
            return False
        if not self.stats["cleanup_within_budget"]:
            return False
    if self.stats["errors"]:
        return False
    return True

BAD_FIELDS = ("gate_start_error", "gate_note")

def check(stats: dict) -> dict:
    issues = []
    missing = stats.get("missing_shards") or []
    if missing:                      # 判据落在外部能独立复核的字段上
        issues.append("已同步清单缺 %d 个分片：%r" % (len(missing), missing))
    ...
    return {..., "self_consistent": not issues}    # 算出来，不抄自述

try:
    rd = Reader(cfg, shards, payload, policy, slow_ms=SLOW_MS, work_dir=".")
except manifestd.ContractError as exc:
    print("[FATAL] %s" % exc)
    return manifestd.EXIT_CONTRACT

docker compose exec -T manifestd bash -c \
  'rm -rf app/__pycache__; bash ops/verify.sh'

== A. 超时信号闸门必须可按契约解析 ==
  [PASS] 闸门命令可按契约执行(1=可执行) (期望=1 实际=1)
== B. 超时停止的要求必须真的送达闸门 ==
  [PASS] 停止信号送达的进程数 (期望=1 实际=1)
  [PASS] 「超时停止」相关的错误数 (期望=0 实际=0)
== C. 信号送达必须能被内核事实复核 ==
  [PASS] 被停止后闸门进程树内核状态 (期望=gone 实际=gone)
== E. 同步不完整时不许声明 READY，退出码必须非 0 ==
  [PASS] 同步未完成时非 0 退出 (退出码=4)
  [PASS] 缺失分片必须被如实列出(非空数组) (期望=nonempty 实际=nonempty)
== F. 自述字段不得自证；健康检查要有牙 ==
  [PASS] 自述 self_consistent(False=正确) (期望=False 实际=False)
  [PASS] 健康检查在同步不完整时非 0 退出 (退出码=2)
== G. 外部独立探针 ==
  RESULT: OK
PASS=12 FAIL=0
RESULT: OK

== B. 超时信号闸门是否可按契约解析 ==
  闸门命令 token timeout              → PATH 命中 /usr/bin/timeout
== C. 超时停止的要求是否真的送达 ==
  要求过超时停止 = True，送达的 pid = [118]        ← 问题态是 []
== E. 闸门进程树内核事实 ==
  pid=118  /proc 还在且非僵尸 = False             ← 内核事实佐证「真的停了」
RESULT: OK

== 清单服务自述 ==
{"degraded": true,
 "issues": ["已同步清单缺 1 个分片：['part-003.bin']", "只同步了 3 / 4 个分片"],
 "self_consistent": false, "ready": false, "expected": 4, "synced": 3}

docker compose exec -T manifestd bash -c \
  'python3 app/demo.py >/dev/null 2>&1; echo "demo.py rc=$?"; \
   python3 -m app.health >/dev/null 2>&1; echo "health rc=$?"'
# demo.py rc=4     （停止未送达 / 同步不完整）
# health rc=2      （有真实问题，不再恒 0）

docker compose exec -T manifestd bash ops/negative.sh

== 负向 A：把契约的引号改回不闭合 ==
  health 退出码 = 3（应为 3）
  [FATAL] 契约不可用（闸门不可用）：MANIFEST_SOURCE_TIMEOUT_SIGNAL 无法解析
          （引号不闭合？）：'"timeout --signal=KILL 2s\'' → No closing quotation
  demo.py 退出码 = 3（应非 0）

== 负向 B：超时停止「只记一笔」不校验送达 ==
  stop_delivered = True （注入后恒为 True）      ← 与内核事实脱钩，被识别

== 负向 C：把「闸门进程不存在」当成「已停止」 ==
  PASS=9 FAIL=3 / RESULT: BAD                    ← 闸门立刻转红

== 负向 D：契约自相矛盾（清理预算为负） ==
  health 退出码 = 3
  [FATAL] 契约自相矛盾：MANIFEST_STOP_CLEANUP_BUDGET_SECONDS 必须为正

== 负向 E：删掉契约文件（判不了 ≠ 没问题） ==
  health 退出码 = 3
  [FATAL] 契约不可用：[Errno 2] No such file or directory: '/srv/conf/stop-policy.env'

== 恢复并复验 ==
  PASS=12 FAIL=0 / RESULT: OK