dsh-mizar 0.8.2 → 0.8.3

package/README.md

@@ -11,38 +11,60 @@
 
 ## 一、装插件
 
-插件在 npm 上叫 **`dsh-mizar`**。命令行和图形界面两种装法，装完都要**重启 DSH** ——
-插件只在启动时加载，不重启等于没装。
+**推荐用 npm 装**:插件已发布到 npm,包名 **`dsh-mizar`**,与当前 DSH 运行时(0.2.1-rc.2)对齐。
+装完都要**重启 DSH** —— 插件只在启动时加载,不重启等于没装。
 
-### 方式 A：图形界面（不想开终端就用这个）
+### 推荐:图形界面(不碰终端)
 
-1. 打开 DSH，左侧栏点 **插件（Plugins）**
-2. 安装输入框里填 **`dsh-mizar`**，点安装
-3. 重启 DSH
+1. 打开 DSH,左侧栏点 **插件(Plugins)**
+2. 安装输入框里填 **`dsh-mizar`**,点安装
+3. 确认它弹出来的包名 / 版本 / 描述
+4. 重启 DSH
 
-安装框同时接受 **npm 包名**（`dsh-mizar`）、**GitHub 地址**（`ShirazuNagisa/DSH-Mizar`）、
-**本地 `.tgz`** 或**目录路径**；装之前它会先把包名、版本、描述报给你确认。
-
-### 方式 B：命令行
+### 推荐:命令行
 
 ```sh
-dsh plugin --profile desktop add dsh-mizar          # npm 正式版
-dsh plugin --profile desktop add dsh-mizar@0.8.2    # 锁定版本
+dsh plugin --profile desktop add dsh-mizar          # 跟随 npm 最新版
+dsh plugin --profile desktop add dsh-mizar@0.8.2    # 锁定某个版本
 ```
 
-尝鲜（还没发版的提交）用 GitHub 直装：
+两种装法都会把依赖写成 `dsh-mizar@^x.y.z`。升级只要再跑一次 `add dsh-mizar@latest`。
 
-```sh
-dsh plugin --profile desktop add ShirazuNagisa/DSH-Mizar
-```
+重启后侧边栏会出现 **DSH-Mizar** 面板。
+
+### 为什么是 npm,而不是 GitHub 直装
+
+| | **npm(推荐)** | GitHub 直装 |
+|---|---|---|
+| 版本 | 有版本号,可锁 `@0.8.2` | 跟随 `main` 最新提交,不可锁 |
+| 可追溯 | `npm view dsh-mizar versions`、`npm outdated` | 只有 commit hash |
+| 完整性 | registry **sha512 校验** | 无包完整性校验 |
+| 前提 | 只要能访问 registry | 需要 git + pnpm 的 git 支持 |
+| 适合 | **所有人** | 只适合尝鲜未发布的提交 |
 
-离线 / 内网就传一个 `.tgz` 过去：
+### 备选:GitHub / 本地 tarball
 
 ```sh
+# 尝鲜:装 main 上还没发版的提交
+dsh plugin --profile desktop add ShirazuNagisa/DSH-Mizar
+
+# 离线 / 内网:在有网的机器上 npm pack,再把 .tgz 传过去
+npm pack dsh-mizar
 dsh plugin --profile desktop add /path/to/dsh-mizar-0.8.2.tgz
 ```
 
