主系統斷線，現場照樣能登入、能掃、能查線路，連回來自動補傳

狀態：v2：全部實作合回 feature/FR-139，決策者手測中｜日期：2026-10-28｜母卡 CM-3109、子卡 CM-3110～CM-3168（v1）、CM-3170～CM-3196（手測追加，§10）｜前作：FR-157（主控台殼、入場券、救援碼、工具帳密）、FR-156（8444 門、第三方元件掃描在 Agent）、FR-056（派工骨架）、FR-129（清冊） 討論稿（選項推演、§13 全案重新檢視、§14 全量工作清單）：discussion.html｜雛形：prototype/index.html（十二幕互動，上方「跟著走」四條流程） 開發 branch：五個 repo 2026-10-26 查皆在 feature/FR-139；runner 開工 git branch --show-current 再確認，不對就停下問，不切

🔴 這份是設計決策，不是現況。 決策（§3）與行為規則（§5）已更新到 v2；§4 現況盤點與 §6 拆卡表的行號與座標停在 v1 定稿當時。上線後的畫面與 API 現況看 SPEC 頁。

老闆 2026-10-26：Agent 與主系統斷線時仍能獨立作業——直接打 Agent 網址登入、不經任務按八支掃描工具、網路除錯（ping、traceroute 這類，使用者勾選，有些公司會告警）、斷線不停工復線補傳、多據點（高雄、台南、日本、新加坡）各自作業報告回台北；不能變跳板或駭客工具。決策者追加：登入方式比較業界模式、LDAP（老闆會要）、重啟 Agent、總覽像儀表板、登入頁與殼照主系統改 Agent 模式。

現況（FR-157 後）：Agent 8444 有主控台三頁（總覽、檢測工具、檔案），只能從主系統簽入場券跳進去；斷線時沒有任何登入方式。八支工具全由主系統心跳領任務執行，Agent 自己沒有「選工具、填目標、按執行」的入口。結果回報失敗就丟。沒有網路除錯。

做完之後

sequenceDiagram
    participant U as 現場使用者
    participant AG as Agent 8444
    participant M as 主系統
    M-->>AG: 心跳回應：離線操作者名單（誰、範圍、到期）＋授權清冊＋CIDR
    Note over AG: 名單與清冊存本機 SQLite；Agent 端沒有「新增使用者」
    U->>AG: 直接打網址，登入頁依連線狀態給分頁
    alt 在線
        U->>M: 「主系統登入」跳回主系統驗，帶入場券回來
    else 離線
        U->>AG: 帳號＋離線密碼（或 AD 密碼）；本機管理員 local-admin
        AG->>AG: 名單內？未到期？密碼對？沒被鎖？四種失敗同一回應
    end
    AG-->>U: 既有 30 分鐘 session（scope 照名單範圍）
    U->>AG: 掃描工具：選工具→選目標→執行
    AG->>AG: 目標過 allowed_targets.check()（與派工同一支）；未同步＝一律拒
    AG->>AG: 走 _run_one 同一條，result 走本機 sink 寫 local_runs
    AG-->>M: 心跳後 outbox.drain()：摘要與報告參照回主系統（任何終態冪等）

flowchart LR
  R[任務／手動執行完成] --> S{主系統連得到？}
  S -->|是| M[(主系統 agent_tasks／agent_local_runs)]
  S -->|否| O[(Agent SQLite outbox)]
  O -->|心跳成功後 drain 50 筆／次，送成功才刪| M
  M -->|同 uid 任何終態重送| I[回 200 不重做]
  T[主系統派工 Agent 離線] -->|7 天內| W[顯示「等待回傳」不計失敗]
  T -->|超過 7 天| F[reaper 標 failed agent_unreachable]

整案：Agent 主控台多一頁登入與四個分頁（掃描工具、網路除錯、執行紀錄、服務與重啟），主系統連得上照舊跳轉，連不上用事先授權的離線密碼或本機管理員；能掃誰一律照主系統清冊；結果先存 Agent、連回自動補傳；LDAP 抽套件共用。

決策者檢查法（每階段對照雛形幕）：P1 幕 1、10、12；P2 幕 2～6；P3 幕 5 回傳欄、幕 10 下半；P4 幕 7、11。PM 裁全做，無可砍項。

全文與選項推演在討論稿 §9；這裡列定案與一句理由。

每列都開檔確認過（討論稿 §13.1 實查）。行數＝2026-10-26 現況。

5.1 登入與身分（P1）

Agent 端資料（SQLite v2，P0-4）：

登入 API（P1-4）：

