@whyshu/argent-engine 0.0.0-stage → 0.6.0

package/engine/scripts/win/dsh-web-autostart.ps1

@@ -0,0 +1,372 @@
+# Argent on DSH - Windows logon autostart registrar for the `dsh web` host (ASCII-only on purpose).
+#
+# WHY TASK SCHEDULER AND NOT A SERVICE
+#   A *user-level* task with a LogonTrigger runs inside the interactive session (session 1) under a
+#   limited token: %USERPROFILE%\.dsh credentials stay visible and NO administrator rights are
+#   needed. SYSTEM / S4U tasks run in session 0 (USERPROFILE becomes systemprofile) which is a dead
+#   end for anything browser-driven. Measured 2026-10-08 on the reference Win11 box; see the
+#   Windows feasibility study in docs/ dated 2026-10-08 (sections 2.1 / 3.2 / 3.5).
+#
+# THE THREE HARMFUL TASK SCHEDULER DEFAULTS, WRITTEN EXPLICITLY
+#   1. ExecutionTimeLimit defaults to PT72H  -> set to PT0S (unlimited). Without this the host is
+#      force-killed on day 3.
+#   2. DisallowStartIfOnBatteries defaults to true (StopIfGoingOnBatteries too) -> both cleared.
+#      Without this the host never starts on a laptop, or is cut off when unplugged.
+#   3. Task Scheduler has NO stdout/stderr sink -> the action redirects both into a stable
+#      directory: <dsh home>\logs\dsh-web.log  (default %USERPROFILE%\.dsh\logs\dsh-web.log).
+#
+# WHY THE ACTION PINS AN ABSOLUTE NODE PATH
+#   A bare `node` resolves to the *system* Node (measured: D:\Program Files\nodejs\node.exe =
+#   v22.12.0 on the reference box) where `dsh --version` prints NOTHING and exits 0 - a silent
+#   failure that looks like success. So the action embeds the Node >= 24.2 absolute path, and this
+#   script refuses to install unless that interpreter really answers (`<node> <dsh bin.js> --version`
+#   returns a non-empty version). `dsh.cmd` is never used: it calls a bare `node` internally.
+#
+# NO CRASH SELF-HEALING (honest limitation, do not paper over it)
+#   RestartOnFailure is deliberately NOT set. It only reacts to non-zero exits (launchd KeepAlive
+#   reacts to any exit), and it was measured NOT to fire at all on this platform under both
+#   at-trigger and on-demand starts (feasibility doc 3.4). This task therefore gives you
+#   "start at logon", NOT "restart when it dies". Do not read it as a KeepAlive equivalent.
+#
+# Usage (run these IN POWERSHELL, from any directory; the default install location is quoted below).
+#   `%USERPROFILE%` is a cmd.exe variable and does NOT expand in PowerShell.
+#   WRONG (cmd-only syntax, kept here as the counter-example):
+#     -File %USERPROFILE%\...\dsh-web-autostart.ps1  ->  "The argument '...' to the -File parameter
+#     does not exist" (measured on Win11 / PowerShell 5.1, 2026-10-09).
+#   RIGHT: PowerShell needs "$env:USERPROFILE\..." QUOTED (same shape install.ps1 prints):
+#   powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.argent-dsh\scripts\win\dsh-web-autostart.ps1" install
+#   powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.argent-dsh\scripts\win\dsh-web-autostart.ps1" status
+#   powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.argent-dsh\scripts\win\dsh-web-autostart.ps1" uninstall
+#   (already inside this file's directory? then the relative form is fine: -File ".\dsh-web-autostart.ps1" <verb>)
+#
+# Options: -TaskName <name> (default WhyshuDshWeb), -Port <n> (default 3080),
+#          -NodePath <node.exe>, -DshBin <...\@deepseek-ai\dsh\lib\bin.js>,
+#          -DshHome <dir> (default %USERPROFILE%\.dsh), -LogDir <dir> (default <DshHome>\logs)
+#
+# Exit codes: 0 ok / 1 failure / 2 usage error.
+#
+# NOTE for maintainers: *.ps1 is intentionally NOT enrolled in scripts/tests/kernel-purity.test.mjs
+#   LAYER_RULES. That gate only walks SCRIPT_CODE_RE = .mjs/.js/.py/.sh/.rb, and it fails a rule
+#   that matches zero files ("dead rule"), so adding a `scripts/win/*.ps1` glob there would turn
+#   the gate RED. This registrar is host-side (L2) by construction; it holds no engine judgement.
+
+[CmdletBinding()]
+param(
+    [Parameter(Position = 0)][string]$Command = 'status',
+    [string]$TaskName = 'WhyshuDshWeb',
+    [int]$Port = 3080,
+    [string]$NodePath = '',
+    [string]$DshBin = '',
+    [string]$DshHome = '',
+    [string]$LogDir = ''
+)
+
+$ErrorActionPreference = 'Stop'
+$MIN_NODE_MAJOR = 24
+$MIN_NODE_MINOR = 2
+
+function Fail {
+    param([string]$Message)
+    Write-Output ''
+    Write-Output ("ERROR: " + $Message)
+    exit 1
+}
+function Show-Usage {
+    Write-Output 'usage: dsh-web-autostart.ps1 <install|status|uninstall> [-TaskName n] [-Port n]'
+    Write-Output '       [-NodePath node.exe] [-DshBin bin.js] [-DshHome dir] [-LogDir dir]'
+    exit 2
+}
+
+# --- resolution ------------------------------------------------------------
+
+function Resolve-NodeExe {
+    $cands = New-Object System.Collections.ArrayList
+    if ($NodePath) { [void]$cands.Add($NodePath) }
+    [void]$cands.Add((Join-Path $env:USERPROFILE '.local\node\node.exe'))
+    $onPath = Get-Command node -ErrorAction SilentlyContinue
+    if ($onPath -and $onPath.Source) { [void]$cands.Add($onPath.Source) }
+    $tried = New-Object System.Collections.ArrayList
+    foreach ($c in $cands) {
+        if (-not $c) { continue }
+        if (-not (Test-Path -LiteralPath $c)) { [void]$tried.Add($c + ' (missing)'); continue }
+        $ver = ''
+        try { $ver = ((& $c --version 2>&1) | Out-String).Trim() } catch { $ver = '' }
+        if ($ver -match '^v?(\d+)\.(\d+)') {
+            $maj = [int]$Matches[1]; $min = [int]$Matches[2]
+            if ($maj -gt $MIN_NODE_MAJOR -or ($maj -eq $MIN_NODE_MAJOR -and $min -ge $MIN_NODE_MINOR)) {
+                return @{ Path = $c; Version = $ver; Tried = $tried }
+            }
+            [void]$tried.Add($c + ' (' + $ver + ', too old)')
+        } else {
+            [void]$tried.Add($c + ' (no version output)')
+        }
+    }
+    return @{ Path = ''; Version = ''; Tried = $tried }
+}
+
+function Resolve-DshBin {
+    $cands = New-Object System.Collections.ArrayList
+    if ($DshBin) { [void]$cands.Add($DshBin) }
+    if ($env:APPDATA) { [void]$cands.Add((Join-Path $env:APPDATA 'npm\node_modules\@deepseek-ai\dsh\lib\bin.js')) }
+    $npm = Get-Command npm -ErrorAction SilentlyContinue
+    if ($npm) {
+        try {
+            $prefix = ((& npm prefix -g 2>$null) | Out-String).Trim()
+            if ($prefix) { [void]$cands.Add((Join-Path $prefix 'node_modules\@deepseek-ai\dsh\lib\bin.js')) }
+        } catch { }
+    }
+    $shim = Get-Command dsh -ErrorAction SilentlyContinue
+    if ($shim -and $shim.Source) {
+        $dir = Split-Path -Parent $shim.Source
+        [void]$cands.Add((Join-Path $dir 'node_modules\@deepseek-ai\dsh\lib\bin.js'))
+    }
+    $tried = New-Object System.Collections.ArrayList
+    foreach ($c in $cands) {
+        if (-not $c) { continue }
+        if (Test-Path -LiteralPath $c) { return @{ Path = $c; Tried = $tried } }
+        [void]$tried.Add($c + ' (missing)')
+    }
+    return @{ Path = ''; Tried = $tried }
+}
+
+# --- task text helpers ------------------------------------------------------------
+
+function Get-TaskXml {
+    param([string]$Name)
+    try { return (Export-ScheduledTask -TaskName $Name -ErrorAction Stop) } catch { return '' }
+}
+function Rx {
+    param([string]$Text, [string]$Pattern)
+    $m = [regex]::Match($Text, $Pattern)
+    if ($m.Success) { return $m.Groups[1].Value }
+    return ''
+}
+
+function Get-TaskPath {
+    param([string]$Name, [string]$DshHomeResolved)
+    return (Join-Path $DshHomeResolved 'logs\dsh-web.log')
+}
+
+# --- status (read-only) ------------------------------------------------------------
+
+function Show-Status {
+    param([string]$Name, [string]$DshHomeResolved)
+    $logFile = Get-TaskPath -Name $Name -DshHomeResolved $DshHomeResolved
+    Write-Output '=== dsh web autostart - status (read-only) ==='
+    Write-Output ("task name        : " + $Name)
+    $task = Get-ScheduledTask -TaskName $Name -ErrorAction SilentlyContinue
+    if (-not $task) {
+        Write-Output 'installed        : no'
+        Write-Output ("log file         : " + $logFile + " (exists=" + (Test-Path -LiteralPath $logFile) + ")")
+        Write-Output 'self-healing     : none (RestartOnFailure deliberately not set; measured not to fire)'
+        Write-Output ("install with     : powershell -NoProfile -ExecutionPolicy Bypass -File `"$PSCommandPath`" install")
+        return
+    }
+    $xml = Get-TaskXml -Name $Name
+    Write-Output 'installed        : yes'
+    Write-Output ("state            : " + $task.State)
+    $trigBlock = [regex]::Match($xml, '<LogonTrigger>.*?</LogonTrigger>', 'Singleline').Value
+    $trigKind = 'LogonTrigger'
+    if (-not $trigBlock) { $trigKind = 'OTHER (no LogonTrigger found in XML)' }
+    $trigUser = Rx -Text $trigBlock -Pattern '<UserId>(.*?)</UserId>'
+    $trigDelay = Rx -Text $trigBlock -Pattern '<Delay>(.*?)</Delay>'
+    if (-not $trigDelay) { $trigDelay = '(none => starts immediately at logon)' }
+    Write-Output ("trigger          : " + $trigKind + "  UserId=" + $trigUser + "  Delay=" + $trigDelay)
+    $logonType = Rx -Text $xml -Pattern '<LogonType>(.*?)</LogonType>'
+    $runLevel = Rx -Text $xml -Pattern '<RunLevel>(.*?)</RunLevel>'
+    if (-not $runLevel) { $runLevel = 'LeastPrivilege (absent in XML = schema default)' }
+    Write-Output ("principal        : " + $trigUser + "  LogonType=" + $logonType + "  RunLevel=" + $runLevel)
+    $actionArgs = ''
+    foreach ($a in $task.Actions) {
+        Write-Output ("action execute   : " + $a.Execute)
+        Write-Output ("action arguments : " + $a.Arguments)
+        Write-Output ("action workdir   : " + $a.WorkingDirectory)
+        $actionArgs = [string]$a.Arguments
+    }
+    $etl = Rx -Text $xml -Pattern '<ExecutionTimeLimit>(.*?)</ExecutionTimeLimit>'
+    $batt = Rx -Text $xml -Pattern '<DisallowStartIfOnBatteries>(.*?)</DisallowStartIfOnBatteries>'
+    $stopb = Rx -Text $xml -Pattern '<StopIfGoingOnBatteries>(.*?)</StopIfGoingOnBatteries>'
+    $idle = Rx -Text $xml -Pattern '<StopOnIdleEnd>(.*?)</StopOnIdleEnd>'
+    $mip = Rx -Text $xml -Pattern '<MultipleInstancesPolicy>(.*?)</MultipleInstancesPolicy>'
+    Write-Output ("settings         : ExecutionTimeLimit=" + $etl + "  DisallowStartIfOnBatteries=" + $batt + "  StopIfGoingOnBatteries=" + $stopb + "  StopOnIdleEnd=" + $idle + "  MultipleInstancesPolicy=" + $mip)
+    $restart = [regex]::Match($xml, '<RestartOnFailure>.*?</RestartOnFailure>', 'Singleline')
+    if ($restart.Success) {
+        Write-Output ("self-healing     : RestartOnFailure present in XML -> " + $restart.Value.Replace("`r", ' ').Replace("`n", ' '))
+    } else {
+        Write-Output 'self-healing     : none (RestartOnFailure deliberately not set; measured not to fire on this platform)'
+    }
+    $dshHomeInAction = Rx -Text $actionArgs -Pattern 'DSH_HOME=([^"]+)"'
+    Write-Output ("dsh home         : " + $dshHomeInAction)
+    $nodeInAction = Rx -Text $actionArgs -Pattern '&&\s+"([^"]+)"'
+    Write-Output ("pinned node      : " + $nodeInAction + "  exists=" + (Test-Path -LiteralPath $nodeInAction))
+    $binInAction = Rx -Text $actionArgs -Pattern '\.exe"\s+"([^"]+)"'
+    Write-Output ("dsh entry        : " + $binInAction + "  exists=" + (Test-Path -LiteralPath $binInAction))
+    $info = $null
+    try { $info = Get-ScheduledTaskInfo -TaskName $Name -ErrorAction Stop } catch { $info = $null }
+    if ($info) {
+        $res = [int]$info.LastTaskResult
+        $resNote = ''
+        if ($res -eq 267011) { $resNote = ' = 0x41303 SCHED_S_TASK_HAS_NOT_RUN (never started yet)' }
+        elseif ($res -eq 267009) { $resNote = ' = 0x41301 SCHED_S_TASK_RUNNING (it is running right now)' }
+        Write-Output ("last run         : " + $info.LastRunTime + "  result=" + $res + " (0x" + ('{0:X}' -f $res) + ")" + $resNote + "  missed=" + $info.NumberOfMissedRuns)
+        Write-Output ("next run         : " + $info.NextRunTime + "  (empty is normal for a logon-only trigger)")
+    }
+    $listen = 0
+    try { $listen = (Get-NetTCPConnection -LocalPort $Port -ErrorAction SilentlyContinue | Measure-Object).Count } catch { $listen = -1 }
+    Write-Output ("port " + $Port + " listeners : " + $listen + "   (0 = dsh web is not running right now)")
+    $exists = Test-Path -LiteralPath $logFile
+    $size = -1
+    $mtime = ''
+    if ($exists) {
+        $fi = Get-Item -LiteralPath $logFile
+        $size = $fi.Length
+        $mtime = $fi.LastWriteTime
+    }
+    Write-Output ("log file         : " + $logFile + "  exists=" + $exists + " size=" + $size + " mtime=" + $mtime)
+    Write-Output ("uninstall with   : powershell -NoProfile -ExecutionPolicy Bypass -File `"$PSCommandPath`" uninstall -TaskName " + $Name)
+}
+
+# --- install ------------------------------------------------------------
+
+function Install-Task {
+    param([string]$Name, [int]$Port, [string]$DshHomeArg, [string]$LogDirArg)
+    $dshHomeResolved = $DshHomeArg
+    if (-not $dshHomeResolved) { $dshHomeResolved = Join-Path $env:USERPROFILE '.dsh' }
+    $logDirResolved = $LogDirArg
+    if (-not $logDirResolved) { $logDirResolved = Join-Path $dshHomeResolved 'logs' }
+    $logFile = Join-Path $logDirResolved 'dsh-web.log'
+
+    Write-Output '=== dsh web autostart - install (user-level logon task; no administrator needed) ==='
+
+    $node = Resolve-NodeExe
+    if (-not $node.Path) {
+        Write-Output '  candidates tried:'
+        foreach ($t in $node.Tried) { Write-Output ('    - ' + $t) }
+        Fail ("no Node.js >= $MIN_NODE_MAJOR.$MIN_NODE_MINOR found. The action must pin an absolute Node path: a bare 'node' resolves to the system Node where 'dsh --version' prints nothing and exits 0 (silent failure). Install Node 24 (e.g. unzip node-v24.x-win-x64.zip to %USERPROFILE%\.local\node) or pass -NodePath.")
+    }
+    Write-Output ("  node             : " + $node.Path + "  (" + $node.Version + ")")
+
+    $bin = Resolve-DshBin
+    if (-not $bin.Path) {
+        Write-Output '  candidates tried:'
+        foreach ($t in $bin.Tried) { Write-Output ('    - ' + $t) }
+        Fail 'dsh entry point (lib\bin.js) not found. Install dsh first, or pass -DshBin.'
+    }
+    Write-Output ("  dsh entry        : " + $bin.Path)
+
+    # The silent-failure gate: the pinned interpreter must really answer.
+    $verOut = ''
+    $verCode = -1
+    try {
+        $verOut = ((& $node.Path $bin.Path --version 2>&1) | Out-String).Trim()
+        $verCode = $LASTEXITCODE
+    } catch {
+        $verOut = ''
+        $verCode = -1
+    }
+    if (-not $verOut) {
+        Fail ("'" + $node.Path + " " + $bin.Path + " --version' returned EMPTY output (exit " + $verCode + "). That is the documented silent-failure mode (Node too old for import.meta.main): the task would look registered but never serve. Refusing to install.")
+    }
+    Write-Output ("  dsh version      : " + $verOut + "  (non-empty => the pinned interpreter really runs dsh)")
+    if ($verCode -ne 0) { Write-Output ("  note             : --version exited " + $verCode + "; continuing because output was non-empty") }
+
+    if (-not (Test-Path -LiteralPath $logDirResolved)) {
+        New-Item -ItemType Directory -Force -Path $logDirResolved | Out-Null
+        Write-Output ("  log dir          : " + $logDirResolved + " (created)")
+    } else {
+        Write-Output ("  log dir          : " + $logDirResolved + " (already existed)")
+    }
+
+    $listening = 0
+    try { $listening = (Get-NetTCPConnection -LocalPort $Port -ErrorAction SilentlyContinue | Measure-Object).Count } catch { $listening = -1 }
+    if ($listening -gt 0) {
+        Write-Output ("  note             : port " + $Port + " already has a listener - a dsh web instance is running. The new task will not be able to bind until that one exits (MultipleInstancesPolicy=IgnoreNew only de-duplicates this task).")
+    }
+
+    # Action: cmd.exe handles the redirection that Task Scheduler cannot do itself.
+    $cmdExe = Join-Path $env:SystemRoot 'System32\cmd.exe'
+    $inner = 'set "DSH_HOME=' + $dshHomeResolved + '" && "' + $node.Path + '" "' + $bin.Path + '" web --port ' + $Port + ' --no-open >> "' + $logFile + '" 2>&1'
+    $actionArg = '/c "' + $inner + '"'
+
+    $action = New-ScheduledTaskAction -Execute $cmdExe -Argument $actionArg -WorkingDirectory $env:USERPROFILE
+    $userName = [Security.Principal.WindowsIdentity]::GetCurrent().Name
+    $trigger = New-ScheduledTaskTrigger -AtLogOn -User $userName
+    # The three harmful defaults are overridden here. RestartCount is deliberately absent.
+    $settings = New-ScheduledTaskSettingsSet -MultipleInstances IgnoreNew `
+        -ExecutionTimeLimit ([TimeSpan]::Zero) `
+        -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries -DontStopOnIdleEnd
+    $principal = New-ScheduledTaskPrincipal -UserId $userName -LogonType Interactive -RunLevel Limited
+
+    Register-ScheduledTask -TaskName $Name -Action $action -Trigger $trigger -Settings $settings -Principal $principal -Force | Out-Null
+    Write-Output ("  registered       : " + $Name + "  (LogonTrigger UserId=" + $userName + ", LogonType=Interactive, RunLevel=Limited)")
+
+    # Verify what actually landed; roll back rather than leave a mis-shaped task behind.
+    $xml = Get-TaskXml -Name $Name
+    $problems = New-Object System.Collections.ArrayList
+    if ($xml -notmatch '<LogonTrigger>') { [void]$problems.Add('no LogonTrigger in the registered XML') }
+    if ($xml -notmatch '<LogonType>InteractiveToken</LogonType>') { [void]$problems.Add('LogonType is not InteractiveToken (session 0 risk)') }
+    if (-not $xml.Contains([System.Security.SecurityElement]::Escape($node.Path))) { [void]$problems.Add('action does not contain the pinned node path ' + $node.Path) }
+    if ($xml -notmatch '<ExecutionTimeLimit>PT0S</ExecutionTimeLimit>') { [void]$problems.Add('ExecutionTimeLimit is not PT0S (default PT72H kills the host on day 3)') }
+    if ($xml -notmatch '<DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>') { [void]$problems.Add('DisallowStartIfOnBatteries is not false') }
+    if ($xml -notmatch '<StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>') { [void]$problems.Add('StopIfGoingOnBatteries is not false') }
+    if ($xml -notmatch '<StopOnIdleEnd>false</StopOnIdleEnd>') { [void]$problems.Add('StopOnIdleEnd is not false (a long-running host must not be stopped on idle-end)') }
+    if ($xml -match '<RunOnlyIfIdle>true</RunOnlyIfIdle>') { [void]$problems.Add('RunOnlyIfIdle is true - the host would only start on an idle machine') }
+    if ($xml -match '<RestartOnFailure>') { [void]$problems.Add('RestartOnFailure is present - remove it, it is measured not to fire and must not be sold as self-healing') }
+    if ($problems.Count -gt 0) {
+        foreach ($p in $problems) { Write-Output ('  VERIFY FAILED    : ' + $p) }
+        Unregister-ScheduledTask -TaskName $Name -Confirm:$false
+        Fail ('registered task did not match the required shape => rolled back (task ' + $Name + ' removed)')
+    }
+    Write-Output '  verified         : LogonTrigger + pinned node path + ExecutionTimeLimit=PT0S + battery/idle flags false + no RestartOnFailure'
+
+    Write-Output ''
+    Write-Output '  RESULT           : REGISTERED (logon autostart). It will start at the NEXT logon of this user.'
+    Write-Output ('  start it now     : schtasks /run /tn "' + $Name + '"')
+    Write-Output ("  log              : " + $logFile)
+    Write-Output '                     WARNING: the host prints its access URL with a ?token=... into this log.'
+    Write-Output '                     Treat the log as a credential-bearing file: do not paste it into chats,'
+    Write-Output '                     tickets or repos; redact the token if you must quote a line.'
+    Write-Output '  self-healing     : NONE. RestartOnFailure is deliberately not set (measured not to fire);'
+    Write-Output '                     if the process dies, nothing restarts it until the next logon.'
+    Write-Output ('  remove it with   : powershell -NoProfile -ExecutionPolicy Bypass -File "' + $PSCommandPath + '" uninstall -TaskName ' + $Name)
+}
+
+# --- uninstall (idempotent) ------------------------------------------------------------
+
+function Uninstall-Task {
+    param([string]$Name, [string]$DshHomeResolved)
+    $logFile = Get-TaskPath -Name $Name -DshHomeResolved $DshHomeResolved
+    Write-Output '=== dsh web autostart - uninstall ==='
+    $task = Get-ScheduledTask -TaskName $Name -ErrorAction SilentlyContinue
+    if (-not $task) {
+        Write-Output ("  " + $Name + " is not registered - nothing to do (idempotent).")
+        Write-Output '  RESULT           : NOT INSTALLED'
+        return
+    }
+    Unregister-ScheduledTask -TaskName $Name -Confirm:$false
+    $still = Get-ScheduledTask -TaskName $Name -ErrorAction SilentlyContinue
+    if ($still) { Fail ('unregister reported success but ' + $Name + ' is still present') }
+    Write-Output ("  removed          : " + $Name + "  (verified absent)")
+    Write-Output ("  log kept         : " + $logFile + " (exists=" + (Test-Path -LiteralPath $logFile) + ") - logs are evidence, not cleaned up")
+    Write-Output '  note             : an already-running dsh web process is NOT stopped by uninstall.'
+    Write-Output '  RESULT           : UNINSTALLED'
+}
+
+# --- dispatch ------------------------------------------------------------
+
+$dshHomeDefault = $DshHome
+if (-not $dshHomeDefault) { $dshHomeDefault = Join-Path $env:USERPROFILE '.dsh' }
+
+switch ($Command.ToLower()) {
+    'install' { Install-Task -Name $TaskName -Port $Port -DshHomeArg $DshHome -LogDirArg $LogDir }
+    'status' { Show-Status -Name $TaskName -DshHomeResolved $dshHomeDefault }
+    'uninstall' { Uninstall-Task -Name $TaskName -DshHomeResolved $dshHomeDefault }
+    'help' { Show-Usage }
+    '-h' { Show-Usage }
+    '--help' { Show-Usage }
+    default {
+        Write-Output ("unknown command: " + $Command)
+        Show-Usage
+    }
+}
+exit 0

package/engine/scripts/ziniao-auth-probe.sh

@@ -0,0 +1,268 @@
+#!/usr/bin/env bash
+# ziniao-auth-probe.sh —— 紫鸟**凭证/授权**心跳（W2 常驻 WebDriver 模式的配套）
+#
+# ## 回答的问题
+# 「常驻 WebDriver 模式后，还需要人工每 30 天点一次登录吗？」
+# WebDriver 模式的鉴权是**随请求走的**：每次调用都带 company/username/password，并用
+# `applyAuth` 申请/续期设备授权（官方 api-core.md）。所以自动化**不依赖 GUI 登录态**；
+# 而 GUI/Bridge 侧的登录在 ziniao-cli 1.1.3 起也能**程序化恢复**（`ziniao-cli zclaw login`
+# 用 API Key 登录本地浏览器，无需人工点击）。
+#
+# 但"不用人工"这件事不能靠推断：供应商文档里**没有**任何有效期/续期字样，我们也没有实测过
+# 30 天窗口。所以本脚本把这件事变成**可观测**：每天（去重）跑一次凭据链路探针，
+#   ① 先探免凭据的 `getRunningInfo`（WebDriver IPC 活着吗）
+#   ② 再探带凭据的 applyAuth + getBrowserList（授权链路活着吗）
+#   ③ 失败 ⇒ **先自己修**：`ziniao-cli zclaw login`（API Key 登录）→ 复探
+#   ④ 仍失败 ⇒ 响亮输出 + 落台账 + 遥测（**提前叫人**，而不是等下一票跑失败）
+# 这样 30 天窗口是"数据说的"，不是"猜的"；真需要人工时也会提前几天暴露（而不是当天才发现）。
+# 另外先探**客户端启动模式**：人工打开客户端 = GUI 模式 ⇒ 常驻 WebDriver IPC 必然不存在，
+# 这类"IPC 失败"的首因是模式不对（一句话可修），不要误报成"登录过期要人工登录"。
+#
+# 用法：
+#   bash scripts/ziniao-auth-probe.sh            # 带 12h 去重（默认；给定时器用）
+#   bash scripts/ziniao-auth-probe.sh --force     # 忽略去重，立刻探一次（排障用）
+#   bash scripts/ziniao-auth-probe.sh --quiet     # 只输出结论行
+# 退出码：0=正常 / 2=需要人工（授权链路不可用且自愈失败）/ 3=跳过（未配置凭据或无 CLI）
+set -uo pipefail
+
+# 仓库根：共享解析（脚本自身位置优先）—— 写死 ~/Code/argent-dsh 会让客户机
+# （克隆在 ~/.argent-dsh）上找不到本仓文件（2026-09-28 实测）
+. "$(dirname "${BASH_SOURCE[0]}")/lib/repo-root.sh"
+REPO="$(argent_repo_root "${BASH_SOURCE[0]}")"
+TTL_H="${ZINIAO_AUTH_PROBE_TTL_H:-12}"
+FORCE=0; QUIET=0
+for a in "$@"; do
+  case "$a" in
+    --force) FORCE=1 ;;
+    --quiet) QUIET=1 ;;
+  esac
+done
+
+log() { [ "$QUIET" = "1" ] || echo "[$(date '+%F %T')] $*"; }
+pick_py() {
+  local c
+  for c in "${ARGENT_PY:-}" "$HOME/.dsh/argent/venv/bin/python3" "$REPO/.venv/bin/python3" \
+           "$(command -v python3 2>/dev/null || true)"; do
+    [ -n "$c" ] && [ -x "$c" ] && { printf '%s' "$c"; return 0; }
+  done
+  return 1
+}
+PY="$(pick_py)" || { echo "❌ 找不到 python3" >&2; exit 3; }
+
+# 数据目录：**唯一判据**在 Python 单一实现（scripts/lib/argent_datadir.py，经 CLI 包装
+# scripts/argent-datadir.py）——⛔ 不在 bash 里重写三级链。取不到 ⇒ 响亮停住（fail-closed）。
+# 用**已解析好的 $PY**（上面 pick_py 验过可执行）：客户机 cron/launchd 的 PATH 极简，
+# 这里再 `command -v python3` 只会平白多一种失败模式。
+DATA="$("$PY" "$REPO/scripts/argent-datadir.py" 2>/dev/null || true)"
+if [ -z "$DATA" ]; then
+  echo "❌ $(basename "${BASH_SOURCE[0]}"): 数据目录判据不可用（$REPO/scripts/argent-datadir.py 取不到）⇒ 停住，不猜目录" >&2
+  exit 2
+fi
+STAMP="$DATA/.ziniao-auth-probe.stamp"
+command -v ziniao-cli >/dev/null 2>&1 || { log "未安装 ziniao-cli ⇒ 跳过（非紫鸟环境）"; exit 3; }
+
+# 去重：默认 12h 一次（定时器每 5 分钟跑，不必每轮都打供应商接口）
+if [ "$FORCE" != "1" ] && [ -f "$STAMP" ]; then
+  if [ "$(find "$STAMP" -mmin -$(( TTL_H * 60 )) 2>/dev/null | wc -l | tr -d ' ')" = "1" ]; then
+    log "授权探针 ${TTL_H}h 内已跑过 ⇒ 跳过（--force 可强制）"
+    exit 0
+  fi
+fi
+mkdir -p "$DATA"; : > "$STAMP"
+
+# ── ⓪-1 客户端**启动模式**：GUI 模式下 WebDriver IPC 本来就不存在 ──
+# 同一实例不能既是 GUI 又是 WebDriver；人工打开客户端会把常驻自动化模式顶掉，
+# 此时"IPC 不可用"的**首因是模式不对**，不是授权失效——先分清，再决定叫不叫人。
+client_mode="未运行"
+_main_pid="$(pgrep -f "[A]pplications/ziniao.app/Contents/MacOS/ziniao" 2>/dev/null | head -1 || true)"
+if [ -n "$_main_pid" ]; then
+  _args="$(ps -o command= -p "$_main_pid" 2>/dev/null || true)"
+  case "$_args" in
+    *--run_type=web_driver*) client_mode="web_driver（常驻自动化模式）" ;;
+    *) client_mode="GUI（人工模式，无 WebDriver IPC）" ;;
+  esac
+fi
+log "⓪-0 客户端启动模式：${client_mode}"
+
+# ── ⓪ 客户端登录态（用户 2026-09-24：登录按钮下方写的是"30 天"）──
+# 这一层是**客户端会话**（GUI/Bridge 用），与 WebDriver 的凭据链路是两回事：
+# 30 天到期只影响前者；后者每次调用自带 company/username/password + applyAuth。
+# 把两层分开报告，叫人时才能一句话说清"该点哪里"。
+# 瞬态容忍（2026-09-24 实测）：客户端**刚启动**的那几秒，doctor 会报
+# 「客户端已启动，但尚未登录」（登录态还没恢复）⇒ 立刻断言"未登录"是假警报。
+# keepalive 拉起客户端后会**马上**调本探针，正好踩这个窗口 ⇒ 这里复探最多 3 次（5s/10s 退避）。
+_probe_login_state() {
+  ziniao-cli doctor 2>&1 | grep -oE "客户端登录用户: [^ ]+|客户端已启动，但尚未登录|CLIENT_LOGGED_OUT" | head -1
+}
+_doctor_out="$(ziniao-cli doctor 2>&1 || true)"
+client_login="$(printf '%s' "$_doctor_out" | grep -oE "客户端登录用户: [^ ]+|客户端已启动，但尚未登录|CLIENT_LOGGED_OUT" | head -1)"
+_transient=0
+case "$client_login" in
+  *尚未登录*|*CLIENT_LOGGED_OUT*)
+    for _w in 5 10; do
+      sleep "$_w"
+      _again="$(_probe_login_state)"
+      case "$_again" in
+        *尚未登录*|*CLIENT_LOGGED_OUT*) : ;;
+        *) client_login="$_again"; _transient=1; _doctor_out="$(ziniao-cli doctor 2>&1 || true)"; break ;;
+      esac
+    done
+    [ "$_transient" = "1" ] && log "⓪ 首探为「未登录」，${_w}s 后复探已恢复 ⇒ 客户端刚启动的瞬态（不是真失效）"
+    ;;
+esac
+[ -n "$client_login" ] || client_login="（未取到）"
+# 官方文档未见有效期条款：api-core.md 只规定"随请求带凭据 + applyAuth"，没有任何"到期/续期"字样
+# ⇒ 30 天窗口只能靠观测（本探针），不能靠推断。
+# 终端绑定：客户端 6.28+ 才支持该项检查（旧客户端 doctor 会写"版本不支持"，不是故障）
+if printf '%s' "$_doctor_out" | grep -q "终端已绑定"; then terminal_bind="已绑定"
+elif printf '%s' "$_doctor_out" | grep -q "不支持终端绑定检查"; then terminal_bind="客户端过旧（不支持该检查）"
+elif printf '%s' "$_doctor_out" | grep -q "未绑定"; then terminal_bind="**未绑定**"
+else terminal_bind="未知"; fi
+log "⓪ 客户端登录态：${client_login}｜终端绑定：${terminal_bind}"
+log "   口径：界面上的「30 天」是**记住密码**（客户端控件缓存，不是会话有效期）；"
+log "   会话真掉了也不用人点——③ 会用 API Key 走 zclaw login 程序化恢复（客户端 6.28+ 起可用）"
+
+# ── ① WebDriver IPC（免凭据）──
+wd_out="$("$PY" - "$REPO" <<'PY' 2>&1
+import importlib.util, pathlib, sys
+repo = sys.argv[1]
+spec = importlib.util.spec_from_file_location("orch", pathlib.Path(repo) / "scripts" / "orchestrator.py")
+m = importlib.util.module_from_spec(spec); sys.modules["orch"] = m; spec.loader.exec_module(m)
+cfg = m.load_config()
+try:
+    items = m.wd_running_info(cfg)
+    print(f"OK ipc windows={len(items)} {m.window_inventory(cfg)}")
+except Exception as exc:
+    print(f"IPC_FAIL {type(exc).__name__}: {exc}")
+PY
+)"
+case "$wd_out" in
+  OK\ ipc*) log "① WebDriver IPC 正常：${wd_out#OK ipc }" ;;
+  *) log "① WebDriver IPC **不可用**：${wd_out}（常驻模式应先启动客户端；本轮先尝试自愈）" ;;
+esac
+
+# ── ② 带凭据的授权链路（applyAuth + getBrowserList）──
+cred_out="$("$PY" - "$REPO" <<'PY' 2>&1
+import importlib.util, pathlib, sys
+repo = sys.argv[1]
+spec = importlib.util.spec_from_file_location("orch", pathlib.Path(repo) / "scripts" / "orchestrator.py")
+m = importlib.util.module_from_spec(spec); sys.modules["orch"] = m; spec.loader.exec_module(m)
+cfg = m.load_config()
+creds = m._load_wd_creds()
+if creds is None:
+    print("SKIP 未配置 ziniao-webdriver.env（ZINIAO_WD_COMPANY/USERNAME/PASSWORD）")
+    raise SystemExit(0)
+try:
+    m.wd_apply_auth(cfg, creds)          # 授权（幂等：等价于"续期/确认"）
+    stores = m.wd_list_stores(cfg, creds)
+    print(f"OK auth stores={len(stores)}")
+except Exception as exc:
+    print(f"AUTH_FAIL {type(exc).__name__}: {exc}")
+PY
+)"
+case "$cred_out" in
+  OK\ auth*) log "② 授权链路正常：${cred_out#OK auth }" ;;
+  SKIP*)     log "② 跳过：${cred_out#SKIP }"; exit 3 ;;
+  *)         log "② 授权链路**失败**：$cred_out" ;;
+esac
+case "$wd_out$cred_out" in
+  *OK\ ipc*OK\ auth*) log "✅ 紫鸟凭证/授权心跳正常（无需人工干预）"; exit 0 ;;
+esac
+
+# ── ③ 自愈：可用 API Key 程序化登录（ziniao-cli 1.1.3+ 的 zclaw login，无需人工点击）──
+# ⚠️ 供应商对该接口**限流**：实测连续调用会返回
+#    `{"ok":false,"error":{"type":"auth","message":"apiKey 登录验证次数过多，请1分钟后再试"}}`（exit 3）。
+# 这类失败**不代表 Key 失效**，但会被误读成"自愈失败"⇒ 必须两件事：
+#   ① 同一个机器 N 秒内只试一次（默认 600s，可用 ZINIAO_LOGIN_MIN_INTERVAL_S 调）；
+#   ② 命中限流时单独归类，不写成"API Key 无效/终端未绑定"。
+LOGIN_STAMP="$DATA/.ziniao-auth-probe.login-attempt"
+LOGIN_MIN_S="${ZINIAO_LOGIN_MIN_INTERVAL_S:-600}"
+login_limited=0
+if ziniao-cli zclaw login --help >/dev/null 2>&1; then
+  _since=999999
+  if [ -f "$LOGIN_STAMP" ]; then
+    _since="$(find "$LOGIN_STAMP" -mmin -$(( (LOGIN_MIN_S + 59) / 60 )) 2>/dev/null | wc -l | tr -d ' ')"
+    _since=$([ "$_since" = "1" ] && echo 0 || echo 999999)
+  fi
+  if [ "$_since" = "0" ]; then
+    log "③ 跳过程序化登录：${LOGIN_MIN_S}s 内已试过（避免触发供应商限流）；需强制：ZINIAO_LOGIN_MIN_INTERVAL_S=0"
+    login_limited=2   # 2 = 本轮未判定（既不是成功也不是失败）
+  else
+    log "③ 尝试程序化登录（ziniao-cli zclaw login，使用本地 API Key）…"
+    mkdir -p "$DATA"; : > "$LOGIN_STAMP"
+    login_out="$(ziniao-cli zclaw login 2>&1)"; login_rc=$?
+    if [ "$login_rc" = "0" ]; then
+    log "③ 程序化登录返回成功 ⇒ 复探一次"
+    retry="$("$PY" - "$REPO" <<'PY' 2>&1
+import importlib.util, pathlib, sys
+repo = sys.argv[1]
+spec = importlib.util.spec_from_file_location("orch", pathlib.Path(repo) / "scripts" / "orchestrator.py")
+m = importlib.util.module_from_spec(spec); sys.modules["orch"] = m; spec.loader.exec_module(m)
+cfg = m.load_config(); creds = m._load_wd_creds()
+if creds is None:
+    print("SKIP"); raise SystemExit(0)
+try:
+    m.wd_apply_auth(cfg, creds); stores = m.wd_list_stores(cfg, creds)
+    print(f"OK auth stores={len(stores)}")
+except Exception as exc:
+    print(f"AUTH_FAIL {type(exc).__name__}: {exc}")
+PY
+)"
+      case "$retry" in
+        OK\ auth*) log "✅ 自愈成功（zclaw login）⇒ 无需人工"; exit 0 ;;
+        *) log "✗ 自愈后仍失败：$retry" ;;
+      esac
+    else
+      case "$login_out" in
+        *次数过多*|*请1分钟后再试*)   # ⚠️ 模式里不能带空格（bash 会把空格当分隔符）
+          login_limited=1
+          log "⚠️ 程序化登录被**限流**（${login_out##*message\":\"}）⇒ 这不是 Key 失效；"
+          log "   ${LOGIN_MIN_S}s 内本机不再重试。要立刻重判：ZINIAO_LOGIN_MIN_INTERVAL_S=0 bash scripts/ziniao-auth-probe.sh --force" ;;
+        *)
+          log "✗ 程序化登录失败（API Key 无效/终端未绑定？）：$(printf '%s' "$login_out" | tr -d '\n' | head -c 200)" ;;
+      esac
+    fi
+  fi
+else
+  log "③ 本机 ziniao-cli 无 zclaw login（<1.1.3）⇒ 无法程序化登录"
+fi
+
+# ── ④ 需要人工：响亮输出 + 台账 + 遥测（提前叫人，而不是等下一票跑失败）──
+_gui_mode=0
+case "$client_mode" in *GUI*) _gui_mode=1 ;; esac
+{
+  if [ "$_gui_mode" = "1" ] && case "$wd_out" in *FAIL*) true ;; *) false ;; esac; then
+    echo "❌ 紫鸟**当前是 GUI 模式**（人工打开过客户端）⇒ 常驻 WebDriver 模式被顶掉，IPC 不存在"
+    echo "   这不是授权/登录过期：同一客户端实例不能同时是 GUI 与 WebDriver。"
+    echo "   处置：关掉这个 GUI 实例，再按部署约定重启为常驻模式："
+    echo "         rm -f ~/.dsh/argent/PAUSE_ZINIAO_KEEPALIVE && bash scripts/ziniao-keepalive.sh run"
+  else
+    echo "❌ 紫鸟**授权链路不可用且自愈失败** ⇒ 需要人工处置（客户端登录窗口的提前预警）"
+  fi
+  echo "   分层结论：客户端启动模式=${client_mode}"
+  echo "             客户端登录态=${client_login}（GUI/Bridge 会话）"
+  echo "             WebDriver IPC=${wd_out}（免凭据）"
+  echo "             授权链路=${cred_out}（applyAuth/getBrowserList，随请求带凭据）"
+  case "$client_mode" in
+    GUI*) echo "   ⇒ 判定：**启动模式不对**（GUI 实例占位，WebDriver IPC 不会起来）⇒ 先按上面第一行处置" ;;
+    *) case "$client_login" in
+         *尚未登录*|*CLIENT_LOGGED_OUT*) echo "   ⇒ 判定：**客户端登录态失效**（这一层需要人点一次；WebDriver 自动化本身未必受影响）" ;;
+         *) echo "   ⇒ 判定：客户端登录态看起来正常 ⇒ 问题在 WebDriver 侧（看上面 IPC/授权两行）" ;;
+       esac ;;
+  esac
+  echo "   处置顺序：① 打开紫鸟客户端确认登录态；② 若被登出，先试 ziniao-cli zclaw login；"
+  echo "             ③ 仍不行再人工登录一次（密码/短信验证无法自动化）"
+  echo "   影响：常驻 WebDriver 模式下，授权失效会让所有票在开跑前失败（不是票的问题）"
+  if [ "$login_limited" = "1" ]; then
+    echo "   ⚠️ 注意：本次「程序化登录」被供应商限流，**未真正判定**登录态；1 分钟后可复跑确认"
+  elif [ "$login_limited" = "2" ]; then
+    echo "   ⚠️ 注意：本次跳过了程序化登录（${LOGIN_MIN_S}s 内已试过）⇒ 登录态结论为**未判定**"
+  fi
+} >&2
+"$PY" "$REPO/scripts/flow_ledger.py" --case-id "auth__ziniao" --event blocked \
+  --by ziniao-auth-probe --detail "紫鸟授权链路不可用且 zclaw login 自愈失败：IPC=${wd_out:0:60} AUTH=${cred_out:0:60}" \
+  >/dev/null 2>&1 || true
+"$PY" "$REPO/scripts/telemetry.py" --emit --kind engine --flow full --error-class needs_human \
+  --detail "紫鸟授权链路不可用（需人工；已尝试 zclaw login）" >/dev/null 2>&1 || true
+"$PY" "$REPO/scripts/telemetry.py" --flush >/dev/null 2>&1 || true
+exit 2