-重启后侧边栏会出现 **DSH-Mizar** 面板。
+### 装不到最新版 / 镜像同步延迟
+
+插件发布在 npm 官方源(`registry.npmjs.org`)。国内镜像(如 `registry.npmmirror.com`)偶尔滞后,
+表现是 `pnpm` 抓到一个旧的或占位版本。两种情况:
+
+- **加 `--registry` 直连官方源**:
+  ```sh
+  dsh plugin --profile desktop add dsh-mizar@0.8.2 --registry=https://registry.npmjs.org
+  ```
+- 或者去 [npmmirror 同步页](https://npmmirror.com/sync/dsh-mizar) 点一次「同步」,等镜像更新。
+
+> GUI 的安装框走的是本机默认 registry;镜像没同步时,用上面的 CLI 命令更稳。
 
 ### 版本必须与 DSH 对齐
 
@@ -97,8 +119,52 @@ Plugin dsh-mizar@0.8.2 is incompatible with dsh 0.2.1-rc.2
 **一轮结束不会立刻推。** DSH 里一个指令常常连着跑好几个 turn，每个 turn 都推一次等于一个
 指令三条通知 —— 所以插件会等这个会话安静 15 秒才发。正在看着 App 的时候什么都不发。
 
+**锁屏上的 Live Activity 会跟着结束。** iPhone 把正在跑的会话画在锁屏 / 灵动岛上计时；
+App 被挂起时它自己没机会收尾。所以 App 会把这次活动的推送令牌随注册交给插件，插件存下来、
+转给中继；会话跑完、且手机上还看得到的会话一个都不在跑时，那条「跑完了」的通知会让中继
+顺手结束 Live Activity —— 任务结束后计时不会一直涨。
+
 推送要 Apple 的签名密钥，密钥只能放在服务器上（放在插件里就等于公开）。**用官方中继
-什么都不用做**；自建中继需要配 `apns`，见 [relay-deployment.md 第 10 节](docs/relay-deployment.md)。
+什么都不用做**；自建中继需要配 `apns`，见
+[Relay 仓库的部署文档第 10 节](https://github.com/ShirazuNagisa/DSH-Mizar-Relay/blob/main/docs/deployment.md#10-push-notifications)。
+
+## 四·五、发布(维护者)
+
+发布走 **trusted publishing(OIDC)**:GitHub Actions 用一次性的 OIDC 身份向 npm 换发布凭证,
+**没有长期令牌,也没有验证码要输**。发布就是推一个版本 tag。
+
+一次性配置(npmjs.com,用账号的安全密钥验证):
+
+1. 打开 `dsh-mizar` 包页面 → **Settings** → **Publishing access** → **Trusted publisher** →
+   **GitHub Actions**;
+2. 填:
+   - Organization or user:`ShirazuNagisa`
+   - Repository:`DSH-Mizar`
+   - Workflow filename:`publish.yml`
+   - Environment name:留空
+   - **Allowed actions**:勾上 **`npm publish`**(直接发布;只勾暂存的话每次发布还要人工批准);
+3. 保存。
+
+之后发布:
+
+```sh
+cd dsh
+npm version patch            # 或手改 package.json 的 version
+git push                     # 版本号先上 main
+git tag vX.Y.Z && git push origin vX.Y.Z
+```
+
+workflow(`.github/workflows/publish.yml`)会:**校验 tag 与 package.json 版本一致** →
+`npm ci` → typecheck → 全部测试 → build → `npm publish --provenance`。任何一步失败都不会发布。
+
+为什么不用手工 `npm publish`:这个账号的第二因子是**安全密钥(WebAuthn)**,npm CLI 不支持
+WebAuthn,`Enter OTP:` 永远过不去;trusted publishing 是 npm 对 CI 发布的官方方案,还顺带生成
+来源证明(provenance)。
+
+> 兜底:`npm publish --registry=https://registry.npmjs.org` 仍可用,但需要账号里有可用的
+> 验证器 App(TOTP)或一次性密码;若走 `auth-type=web` 会进入暂存发布,registry 上出现
+> `0.0.0-stage` 占位版本时用
+> `npm unpublish dsh-mizar@0.0.0-stage --registry=https://registry.npmjs.org` 清掉。
 
 ## 五、开发
 
@@ -155,4 +221,4 @@ DSH 启动日志里有 `[mizar] dsh-mizar <版本号> · state: … · devices:
 
 ---
 
-协议、架构决策、自建中继：[docs/](docs/)
+协议、架构决策、自建中继、研究记录：[docs/](docs/)

package/lib/auth/devices.d.ts

@@ -2,6 +2,20 @@
 export declare const TOKEN_PREFIX = "mz_";
 /** Longest accepted device name, in characters. */
 export declare const MAX_DEVICE_NAME = 64;
+/** Longest accepted Live Activity push token, in characters. */
+export declare const MAX_LIVE_ACTIVITY_TOKEN = 200;
+/**
+ * Whether a value is an APNs Live Activity push token.
+ *
+ * Lowercase hex, because that is what APNs issues and therefore what the app
+ * reports. The length bound is the wire contract's: wide enough for any token
+ * APNs has ever issued, narrow enough that a stored file cannot be made to hold
+ * an unbounded string.
+ *
+ * @param value - the candidate, normally straight from a client payload or from state.json.
+ * @returns whether it is usable.
+ */
+export declare function isLiveActivityToken(value: unknown): value is string;
 /** One paired device. */
 export interface DeviceRecord {
     /** Stable identity, generated at pairing time. */
@@ -59,6 +73,18 @@ export interface DevicePush {
     readonly environment: 'sandbox' | 'production' | null;
     /** The language the app is running in, so notifications match it. */
     readonly locale: string;
+    /**
+     * The APNs push token of the Live Activity currently on screen.
+     *
+     * Not the same token as {@link DevicePush.token}, and not interchangeable: a
+     * Live Activity is addressed by a per-activity token, so an end push sent to
+     * the app's device token would reach the app rather than the activity.
+     *
+     * Absent means no Live Activity is up. That is why registering without it has
+     * to *clear* the stored one rather than leave it alone: a token held past its
+     * activity is a credential for ending a countdown that no longer exists.
+     */
+    readonly liveActivityToken?: string;
     /** When the app last told this host where it is. */
     readonly updatedAt: number;
 }

package/lib/auth/devices.js

@@ -17,6 +17,24 @@ export const TOKEN_PREFIX = 'mz_';
 const TOKEN_BYTES = 32;
 /** Longest accepted device name, in characters. */
 export const MAX_DEVICE_NAME = 64;
+/** Longest accepted Live Activity push token, in characters. */
+export const MAX_LIVE_ACTIVITY_TOKEN = 200;
+/** APNs issues lowercase hex tokens and nothing else. */
+const LIVE_ACTIVITY_TOKEN_PATTERN = new RegExp(`^[0-9a-f]{1,${MAX_LIVE_ACTIVITY_TOKEN}}$`);
+/**
+ * Whether a value is an APNs Live Activity push token.
+ *
+ * Lowercase hex, because that is what APNs issues and therefore what the app
+ * reports. The length bound is the wire contract's: wide enough for any token
+ * APNs has ever issued, narrow enough that a stored file cannot be made to hold
+ * an unbounded string.
+ *
+ * @param value - the candidate, normally straight from a client payload or from state.json.
+ * @returns whether it is usable.
+ */
+export function isLiveActivityToken(value) {
+    return typeof value === 'string' && LIVE_ACTIVITY_TOKEN_PATTERN.test(value);
+}
 /**
  * Hash a token for storage or comparison.
  * @param token - the token.

package/lib/auth/store.d.ts

@@ -1,4 +1,4 @@
-import type { DevicePush, DeviceRecord } from './devices.js';
+import { type DevicePush, type DeviceRecord } from './devices.js';
 import type { PairingSlot } from './pairing.js';
 /** Schema version of the state file. */
 export declare const STATE_VERSION = 1;

package/lib/auth/store.js

@@ -19,6 +19,7 @@ import { randomBytes, randomUUID } from 'node:crypto';
 import { mkdir, open, readFile, rename, unlink, appendFile } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { isLiveActivityToken } from './devices.js';
 /** Schema version of the state file. */
 export const STATE_VERSION = 1;
 /** Bytes in the host secret. */
@@ -68,6 +69,11 @@ function createState(now = Date.now()) {
  * device re-registers on its next launch, and this file is the wrong place for a
  * recoverable field to become a lockout.
  *
+ * The Live Activity token inside it gets the same treatment one level down: an
+ * unusable one costs the activity, not the endpoint, because a phone that can
+ * still be notified is worth more than one whose corrupt extra field made the
+ * whole registration vanish.
+ *
  * @param value - the candidate.
  * @returns the endpoint, or `null` when it is unusable.
  */
@@ -95,12 +101,19 @@ function parsePush(value) {
             platform === 'ios'
                 ? 'production'
                 : null;
+    // Validated on the way in and on the way back out, because this is the copy
+    // the relay is told again after a restart -- a token that rotted in the file
+    // would be re-announced as if it were still a Live Activity.
+    const liveActivityToken = isLiveActivityToken(record['liveActivityToken'])
+        ? record['liveActivityToken']
+        : undefined;
     return {
         token: record['token'],
         platform,
         environment,
         locale: record['locale'],
         updatedAt: record['updatedAt'],
+        ...(liveActivityToken === undefined ? {} : { liveActivityToken }),
     };
 }
 /**

package/lib/bridge/index.js

@@ -1,3 +1,4 @@
+import { isLiveActivityToken } from '../auth/devices.js';
 import { deliverQuestionAnswers } from './answerers.js';
 import { toMethodError } from './errors.js';
 import { CLIENT_APPROVAL_OUTCOMES, InteractionBroker, } from './interactions.js';
@@ -71,7 +72,35 @@ function readAnswerBatch(payload) {
     });
 }
 /**
- * Read a `push.register`'s platform and environment.
+ * Read the optional Live Activity token a registration carries.
+ *
+ * Absence is meaningful rather than "no change": the app only sends this while
+ * a Live Activity is up, so a registration without it says none is up now and
+ * the stored token must be cleared. That is why the answer is `string | null`
+ * rather than `string | undefined` -- the binding has to act on the absence.
+ *
+ * A present value is held, not just forwarded, because it has to outlive this
+ * launch: the relay is told again after a reconnect, and the app may be
+ * suspended long before the turn that ends the activity.
+ *
+ * @param record - the registration payload.
+ * @returns the token, or `null` when the app has no Live Activity up.
+ * @throws MethodError when a value is present but is not a usable token.
+ */
+function readLiveActivityToken(record) {
+    const value = record['liveActivityToken'];
+    // Absent, not null and not empty: those are present values that failed the
+    // contract, and a client sending one has a bug worth naming rather than
+    // silently having its activity token cleared.
+    if (value === undefined)
+        return null;
+    if (!isLiveActivityToken(value)) {
+        throw new MethodError('MALFORMED_FRAME', 'push.register: payload."liveActivityToken" must be 1-200 lowercase hex characters');
+    }
+    return value;
+}
+/**
+ * Read a `push.register`'s platform, environment and Live Activity token.
  *
  * `platform` is optional and means iOS when absent, which is the one thing that
  * makes this change compatible: every app build that exists today sends
@@ -87,9 +116,13 @@ function readAnswerBatch(payload) {
  * is dropped rather than rejected: FCM has one service and the field is
  * meaningless there.
  *
+ * `liveActivityToken` is likewise iOS-only and optional. An Android client has
+ * no Live Activity to end, so a stray value is dropped rather than refused, for
+ * the same reason a stray environment is.
+ *
  * @param payload - the request payload.
- * @returns the platform, and the environment when there is one.
- * @throws MethodError when either is present but not one of the allowed values.
+ * @returns the platform, the environment and the activity token when there are any.
+ * @throws MethodError when a present field is not one of the allowed values.
  */
 function readRegistration(payload) {
     const record = optionalObject(payload, 'push.register');
@@ -103,12 +136,12 @@ function readRegistration(payload) {
         // nothing for an Android client to answer here -- and a client that sends
         // one anyway must still register, because refusing would make a version of
         // the app unable to pair for a reason that cannot be true.
-        return { platform, environment: null };
+        return { platform, environment: null, liveActivityToken: null };
     }
     if (value !== 'sandbox' && value !== 'production') {
         throw new MethodError('MALFORMED_FRAME', 'push.register: payload."environment" must be "sandbox" or "production" for platform "ios"');
     }
-    return { platform, environment: value };
+    return { platform, environment: value, liveActivityToken: readLiveActivityToken(record) };
 }
 /**
  * Build the method table for one plugin mount.
@@ -255,6 +288,11 @@ export function createMethodTable(ctx, facts, broker, push) {
          * notification permission -- so a phone that refused simply never calls it,
          * and nothing needs to model refusal.
          *
+         * The optional `liveActivityToken` is the one field that is *cleared* by
+         * absence. The app sends it while a Live Activity is on screen and omits it
+         * afterwards, so a registration without it is the signal that the countdown
+         * is gone and the stored token must go with it.
+         *
          * Answers `registered: false` rather than failing when the device is not on
          * the roster. That cannot happen through the listener (every method is behind
          * authentication), and a client that met it would have nothing useful to do
@@ -274,6 +312,7 @@ export function createMethodTable(ctx, facts, broker, push) {
                     platform: registration.platform,
                     environment: registration.environment,
                     locale: optionalString(payload, 'locale') ?? 'en',
+                    liveActivityToken: registration.liveActivityToken,
                 }),
             };
         },

package/lib/index.js

@@ -14,11 +14,11 @@ import { Config } from './config.js';
 import { registerAnswerers } from './bridge/answerers.js';
 import { createMethodTable } from './bridge/index.js';
 import { InteractionBroker } from './bridge/interactions.js';
-import { sessionStats } from './bridge/sessions.js';
+import { listSessions, sessionStats } from './bridge/sessions.js';
 import { registerPanelApi } from './panel/api.js';
 import { createPushBinding } from './push/binding.js';
 import { PushNotifier } from './push/notifier.js';
-import { isNotifiable } from './push/scope.js';
+import { anyNotifiableSessionRunning, isNotifiable, } from './push/scope.js';
 import { NoopTransport, RelayTransport } from './push/transport.js';
 import { MizarStore, resolveMizarHome } from './auth/store.js';
 import { selectBindAddresses, snapshotInterfaces, } from './net/interfaces.js';
@@ -53,7 +53,7 @@ const systemLocale = (() => {
  * code in place and every symptom unchanged. One line at boot turns that from a
  * guess into a fact.
  */
-const MIZAR_VERSION = '0.8.2';
+const MIZAR_VERSION = '0.8.3';
 /**
  * Services this plugin must observe before it activates.
  *
@@ -170,8 +170,33 @@ async function startListener(ctx, config, signal) {
     const pushTransport = relayBaseURL === null
         ? new NoopTransport()
         : new RelayTransport({ baseURL: relayBaseURL, token: tunnelToken, log: report });
+    // The question a finished turn has to answer before it may take the Live
+    // Activity down: is anything the phone would show still working? Read through
+    // the same list the app draws its rows from, and filtered by the same rule as
+    // the notification scope, so "idle" means idle on the phone rather than idle
+    // in some other sense.
+    //
+    // A gateway that cannot be read is not evidence that everything stopped: the
+    // failure direction is "still running", because a countdown that lingers is a
+    // wrong clock, while one that vanishes under a running session is a wrong
+    // screen. Reported once -- this runs per notification, and a down gateway
+    // would otherwise write a line every time one finished.
+    let warnedAboutSessionList = false;
+    const anySessionRunning = async () => {
+        try {
+            return anyNotifiableSessionRunning((await listSessions(ctx)).items);
+        }
+        catch (error) {
+            if (!warnedAboutSessionList) {
+                warnedAboutSessionList = true;
+                report(`push: could not read the session list — leaving the live activity up (${describe(error)})`);
+            }
+            return true;
+        }
+    };
     const notifier = new PushNotifier({
         transport: pushTransport,
+        anySessionRunning,
         describeSession: async (sessionId) => {
             try {
                 const frame = await sessionStats(ctx, sessionId);

package/lib/protocol/frames.d.ts

@@ -19,7 +19,16 @@
  *
  * @module dsh-mizar/protocol/frames
  */
-/** The protocol version this build speaks. */
+/**
+ * The protocol version this build speaks.
+ *
+ * **Adding an optional field to an existing payload is not a version bump**, and
+ * the Live Activity fields (the bridge's `push.register.liveActivityToken`, and
+ * the relay's `endLiveActivity`) are added that way: a peer that does not know a
+ * key leaves it alone, which is what lets a phone update before its host or the
+ * other way round. Changing what an existing field means, renaming one, or
+ * requiring a new one *is* a bump.
+ */
 export declare const PROTOCOL_VERSION = 1;
 /** Path of the authenticated WebSocket endpoint. */
 export declare const WS_PATH = "/mizar/v1/ws";

package/lib/protocol/frames.js

@@ -19,7 +19,16 @@
  *
  * @module dsh-mizar/protocol/frames
  */
-/** The protocol version this build speaks. */
+/**
+ * The protocol version this build speaks.
+ *
+ * **Adding an optional field to an existing payload is not a version bump**, and
+ * the Live Activity fields (the bridge's `push.register.liveActivityToken`, and
+ * the relay's `endLiveActivity`) are added that way: a peer that does not know a
+ * key leaves it alone, which is what lets a phone update before its host or the
+ * other way round. Changing what an existing field means, renaming one, or
+ * requiring a new one *is* a bump.
+ */
 export const PROTOCOL_VERSION = 1;
 /** Path of the authenticated WebSocket endpoint. */
 export const WS_PATH = '/mizar/v1/ws';

package/lib/push/binding.d.ts

@@ -30,6 +30,14 @@ export interface PushRegistrationInput {
      */
     readonly environment: 'sandbox' | 'production' | null;
     readonly locale: string;
+    /**
+     * The APNs push token of the Live Activity on screen, or `null` when none is.
+     *
+     * `null` clears the stored token rather than leaving it alone: the app omits
+     * the field once its activity is gone, and a token kept past that point is a
+     * credential for ending a countdown that no longer exists.
+     */
+    readonly liveActivityToken: string | null;
 }
 /** What the bridge calls. */
 export interface PushBinding {

package/lib/push/binding.js

@@ -16,6 +16,7 @@ export function createPushBinding(options) {
             platform: push.platform,
             environment: push.environment,
             locale: push.locale,
+            ...(push.liveActivityToken === undefined ? {} : { liveActivityToken: push.liveActivityToken }),
         };
     };
     return {
@@ -26,6 +27,9 @@ export function createPushBinding(options) {
                 environment: input.environment,
                 locale: input.locale,
                 updatedAt: Date.now(),
+                // Omitted when there is none, which is how `setDevicePush` is told to
+                // clear it: this object is the whole record, not a patch.
+                ...(input.liveActivityToken === null ? {} : { liveActivityToken: input.liveActivityToken }),
             });
             if (!known) {
                 // A device that is not on the roster cannot have got here: every method
@@ -40,12 +44,16 @@ export function createPushBinding(options) {
                 platform: input.platform,
                 environment: input.environment,
                 locale: input.locale,
+                ...(input.liveActivityToken === null ? {} : { liveActivityToken: input.liveActivityToken }),
             });
+            // Whether a Live Activity token is held, never the token itself: it is a
+            // notification credential, and this log is what support requests quote.
+            const activity = input.liveActivityToken === null ? 'live-activity token: none' : 'live-activity token: held';
             // Only the first eight characters of the token, which is enough to tell
             // two registrations apart in a log and not enough to be one.
             options.log(accepted
-                ? `push: ${deviceId} registered (${input.platform}, ${input.environment ?? 'no environment'}, ${input.locale}) — ${input.token.slice(0, 8)}…`
-                : `push: the relay did not take ${deviceId}'s token (${input.platform}, ${input.environment ?? 'no environment'}) — this phone will not be woken`);
+                ? `push: ${deviceId} registered (${input.platform}, ${input.environment ?? 'no environment'}, ${input.locale}) — ${input.token.slice(0, 8)}…, ${activity}`
+                : `push: the relay did not take ${deviceId}'s token (${input.platform}, ${input.environment ?? 'no environment'}) — this phone will not be woken, ${activity}`);
             // The roster keeps the token either way: the relay may be an older build
             // today and accept it after an upgrade, and `republish` hands it over
             // again on the next reconnect. What must not happen is telling the phone

package/lib/push/notifier.d.ts

@@ -62,6 +62,19 @@ export interface PushNotifierOptions {
     readonly log: (message: string) => void;
     /** How long a session must be quiet, in milliseconds. */
     readonly settleMs?: number;
+    /**
+     * Whether any session the phone would show is still working.
+     *
+     * Asked only when a `turn-complete` notification is about to go out, to decide
+     * whether the relay should end the Live Activity with it. A Live Activity is
+     * the countdown for the work on screen, so while another visible session is
+     * still running ending it would take away the wrong screen.
+     *
+     * Absent when the host cannot answer, and then nothing is ever ended: a
+     * countdown that lingers is wrong, but one that disappears under a running
+     * session is wrong and loses the screen the operator was using.
+     */
+    readonly anySessionRunning?: () => Promise<boolean>;
 }
 /**
  * Which language to write a notification in.

package/lib/push/notifier.js

@@ -78,6 +78,8 @@ export class PushNotifier {
     #foreground = new Set();
     /** Sessions that have stopped and are waiting out the quiet period. */
     #settling = new Map();
+    /** Whether the one "could not tell whether anything is running" line was logged. */
+    #warnedLiveActivity = false;
     constructor(options) {
         this.#options = options;
         this.#settleMs = Math.max(0, options.settleMs ?? DEFAULT_SETTLE_MS);
@@ -223,6 +225,11 @@ export class PushNotifier {
     async #announceSettled(sessionId, reason) {
         const session = await this.#describe(sessionId);
         const wording = turnWording(reason, session, languageOf(this.#options.locale()));
+        // Only a turn that finished can be the end of the work, and only when
+        // nothing the phone would show is still going. The app ends its own Live
+        // Activity while it is running; this is that same end for the case the app
+        // cannot cover -- one that arrives while the phone is suspended.
+        const endLiveActivity = await this.#nothingIsRunning();
         await this.#send({
             kind: 'turn-complete',
             title: wording.title,
@@ -233,8 +240,35 @@ export class PushNotifier {
             // the first rather than stacking under it.
             collapseId: `turn-${sessionId}`,
             timeSensitive: false,
+            ...(endLiveActivity ? { endLiveActivity: true } : {}),
         });
     }
+    /**
+     * Whether it is safe to ask the relay to end the Live Activity.
+     *
+     * Defaults to `false` everywhere it cannot tell: no callback, or a callback
+     * that failed. Ending the countdown on a guess would remove the screen a
+     * still-running session owns, which is the one failure the feature must not
+     * have -- leaving it up is only a stale clock.
+     */
+    async #nothingIsRunning() {
+        const check = this.#options.anySessionRunning;
+        if (check === undefined)
+            return false;
+        try {
+            return (await check()) === false;
+        }
+        catch (error) {
+            // Once, not once per announcement: a gateway that is down would otherwise
+            // write a line for every session that finishes for as long as it is down.
+            if (!this.#warnedLiveActivity) {
+                this.#warnedLiveActivity = true;
+                const detail = error instanceof Error ? error.message : String(error);
+                this.#options.log(`push: could not tell whether any session is running — leaving the live activity up (${detail})`);
+            }
+            return false;
+        }
+    }
     /** Name a session, tolerating a host that will not say. */
     async #describe(sessionId) {
         // Through `languageOf`, not a `startsWith('zh')` of its own: a Traditional

package/lib/push/scope.d.ts

@@ -43,3 +43,26 @@ export interface ScopedSessionHeader {
  * @returns whether the phone would show a row for it.
  */
 export declare function isNotifiable(header: ScopedSessionHeader | undefined): boolean;
+/** As much of a session-list row as the idle check reads. */
+export interface RunningSessionRow {
+    /** Whether a turn is currently executing. */
+    readonly running: boolean;
+    /** `'subagent'` for a delegated child. */
+    readonly origin: string | null;
+    /** Set on a fork, and on a delegated child's own header. */
+    readonly parentSessionId: string | null;
+}
+/**
+ * Whether any session the phone draws a row for is still working.
+ *
+ * The one question that decides whether a finished turn may take the Live
+ * Activity down with it: the island belongs to the work on screen, so a hidden
+ * subagent or fork still running is not a reason to keep it up, and a visible
+ * session still running is. Written over rows rather than headers because that
+ * is the shape `listSessions` returns, and mapped through {@link isNotifiable}
+ * so the two questions cannot disagree about which sessions are visible.
+ *
+ * @param rows - the session list, as `listSessions` returned it.
+ * @returns whether the Mac is still working on something the phone shows.
+ */
+export declare function anyNotifiableSessionRunning(rows: readonly RunningSessionRow[]): boolean;

package/lib/push/scope.js

@@ -42,3 +42,25 @@ export function isNotifiable(header) {
         return false;
     return header.parentSession === undefined;
 }
+/**
+ * Whether any session the phone draws a row for is still working.
+ *
+ * The one question that decides whether a finished turn may take the Live
+ * Activity down with it: the island belongs to the work on screen, so a hidden
+ * subagent or fork still running is not a reason to keep it up, and a visible
+ * session still running is. Written over rows rather than headers because that
+ * is the shape `listSessions` returns, and mapped through {@link isNotifiable}
+ * so the two questions cannot disagree about which sessions are visible.
+ *
+ * @param rows - the session list, as `listSessions` returned it.
+ * @returns whether the Mac is still working on something the phone shows.
+ */
+export function anyNotifiableSessionRunning(rows) {
+    return rows.some((row) => row.running &&
+        isNotifiable({
+            // `null` is "this field is not there", which is what the header type
+            // uses absence for.
+            ...(row.origin === null ? {} : { origin: row.origin }),
+            ...(row.parentSessionId === null ? {} : { parentSession: row.parentSessionId }),
+        }));
+}

package/lib/push/transport.d.ts

@@ -47,6 +47,16 @@ export interface PushRegistration {
      * row that says which language it asked for is one less thing to guess.
      */
     readonly locale: string;
+    /**
+     * The APNs token of the Live Activity currently on screen, when there is one.
+     *
+     * Omitted when no activity is up. The relay keeps it so it can end the
+     * activity from the Mac side, which is the case the app cannot cover: a turn
+     * that finishes while the app is suspended has nobody on the phone to end the
+     * countdown. An older relay ignores the field, exactly as it ignores any other
+     * JSON key it does not know.
+     */
+    readonly liveActivityToken?: string;
 }
 /** One notification. */
 export interface PushMessage {
@@ -78,6 +88,19 @@ export interface PushMessage {
      * has to be there when the app goes away again.
      */
     readonly exceptDeviceIds: readonly string[];
+    /**
+     * Whether the relay should end the Live Activity alongside this notification.
+     *
+     * Only ever set on a `turn-complete` message, and only when the session that
+     * finished was the last one the phone would show still running: an end push
+     * tears the countdown down, so sending it while other work is still going
+     * would take away the screen the operator is waiting on.
+     *
+     * Omitted when false, rather than sent as `false`: an older relay then reads
+     * the body it always did. Only the relay can act on it, so this is a request,
+     * not a promise -- the phones that are asleep are exactly why it exists.
+     */
+    readonly endLiveActivity?: boolean;
 }
 /** Where notifications go. */
 export interface PushTransport {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-mizar",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Remote monitoring and guidance for DSH agents — host plugin backing the DSH-Mizar iOS app.",
   "license": "MIT",
   "type": "module",