GET  /console/state                 無需 session；回 {net: online|offline|unsynced|disabled, offline_days, agent:{name,ip,version}, ldap_source}
POST /console/local-session         body ≤1KB {sub, password, method: password|ldap}；所有失敗同 401 同 body {error_code:"CONSOLE_LOGIN_FAILED"}；成功發既有 session
POST /console/api/me/password       {old, new}；只能改自己（local-admin 或本人離線密碼）；12 碼

判定順序（local_auth.verify）：①sub == LOCAL_ADMIN_SUB → 查 local_credentials，不受到期與離線天數影響。②找人：method=ldap 且目錄是 AD → sub 是 AD 帳號，用 offline_operators.get_by_ad_account 反查名單（網域與帳號各自不分大小寫比對，命中不是恰好一人就當找不到，不猜）；其餘情況 sub 就是主系統帳號。找不到、已撤銷、到期 → 失敗。③method=password 另受離線天數限制、本機關閉離線登入時一律拒；method=ldap 不受天數限制，只問 AD、不退回離線密碼，沒綁 AD 的人 AD 分頁一律失敗。④鎖定：failed_count >= 5 且 locked_until 未到 → 失敗。所有失敗同一回應、反查不到也照樣跑一次雜湊（回應時間不洩漏有沒有人綁）；原因只進 log 與稽核（not_listed／method_blocked／credential_rejected）。之後 session、稽核、鎖定計數一律記主系統帳號；已登入的離線操作者每個請求都重驗名單與天數。

未同步判定：allowed_targets.received and offline_operators.received_at is not None。未同步時 state.net = unsynced，掃描與除錯（主系統連線診斷除外）入口 403。

主系統端（P0-5／P0-6／P1-1／P1-2）：remote_agent_offline_operators（agent_id、user_id、scope JSONB、expires_at、local_password_set_at、revoked_at、tenant_id、RLS FOR ALL）。授權 API 三核：agent 屬本租戶、user 屬本租戶、user 在主系統至少持有一顆 Agent 能力點；授權只收 {user_id, expires_at}，不收範圍（D23）。心跳回應 offline_operators[]（sub、display_name、ad_account、scope、expires_at、revoked），其中 scope 由 _scopes_for(user_id) 依當下能力點即時算、ad_account 取 jedi-iam user_auth_providers.provider_login（使用者用 AD 登過主系統一次才有）。表上的 scope 欄只是授權當下的快照。remote_agents 加 console_allow_cidr、outbox_size、local_admin_set、uptime_sec、restart_requested、ldap_source。能力點 detection.remote-agent.{run-local-scan,net-diag,restart}，路由綁 remote-agent-manage ANY。

CIDR（P1-5）：AGENT_CONSOLE_ALLOW_CIDR（安裝時問，空＝不限）；心跳收 console_allow_cidr 取交集，空交集忽略＋稽核；127.0.0.0/8／::1 永遠放行；browser_plane_server 在 accept 後第一件事檢查。主系統端存前驗交集非空（Agent 回報 console_allow_cidr_installed）。

安裝與升級（P1-6，雛形幕 12）：新裝題目 4/5 本機管理員密碼（12 碼、二次輸入、argon2id 寫 local_credentials）、5/5 白名單；完成畫面保管框。升級：[ -t 0 ] 真照新裝問（Enter 跳過），假只紅字。新子命令 reset-admin-password／wipe／console-allow-cidr reset 進 scripts/install/lib/，case 一行 source。do_re_enroll 擴充：outbox 非空先問，清名單、清冊、local_runs、outbox。cmd_upgrade 前查執行中任務，互動問、非互動標 cancelled。

5.2 手動掃描（P2-1～P2-3）

sink 抽取（P2-1）：

class TaskSink(Protocol):
    def ack(self, task) -> None
    def result(self, task, outcome) -> None       # 失敗可拋，由 outbox 接
    def report(self, task, file) -> str           # 回 file_uid
CloudSink  = 現況三個函式搬進來，行為不變
LocalSink  = 寫 local_runs；report 走既有 file_upload_service；result 同時入 outbox(kind=local_run)
_run_one(task, sink)  # 既有呼叫改傳 CloudSink()；手動執行傳 LocalSink()

並發：_RUNNING_TASKS 既有；手動執行加計數，掃描 >2 或診斷 >1 進佇列。取消走既有 cancel_event。離線 30 天／未同步在 start() 擋。

ZAP 網址納清冊：allowed_targets._target_networks 加 _URL_FIELDS（ZAP 的 target_url／urls），urlsplit().hostname → socket.getaddrinfo → 每個 IP 過 _is_allowed_ip；解不到＝拒。主系統派的 ZAP 一併受管。

