@@ -580,7 +580,7 @@ function Infer-State($msg) {
   return $null
 }
 
-function Write-Status($state, $message, $family) {
+function Write-Status($state, $message, $family, [switch]$KeepSubStep) {
   $tmp = "$statusFile.tmp"
   # usage5h：0..100 表示"剩余"百分比（不是已用！）；null = 未知/未拉到
   # usage5hResetMs：距下次刷新的毫秒数；null = 未知
@@ -592,17 +592,31 @@ function Write-Status($state, $message, $family) {
   $todoCnt     = if ($null -ne $script:plan5hTodoData)    { ("{0}/{1}" -f $script:plan5hTodoData.completed, $script:plan5hTodoData.total) } else { $null }
   $famField    = if ($family) { [string]$family } else { $null }
   # step / total / detail 是 agent（hook）推的 sub-step 状态，不是 detector
-  # 推的。detector 每次刷 5h 用量或 todo 进度都会重写整个 payload，如果这里
-  # 不把现有值读回来合并，正常使用中的 sub-step 进度会被静默清零
-  # （round-19 review hetaoBackend #2）。读-改-写，不是覆盖。
-  $prev = Read-StatusObj
+  # 推的。detector 重写整个 payload 时，这里怎么处理取决于"为什么写"。
+  #
+  # 两种写入语义完全不同（round-20 #5）：
+  #
+  #   - 元数据刷新（-KeepSubStep）：每 60s 刷 5h 用量、每次刷 todo 进度。
+  #     这两次的 state/message 是从当前 status.json 读回来原样再写回去的，
+  #     不代表"agent 进入了新的一步"，所以必须把已有的 sub-step 合并回来，
+  #     否则正常使用中的进度会被静默清零（round-19 #2）。
+  #
+  #   - 状态推断（默认）：detector 从 session log 推出一个新状态并写入。
+  #     这条消息的语义是"agent 现在在干这个"，它和上一条 hook 推的
+  #     sub-step 没有任何承接关系。无条件合并会让 pill 一直挂着上一步的
+  #     计数：实测里 agent 早已换工具、甚至这一轮都结束了，pill 还卡在
+  #     "step 1/1" 显示一条早就跑完的 curl 命令，而且没有任何后续写入会
+  #     把它清掉。所以状态推断一律重置。
   $stepField   = -1
   $totalField  = -1
   $detailField = ''
-  if ($prev) {
-    if ($prev.PSObject.Properties['step'])   { $stepField   = [int]$prev.step }
-    if ($prev.PSObject.Properties['total'])  { $totalField  = [int]$prev.total }
-    if ($prev.PSObject.Properties['detail'] -and $null -ne $prev.detail) { $detailField = [string]$prev.detail }
+  if ($KeepSubStep) {
+    $prev = Read-StatusObj
+    if ($prev) {
+      if ($prev.PSObject.Properties['step'])   { $stepField   = [int]$prev.step }
+      if ($prev.PSObject.Properties['total'])  { $totalField  = [int]$prev.total }
+      if ($prev.PSObject.Properties['detail'] -and $null -ne $prev.detail) { $detailField = [string]$prev.detail }
+    }
   }
   $payload = [PSCustomObject]@{
     state          = $state
@@ -808,7 +822,8 @@ try {
       $sForU = if ($curForUsage) { [string]$curForUsage.state } else { $S_IDLE }
       $mForU = if ($curForUsage) { [string]$curForUsage.message } else { '' }
       $fForU = if ($curForUsage -and $curForUsage.PSObject.Properties['family']) { $curForUsage.family } else { $null }
-      Write-Status $sForU $mForU $fForU
+      # 元数据刷新：原样写回当前状态，必须保留 sub-step（-KeepSubStep）
+      Write-Status $sForU $mForU $fForU -KeepSubStep
       Log-Line ("5h usage refreshed: remaining=" + $curPct + "% resetMs=" + $curMs)
     }
 
@@ -822,7 +837,8 @@ try {
       $sForT = if ($curForTodo) { [string]$curForTodo.state } else { $S_IDLE }
       $mForT = if ($curForTodo) { [string]$curForTodo.message } else { '' }
       $fForT = if ($curForTodo -and $curForTodo.PSObject.Properties['family']) { $curForTodo.family } else { $null }
-      Write-Status $sForT $mForT $fForT
+      # 元数据刷新：原样写回当前状态，必须保留 sub-step（-KeepSubStep）
+      Write-Status $sForT $mForT $fForT -KeepSubStep
       $script:plan5hLastWrittenTodoPct = $curTodoPct
       if ($null -ne $curTodoData) {
         Log-Line ("todo refreshed: " + $curTodoData.completed + "/" + $curTodoData.total + " = " + $curTodoPct + "%")
 
@@ -139,6 +139,13 @@ if (!PS_BIN) {
     const libPath = join(PLUGIN_ROOT, 'io.minimax.mcode', 'hooks', 'scripts', '_lib.ps1');
     const lib = readFileSync(libPath, 'utf8');
 
+    // Format-ToolSummary calls Protect-SecretText, which lives in a
+    // separate lib (round-20). Extracting the function body alone would
+    // leave the call unresolvable and the harness would die on an
+    // undefined command rather than on a real assertion -- so the harness
+    // dot-sources the lib, exactly as _lib.ps1 does in production.
+    const protectLibPath = join(PLUGIN_ROOT, 'scripts', 'lib', 'Protect-Text.ps1');
+
     let formatToolSummary;
     try {
         formatToolSummary = extractFn(lib, 'Format-ToolSummary');
@@ -151,6 +158,7 @@ if (!PS_BIN) {
 
         const harness = `
 $ErrorActionPreference = 'Stop'
+. '${protectLibPath.replace(/'/g, "''")}'
 ${formatToolSummary}
 $evt = [PSCustomObject]@{
   tool_name = 'mcode-computer-use'
@@ -179,6 +187,7 @@ Format-ToolSummary $evt
         // the redaction could have been implemented by disabling the branch.
         const coordHarness = `
 $ErrorActionPreference = 'Stop'
+. '${protectLibPath.replace(/'/g, "''")}'
 ${formatToolSummary}
 $evt = [PSCustomObject]@{
   tool_name = 'mcode-computer-use'
@@ -300,29 +309,33 @@ if (PS_BIN) {
 
     const writeStatusFn = extractFn(detect, 'Write-Status');
 
-    // Extract just the sub-step preservation lines as a standalone repro of
-    // the logic, so the test does not need the detector's whole environment.
-    const preserveMatch = writeStatusFn.match(
-        /\$prev = Read-StatusObj[\s\S]*?\$detailField = ''[\s\S]*?if \(\$prev\)\s*\{[\s\S]*?\n\s*\}/);
+    // Extract the sub-step decision block as a standalone repro of the
+    // logic, so the test does not need the detector's whole environment.
+    //
+    // The block is bounded by two stable statements rather than by the
+    // internal ordering of the read-modify-write: round-20 #5 wrapped it
+    // in `if ($KeepSubStep) { ... }`, so a regex anchored on `$prev`
+    // appearing before `$detailField` silently stopped matching. Anchor on
+    // the initialisers and the payload construction instead, and drive the
+    // switch explicitly -- this section pins the PRESERVE half; section 5
+    // pins the reset half and the call-site wiring.
+    const preserveMatch = writeStatusFn.match(/\$stepField\s*=\s*-1[\s\S]*?\$payload\s*=/);
 
     if (!preserveMatch) {
         bad('Write-Status preserves sub-step fields',
-            'could not find the step/total/detail read-modify-write block in Write-Status');
+            'could not find the step/total/detail decision block in Write-Status');
     } else {
         ok('Write-Status preserves sub-step fields');
 
         const harness = `
 $ErrorActionPreference = 'Stop'
 $statusFile = $env:ISLAND_TEST_STATUS
+$KeepSubStep = $true
 function Read-StatusObj {
   if (!(Test-Path $statusFile)) { return $null }
   try { return ([System.IO.File]::ReadAllText($statusFile) | ConvertFrom-Json) } catch { return $null }
 }
-$prev = Read-StatusObj
-$stepField   = -1
-$totalField  = -1
-$detailField = ''
-${preserveMatch[0].split('\n').slice(1).join('\n')}
+${preserveMatch[0].replace(/\$payload\s*=$/, '')}
 "$stepField|$totalField|$detailField"
 `;
         const statusFile = join(TMP, 'status.json');
@@ -376,6 +389,95 @@ ${preserveMatch[0].split('\n').slice(1).join('\n')}
     }
 }
 
+// ---------------------------------------------------------------------------
+// 5. A detector state-inference write must CLEAR a stale sub-step
+//    (round-20 #5)
+// ---------------------------------------------------------------------------
+//
+// Section 3 pins the other half of the same contract: a metadata refresh
+// must PRESERVE step/total/detail, because the 60s 5h-usage rewrite and
+// the todo rewrite restate the current state rather than announcing a new
+// step. Preserving unconditionally is only half right.
+//
+// A detector state-inference write is different in kind. It read a new
+// tool call out of the session log and is asserting "the agent is doing
+// THIS now". That message has no relationship to whatever sub-step a hook
+// pushed last, so inheriting step/total/detail leaves the previous turn's
+// counter on the pill indefinitely. Observed live: the pill sat on
+// "step 1/1" showing a curl command from a finished tool call, through
+// several subsequent turns, because nothing ever cleared it.
+//
+// The two write paths must therefore be distinguished explicitly, not by
+// guessing from the message text.
+{
+    const detectPath = join(PLUGIN_ROOT, 'mcode-status-detect.ps1');
+    const detect = readFileSync(detectPath, 'utf8');
+    const writeStatusFn = extractFn(detect, 'Write-Status');
+
+    const hasSwitch = /function\s+Write-Status[\s\S]*?\[switch\]\$KeepSubStep/.test(writeStatusFn);
+    check('Write-Status exposes a -KeepSubStep switch',
+        hasSwitch,
+        'state-inference and metadata-refresh writes are not distinguished, so a stale sub-step can never be cleared');
+
+    // Anchor on the two stable statements either side of the decision so
+    // the extraction survives reformatting inside the block.
+    const block = writeStatusFn.match(/\$stepField\s*=\s*-1[\s\S]*?\$payload\s*=/);
+
+    if (!hasSwitch || !block) {
+        bad('detector state write clears a stale sub-step',
+            'could not extract the sub-step decision block from Write-Status');
+    } else {
+        ok('detector state write clears a stale sub-step');
+
+        const harness = `
+$ErrorActionPreference = 'Stop'
+$statusFile = $env:ISLAND_TEST_STATUS
+$KeepSubStep = [bool]::Parse($env:ISLAND_TEST_KEEP)
+function Read-StatusObj {
+  if (!(Test-Path $statusFile)) { return $null }
+  try { return ([System.IO.File]::ReadAllText($statusFile) | ConvertFrom-Json) } catch { return $null }
+}
+${block[0].replace(/\$payload\s*=$/, '')}
+"$stepField|$totalField|$detailField"
+`;
+
+        const statusFile = join(TMP, 'status.json');
+        const run = (keep) => runPs(
+            `$env:ISLAND_TEST_STATUS = '${statusFile.replace(/'/g, "''")}'\n` +
+            `$env:ISLAND_TEST_KEEP = '${keep ? 'True' : 'False'}'\n` + harness).trim();
+
+        // Previous status carries a finished sub-step from an agent push.
+        const stale = {
+            state: 'done', message: 'Bash ok', family: 'shell',
+            step: 1, total: 1, detail: 'curl -H "Authorization: Bearer <redacted>"',
+            source: 'agent',
+        };
+
+        writeFileSync(statusFile, JSON.stringify(stale), 'utf8');
+        eq('state-inference write clears the stale sub-step', run(false), '-1|-1|');
+
+        writeFileSync(statusFile, JSON.stringify(stale), 'utf8');
+        eq('metadata-refresh write (-KeepSubStep) still preserves it',
+            run(true), '1|1|curl -H "Authorization: Bearer <redacted>"');
+    }
+
+    // The call sites must actually differ. A switch nobody passes is the
+    // dead-code shape this suite exists to catch.
+    const callSites = detect.split('\n')
+        .map((l, i) => ({ l, n: i + 1 }))
+        .filter(({ l }) => /^\s*Write-Status\s+\$/.test(l));
+    const keeps = callSites.filter(({ l }) => /-KeepSubStep/.test(l));
+    const infers = callSites.filter(({ l }) => /\$inferred\.state/.test(l));
+
+    eq('Write-Status has 3 call sites', callSites.length, 3);
+    check('the state-inference call site does NOT pass -KeepSubStep',
+        infers.length === 1 && !/-KeepSubStep/.test(infers[0].l),
+        `inference call site must clear stale sub-step (line ${infers[0]?.n})`);
+    check('the 5h-usage and todo call sites DO pass -KeepSubStep',
+        keeps.length === 2,
+        `expected 2 -KeepSubStep call sites, found ${keeps.length}`);
+}
+
 // ---------------------------------------------------------------------------
 // summary
 // ---------------------------------------------------------------------------