API（P2-2）：GET /console/api/scan/tools（八支：code、name、configured、capabilities_ok）；GET .../targets（清冊：devices[]、networks[]、version、received_at）；GET .../schema/{tool}（既有 tool_schemas）；POST .../runs（{tool, targets[], params} → 清冊 check → credential_resolver → LocalSink → 回 local_uid）；GET .../runs/{uid}；POST .../runs/{uid}/cancel。scope run-local-scan。第三方元件：PUT /scan-input/<uid> 多認本機 session（scan_input.py 驗票處加分支），執行走既有 sbom_scan connector，結果走 source_scans 既有收件並標 source=agent_manual。

5.3 網路除錯（P2-4～P2-6）

core/netdiag/：dashboard.py 讀 ip -j addr／ip -j route／resolvectl／ss -ltn／ethtool／nmcli，容器形態（/.dockerenv 或無 NetworkManager）回 unavailable；回 {info:{...}, lamps:[{name,state,why}]} 資訊與燈分開。

十項 probe 共同規則：目標先過 allowed_targets.is_allowed(ip) 或三固定例外（主系統 host、預設閘道、DNS，由 Agent 自己算不收 body）；subprocess.run([...], shell=False, timeout=固定)；輸出長度上限 64KB、固定 regex 解析；連線之間 sleep(1)；同目標每分鐘 3 輪（記憶體 token bucket）。各項逾時：ping 10s／DNS 5s／埠每個 3s（上限 5 個）／TLS 10s／HTTP 10s／SSH 10s／MTU 10s／cloud 序列 60s／traceroute 60s（無 CAP_NET_RAW 回 unavailable）／mtr 式 60s。TLS 用 ssl.create_default_context()，捕 SSLCertVerificationError 當結果；程式不得出現 CERT_NONE。HTTP 用 httpx：不跟隨跨 host 轉址、最多 5 跳、只取標頭、大小上限。

limits.estimate(selection)（D20）：連線數 = ping 4 ＋ DNS 1 ＋ 埠 N ＋ TLS 1 ＋ HTTP 1 ＋ SSH 1 ＋ MTU 1 ＋ cloud 5 ＋ traceroute 30 ＋ mtr 60；秒數 = 連線數 ＋ 各項逾時估；等級：含 mtr＝高，含 traceroute 或連線數 >10＝中，否則安靜。POST runs 等級非安靜需 confirm=true。

verdict.py：確定性規則表（fixture 驅動），輸出結論／依據／建議動作三句；主系統連線診斷固定序列 DNS → 閘道 → 主系統 → 443 → TLS（describe_tls_failure）→ 心跳端點 → 時鐘（clock_skew）→ 代理，三種結論：連不到／連得到但身分被拒（401／403）／憑證驗不過。

報告：JSON＋文字＋PDF（既有 WeasyPrint 路徑，html.escape）；存 upload_files；local_runs.kind=diag。

5.4 續傳與主系統端（P3）

outbox（P3-1）：CloudSink.result 失敗 → 入列（idempotency_key = f"{kind}:{uid}:{status}"）；心跳成功後 drain()：依 created_at 送最多 50 筆，退避 1／2／4／8 分上限 1 小時，送成功才刪；heartbeat_status 加遲滯（3 敗→offline、2 成→online）；磁碟低於門檻停止入列 audit 類。心跳 payload 帶 outbox_size。

主系統冪等（P0-6）：receive_result 短路條件 task.status in TERMINAL → 回 200 不重寫；POST /agents/local-runs 批次 ≤50、agent_id 從通行證取、(agent_id, local_uid) 唯一衝突視為已收；已停用／撤銷 Agent 拒收。

reaper（P0-6 套件＋P3-5 接線）：run_daily_tick()：agent_tasks.status in (dispatched, running) 且該 Agent last_heartbeat_at < now - 7d → failed、fail_reason=agent_unreachable；0 筆不寫 log。BE core/scheduler_agent.py 註冊 @_job_scoped("agent_task_offline_reaper")，scheduler.py 只加一行。

離線顯示（P3-4a／P3-4b）：_enrich_online 加 agent_offline_waiting、agent_last_heartbeat_at；FE 任務頁橫幅、清單「待傳」「LDAP」欄。

5.5 LDAP（P0-1／P0-2／P0-3／P0-7／P4-1～P4-3）

jedi-ldap（新套件，只靠 ldap3）：

@dataclass class LdapConfig: host, port=389, encryption="starttls"|"ssl"|"none", base_dn, is_ad, bind_user, bind_password, ca_pem=None
class FingerprintStore(Protocol): get(host) -> str|None; set(host, fp, meta)
class LdapDirectory:
    def __init__(cfg, store: FingerprintStore)
    def test_connect() -> ConnectResult(ok, reason: "ok"|"unreachable"|"cert_changed"|"cert_invalid"|"bind_failed"|"plaintext_warning", fingerprint, cert_meta)
    def verify_user(username, password) -> DirectoryUser(uid, name, email, groups) | raises LdapAuthError(reason)

首次連線 store.get(host) is None → 記指紋；之後不同 → cert_changed，不連。encryption="none" 回 plaintext_warning。不 import Flask、不碰任何表。

jedi-iam 瘦身（P0-2）：LdapAdapter 只留「DirectoryUser.uid → user_auth_providers → users」綁定段；LDAP bind 失敗走既有 login_failed_count 同一路徑；LDAP_VERIFY_CERT 退役，LDAP_TRUSTED_FINGERPRINT／LDAP_TRUSTED_AT 由 system-core 設定組提供（P0-3）並當 FingerprintStore；/ldap/connect-test 換 host 不帶舊密碼。

Agent 三選一（P4-1）：ldap_source ∈ synced／local／none。synced：心跳 ldap_config 帶主系統設定與服務帳密（主系統解密後經 mTLS 心跳下發；Agent 收到後用自己的 credential_store key 加密保存、不落明文、不進 log），指紋由主系統下發；local：主控台表單（secret_form.py）存 credential_store，指紋存 local_credentials（kind=ldap_fingerprint）；none：略過。登入分支見 5.1 ③。Nuitka --include-package=ldap3,jedi_ldap。

5.6 儲存設定搬 UI（P2-8a／P2-8b）

secret_form.py：通用「欄位定義 → 驗證 → 祕密欄進 credential_store、其餘進設定檔 → 測試連線 hook → 套用 hook」。工具帳密（既有）、儲存設定、LDAP 自設三者各一份欄位定義。儲存設定的表單只有一個選項「系統內建 SeaweedFS」（D22），GET 不回任何端點、帳號、金鑰，只回 current_type 說明現在存哪；沒有內建儲存的機器（原生安裝、源碼模式）套用與測試回 409 並指向 CLI；「改回安裝時設定」保留。套用後 storage 模組 reload，不重啟。FE SecretForm.vue 同理三頁共用。

5.7 安全規則對照

全表在討論稿 §13.6；每張卡的紀律段帶「資安規範」行，runner 回寫列對到哪幾條。本案特別要守：四種登入失敗同回應（SR-01.1）、body 上限在 before_request（SR-04.1）、機器身分只認通行證且只動自己名下（SR-01.6／01.7）、新表 RLS FOR ALL（SR-02.1）、授權三核（SR-02.4）、argon2id 且 API 不回雜湊（SR-06.1）、密碼欄進遮罩（SR-06.2）、subprocess 不經 shell（SR-04.8／04.10）、CERT_NONE 禁用（SR-03.2）、兩條例外登記（§3 callout）。

批（Stage）＝工作坊同時開幾個小弟一起跑的那一組：同一批不改同一個既有檔、不依賴對方產出、不搶同一外部資源。階段（P0～P4）只是分組標籤。底表在 handoff/cards.py，兩個斷言已過：依賴都在更早的批；同批同 repo 無兩張卡改同一既有檔。

登記型檔先佔位（解掉 7 組撞檔）：core/console/routes.py 由 P1-4 一次掛四支 blueprint（後三支先空殼）；core/enroll.py 由 P1-3 一次掛三個 observer（後兩支先 no-op）；console/Shell.vue 由 P1-7a 一次寫全九項選單（view 懶載入指向佔位）並佔好 i18n key。後面的卡只填自己的檔。

repo 分布：evidence-agent 15、FE 11、BE 8、jedi 套件 6、test 1。套件異動（發版前統一確認）：jedi-ldap 新建、jedi-iam、jedi-system-core、jedi-remote-agent；開發期走 path dependency，發版等令。

決策者功課（開工前）：批 1 派出前確認五個 repo 都在 feature/FR-139。卡號對照見 handoff/FR-166-STATE.md 任務總表。

v1 的 41 張卡合回後，決策者手測再追加 29 張（含首腦直接修的一批）。決策層的變動已併入 §3（D2、D17、D22、D23）與 §5；這裡列每張卡做了什麼。

登入與身分

主控台

主系統

首腦直接修（未開卡）：主控台贅述刪除、執行紀錄頁重做（今日／自訂區間、⋮ 操作、重新執行、失敗原因可複製）、錯誤訊息遮罩、麵包屑、版本號加 v；主系統 Agent 管理頁「連線至 Agent」、離線操作者對話框改版、角色權限頁補漏翻譯、主系統「檢測工具」頁先隱藏。施工細節在各 commit 與 CM-3177 卡尾。