@khorsheed/dsh-ankh-guard 0.2.0 → 0.3.1

package/lib/types/browser-handoff.js

@@ -16,6 +16,14 @@
  * means the process it knew is gone — answer ready/reload. A cutover receipt
  * always wins over the generation check: during a cutover the old tab's known
  * id is already stale, and the receipt protocol owns the pacing.
+ *
+ * The generation answer waits for the successor's composition to settle. The
+ * shared Web-server seat answers as soon as it listens — well before sibling
+ * rows mount — and a page that loads then calls into a half-mounted /api
+ * surface (the Web app gates its own browser handoff on the same Loader
+ * settlement for that reason). Until then the poll is answered `waiting`
+ * WITHOUT the boot id: teaching the tab the successor's id would consume its
+ * one-shot generation check and strand it on an unusable page.
  */
 import { createHash, randomBytes } from 'node:crypto';
 import { chmodSync, linkSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
@@ -313,6 +321,13 @@ export function createBrowserHandoffHandler(dependencies) {
             // would race the registration/ack dance.
             if (bootId !== undefined && message.knownBootId !== undefined && message.knownBootId !== bootId
                 && activeCutover(dependencies.stateDir) === null) {
+                if (dependencies.applicationReady?.() === false) {
+                    // The successor's composition is still mounting. Answer WITHOUT the
+                    // boot id (not through `respond`): the tab must keep its stale id so
+                    // this one-shot generation check survives until readiness lands.
+                    json(res, 200, { state: 'waiting' });
+                    return;
+                }
                 respond(200, { state: 'ready', action: 'reload', authentication: 'existing-cookie' });
                 return;
             }
@@ -483,7 +498,31 @@ export function registerBrowserHandoff(ctx, stateDir) {
         const handler = createBrowserHandoffHandler({
             stateDir,
             connectionProvider: () => webCtx.get('connection'),
+            applicationReady: applicationReadyProbe(webCtx),
         });
         webCtx.effect(() => webServer.register({ kind: 'exact', path: BROWSER_HANDOFF_ROUTE, handler }), 'ankh-guard: browser handoff route');
     });
 }
+/**
+ * Build the generation channel's readiness probe from the Loader tree.
+ *
+ * The Web-server seat is shared: it answers as soon as it listens, while
+ * sibling rows — including the /api route owner a reloaded page immediately
+ * calls into — are still mounting. The Web app gates its own URL line and
+ * browser handoff on this exact settlement, so the guard's automatic reload
+ * must wait for it too. A composition without a Loader is already complete.
+ *
+ * Only settlement counts as ready: a failed tree leaves the tab on its old
+ * page (the watchdog's crash recovery owns that outcome), and the next healthy
+ * process answers the still-stale poll.
+ * @param ctx - context owning the Loader service.
+ * @returns probe consulted by every boot-generation poll.
+ */
+function applicationReadyProbe(ctx) {
+    const settled = ctx.get('loader')?.await();
+    if (settled === undefined)
+        return () => true;
+    let ready = false;
+    void settled.then(() => { ready = true; }, () => { });
+    return () => ready;
+}

package/lib/types/client/index.d.ts

@@ -2,7 +2,7 @@
  * Browser half of the original-tab launch-cutover handoff, plus the
  * boot-generation reload loop: polls carry the last-seen boot id, a stale id
  * with no cutover in flight reloads the tab once, and a sustained disconnection
- * (not a transient blip) raises a neutral overlay.
+ * (not a transient blip) raises a non-blocking connection notice.
  */
 import type { Context as ClientContext } from '@deepseek-ai/cordis';
 /** No Cordis services are needed; this is a same-origin browser lifecycle observer. */

package/lib/types/client/index.js

@@ -6,8 +6,10 @@ const FALLBACK_HASH_KEY = 'ankh-guard-handoff';
 const ACTIVE_RETRY_MS = 250;
 const ERROR_RETRY_MIN_MS = 1_000;
 const ERROR_RETRY_MAX_MS = 30_000;
-/** Sustained-failure threshold for the disconnected overlay; transient blips never show it. */
-const DISCONNECTED_OVERLAY_MS = 5_000;
+/** Sustained-failure threshold for the connection notice; transient blips never show it. */
+const DISCONNECTED_NOTICE_MS = 5_000;
+// Server idle polls hold for 25s; bound a stalled browser request beyond that.
+const REQUEST_TIMEOUT_MS = 35_000;
 /** No Cordis services are needed; this is a same-origin browser lifecycle observer. */
 export const inject = [];
 function encodeBase64Url(bytes) {
@@ -88,38 +90,55 @@ function consumeFallbackFragment() {
     writePending(pending);
     return pending;
 }
-function waitingOverlay(kind = 'restarting') {
+function waitingOverlay(kind = 'restarting', retry) {
     const existing = document.getElementById('ankh-guard-browser-handoff');
-    if (existing !== null)
+    // A confirmed restart cannot be downgraded by a subsequent transport failure.
+    if (existing?.dataset.kind === 'restarting' && kind === 'disconnected')
         return existing;
+    const element = existing ?? document.createElement('div');
     const zh = navigator.language.toLowerCase().startsWith('zh');
-    const element = document.createElement('div');
     element.id = 'ankh-guard-browser-handoff';
+    element.dataset.kind = kind;
     element.setAttribute('role', 'status');
     element.setAttribute('aria-live', 'polite');
-    // 'disconnected' covers failures without a known restart in flight (a bare
-    // exit may never come back) — neutral copy, no auto-recovery promise.
     element.textContent = kind === 'disconnected'
-        ? (zh ? '连接已断开,等待服务恢复。' : 'Connection lost; waiting for the service to recover.')
+        ? (zh ? '连接暂时中断，正在重试…' : 'Connection interrupted; retrying…')
         : (zh ? 'dsh 正在重启；此标签页会自动恢复。' : 'dsh is restarting; this tab will recover automatically.');
-    element.style.cssText = [
+    element.style.cssText = kind === 'restarting' ? [
         'position:fixed', 'inset:0', 'z-index:2147483647', 'display:grid', 'place-items:center',
         'padding:24px', 'background:rgba(15,18,24,.92)', 'color:#fff',
         'font:500 16px/1.5 system-ui,sans-serif', 'text-align:center',
+    ].join(';') : [
+        'position:fixed', 'top:calc(env(safe-area-inset-top,0px) + 12px)', 'left:12px', 'right:12px',
+        'max-width:520px', 'margin:0 auto', 'box-sizing:border-box', 'z-index:2147483647',
+        'display:flex', 'align-items:center', 'justify-content:space-between', 'gap:12px',
+        'padding:12px 16px', 'border:1px solid var(--dsw-alias-border-l2,#8885)', 'border-radius:16px',
+        'background:var(--dsw-alias-bg-base,#fff)', 'color:var(--dsw-alias-label-primary,#181a20)',
+        'box-shadow:0 4px 24px #0002', 'font:400 15px/1.5 system-ui,sans-serif',
     ].join(';');
-    document.documentElement.append(element);
+    if (kind === 'disconnected' && retry) {
+        const button = document.createElement('button');
+        button.textContent = zh ? '重试' : 'Retry';
+        button.style.cssText = 'flex:none;border:0;background:transparent;color:var(--dsw-alias-state-business-primary,#4d6bfe);font:inherit;min-height:36px;cursor:pointer';
+        button.onclick = retry;
+        element.append(button);
+    }
+    // Official theme tokens live on body, so the notice must inherit from it.
+    if (!existing)
+        (document.body ?? document.documentElement).append(element);
     return element;
 }
-async function post(body) {
+async function post(body, signal) {
     return fetch(ROUTE, {
         method: 'POST',
+        signal,
         credentials: 'same-origin',
         cache: 'no-store',
         headers: { 'content-type': 'application/json' },
         body: JSON.stringify(body),
     });
 }
-async function acknowledge(pending) {
+async function acknowledge(pending, signal) {
     const response = await post({
         version: 1,
         operation: 'ack',
@@ -127,7 +146,7 @@ async function acknowledge(pending) {
         channel: pending.channel,
         authentication: pending.authentication,
         ...(pending.capability !== undefined ? { capability: pending.capability } : {}),
-    });
+    }, signal);
     return response.status === 204;
 }
 /** Install the polling/reload loop for this tab's lifetime. */
@@ -138,24 +157,68 @@ export function apply(_ctx) {
     let cap;
     let errorRetryMs = ERROR_RETRY_MIN_MS;
     let firstFailureAt;
-    // Fullscreen notice only for SUSTAINED disconnection (restart window, bare
-    // exit): transient network blips and the backoff cadence never trip it.
+    let request;
+    let lastWakeAt = -Infinity;
+    const foreground = () => document.visibilityState !== 'hidden' && navigator.onLine !== false;
+    const clearConnectionNotice = () => {
+        const notice = document.getElementById('ankh-guard-browser-handoff');
+        if (notice?.dataset.kind === 'disconnected')
+            notice.remove();
+    };
+    const pause = () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+        const previous = request;
+        request = undefined;
+        previous?.abort();
+        firstFailureAt = undefined;
+        errorRetryMs = ERROR_RETRY_MIN_MS;
+        clearConnectionNotice();
+    };
+    const wake = () => {
+        if (disposed || !foreground() || Date.now() - lastWakeAt < 500)
+            return;
+        lastWakeAt = Date.now();
+        pause();
+        schedule();
+    };
+    const visibility = () => {
+        if (!foreground()) {
+            lastWakeAt = -Infinity;
+            pause();
+        }
+        else
+            wake();
+    };
+    const page = (event) => { if (event.persisted)
+        wake(); };
+    // Only visible failures count. Ordinary outages never block the page.
     const noteDisconnected = () => {
         firstFailureAt ??= Date.now();
-        if (Date.now() - firstFailureAt >= DISCONNECTED_OVERLAY_MS)
-            waitingOverlay('disconnected');
+        if (Date.now() - firstFailureAt >= DISCONNECTED_NOTICE_MS)
+            waitingOverlay('disconnected', wake);
     };
     const schedule = (delayMs = 0) => {
-        if (!disposed)
-            timer = setTimeout(() => { void tick(); }, delayMs);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (!disposed && foreground())
+            timer = setTimeout(() => { timer = undefined; void tick(); }, delayMs);
     };
     const tick = async () => {
-        if (disposed)
+        if (disposed || !foreground() || request)
             return;
+        const current = new AbortController();
+        request = current;
+        const stale = () => disposed || request !== current || !foreground();
+        const deadline = setTimeout(() => current.abort(), REQUEST_TIMEOUT_MS);
         try {
             if (pending !== null) {
                 waitingOverlay();
-                if (await acknowledge(pending)) {
+                const acknowledged = await acknowledge(pending, current.signal);
+                if (stale())
+                    return;
+                if (acknowledged) {
                     const returnPath = pending.returnPath;
                     const originalTab = pending.channel === 'original-tab';
                     sessionStorage.removeItem(PENDING_KEY);
@@ -178,7 +241,9 @@ export function apply(_ctx) {
             const response = await post({
                 version: 1, operation: 'poll', capability: tabCapability,
                 ...(knownBootId === null ? {} : { knownBootId }),
-            });
+            }, current.signal);
+            if (stale())
+                return;
             if (!response.ok) {
                 noteDisconnected();
                 schedule(errorRetryMs);
@@ -188,6 +253,8 @@ export function apply(_ctx) {
             errorRetryMs = ERROR_RETRY_MIN_MS;
             firstFailureAt = undefined;
             const result = await response.json();
+            if (stale())
+                return;
             // Learn the serving boot id before acting on it — storing the successor's
             // id ahead of the reload is what makes the generation check one-shot.
             if (typeof result.bootId === 'string')
@@ -247,18 +314,35 @@ export function apply(_ctx) {
             }
         }
         catch {
+            if (stale())
+                return;
             // The expected restart interval rejects fetches; keep the old page and retry.
             noteDisconnected();
             schedule(errorRetryMs);
             errorRetryMs = Math.min(errorRetryMs * 2, ERROR_RETRY_MAX_MS);
             return;
         }
+        finally {
+            clearTimeout(deadline);
+            if (request === current)
+                request = undefined;
+        }
         schedule(ACTIVE_RETRY_MS);
     };
+    document.addEventListener('visibilitychange', visibility);
+    window.addEventListener('online', wake);
+    window.addEventListener('offline', visibility);
+    window.addEventListener('pageshow', page);
+    window.addEventListener('dsh-mobile-foreground', wake);
     void tick();
     return () => {
         disposed = true;
-        if (timer !== undefined)
-            clearTimeout(timer);
+        pause();
+        document.removeEventListener('visibilitychange', visibility);
+        window.removeEventListener('online', wake);
+        window.removeEventListener('offline', visibility);
+        window.removeEventListener('pageshow', page);
+        window.removeEventListener('dsh-mobile-foreground', wake);
+        document.getElementById('ankh-guard-browser-handoff')?.remove();
     };
 }

package/lib/types/index.d.ts

@@ -18,6 +18,15 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import type { ContextFormed } from '@deepseek-ai/dsh-llm';
+declare module '@deepseek-ai/dsh-llm' {
+    interface MessageSourceMap {
+        'ankh-guard': {
+            kind: 'ankh-guard';
+            plugin: string;
+        } & ContextFormed;
+    }
+}
 import { type RestartRequest, type RestartRequestResult } from './restart-request.ts';
 import { type GuardState, type VerifyResult } from './state.ts';
 /**
@@ -52,6 +61,23 @@ export interface PresetDerivationSurface {
     };
     resolveSessionPreset?: (session: PersistedPresetSource) => string | undefined;
 }
+/**
+ * Resolve the preset-registry module by name. The 0.1.7-rc.1 host renamed
+ * `@deepseek-ai/dsh-agent-presets` to `@deepseek-ai/dsh-agent-preset-registry`
+ * (the resolve/mount/livePresetMounts/agentPresetProjectionDefinition API
+ * carried over); 0.1.5/0.1.6 hosts install only the old name, and a host
+ * without preset composition installs neither — `null`, and the derivation
+ * then receives `{}`, the established no-preset degrade (the resume falls
+ * back to the deployment's default preset). A STATIC import of either name is
+ * a module-resolution failure at load on hosts installing only the other —
+ * pack-dist strips `dependencies`, so the specifier resolves against the
+ * host's install tree. Both specifiers stay static string literals so tsdown
+ * externalizes them and tsc type-checks them.
+ * @returns the module namespace, or null when neither name resolves.
+ */
+export declare function loadPresetRegistry(): Promise<unknown>;
+/** Test seam: drop the cached probe so a mocked resolution path re-runs. */
+export declare function resetPresetRegistryProbeForTest(): void;
 /**
  * Which preset a session actually runs, newest selection winning. The rc host
  * exports `resolveSessionPreset` for exactly this fold; the 0.1.2 host
@@ -68,11 +94,11 @@ export declare function deriveSessionPreset(host: PresetDerivationSurface, sessi
 /** Plugin configuration. */
 export interface SelfRestartGuardConfig {
     /** Credential freshness window in minutes (default 10). */
-    maxAgeMinutes?: number;
+    maxAgeMinutes?: number | undefined;
     /** State directory; defaults to $DSH_HOME/state, else `<cwd>/.dsh-guard-state`. */
-    stateDir?: string;
+    stateDir?: string | undefined;
     /** Repository the credential binds to; defaults to the process cwd. */
-    repoDir?: string;
+    repoDir?: string | undefined;
     /**
      * How to surface a scheduled restart's record to the agent (default
      * `followup` — fully autonomous: the plugin queues the report as the next
@@ -80,7 +106,7 @@ export interface SelfRestartGuardConfig {
      * system uses for reminders, so the agent reports without any user message).
      * `step` rides the first step of whatever turn comes next; `off` disables.
      */
-    reportRestartContext?: 'followup' | 'step' | 'off';
+    reportRestartContext?: 'followup' | 'step' | 'off' | undefined;
     /**
      * Resume the sessions a restart interrupted (default true). At SIGTERM the
      * plugin snapshots which root sessions had a live turn (plus the restart's
@@ -90,21 +116,21 @@ export interface SelfRestartGuardConfig {
      * The pass only runs on a restart boot (restart marker or pending restart
      * record present); a cold start drops the snapshot without acting.
      */
-    resumeInterrupted?: boolean;
+    resumeInterrupted?: boolean | undefined;
     /**
      * Delay before the interrupted-session resume pass runs after plugin load
      * (default 5000 ms), so the pass starts turns only after the app's services
      * are up.
      */
-    resumeDelayMs?: number;
+    resumeDelayMs?: number | undefined;
     /**
      * Maximum age of the interrupted-session snapshot the resume pass honors
      * (default 600000 ms, ten minutes). A snapshot older than that comes from a
      * manual stop/start, not a restart, and is dropped without acting.
      */
-    resumeMaxSnapshotAgeMs?: number;
+    resumeMaxSnapshotAgeMs?: number | undefined;
 }
-export declare const Config: z<SelfRestartGuardConfig>;
+export declare const Config: z;
 /** One canary check line. */
 export interface CanaryCheck {
     name: string;

package/lib/types/index.js

@@ -1,13 +1,6 @@
 import z from '@deepseek-ai/schemastery';
 import { connect } from 'node:net';
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
-// Namespace handle for runtime feature detection: the 0.1.2 host replaced
-// the `resolveSessionPreset` free function (and the `PresetBearingSession`
-// type) with the `agentPresetProjectionDefinition` unit, and a STATIC named
-// import of a removed export is a SyntaxError at module load — exactly the
-// failure this dual-host probing exists to survive. The derivation below
-// reads both surfaces through one structural cast.
-import * as agentPresetsHost from '@deepseek-ai/dsh-agent-presets';
 import { existsSync, readFileSync, unlinkSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -20,6 +13,31 @@ import { registerBrowserHandoff } from "./browser-handoff.js";
 import { requestRestart } from "./restart-request.js";
 import { acknowledgeRestartRecord, buildLaunchCommand, continueAndReportText, continueInterruptedText, interruptedSnapshotFile, isParkedOnUserInput, writeInstanceLaunch, writeSkillRegistration, pendingRestartRecord, readInterruptedSnapshot, restartContextText, writeInterruptedSnapshot, } from "./restart-context.js";
 import { clearCredential, loadState, recordCredential, setCheckpoint, verifyCredential, } from "./state.js";
+let presetRegistryProbe;
+/**
+ * Resolve the preset-registry module by name. The 0.1.7-rc.1 host renamed
+ * `@deepseek-ai/dsh-agent-presets` to `@deepseek-ai/dsh-agent-preset-registry`
+ * (the resolve/mount/livePresetMounts/agentPresetProjectionDefinition API
+ * carried over); 0.1.5/0.1.6 hosts install only the old name, and a host
+ * without preset composition installs neither — `null`, and the derivation
+ * then receives `{}`, the established no-preset degrade (the resume falls
+ * back to the deployment's default preset). A STATIC import of either name is
+ * a module-resolution failure at load on hosts installing only the other —
+ * pack-dist strips `dependencies`, so the specifier resolves against the
+ * host's install tree. Both specifiers stay static string literals so tsdown
+ * externalizes them and tsc type-checks them.
+ * @returns the module namespace, or null when neither name resolves.
+ */
+export function loadPresetRegistry() {
+    presetRegistryProbe ??= import('@deepseek-ai/dsh-agent-preset-registry')
+        .catch(() => import('@deepseek-ai/dsh-agent-presets'))
+        .catch(() => null);
+    return presetRegistryProbe;
+}
+/** Test seam: drop the cached probe so a mocked resolution path re-runs. */
+export function resetPresetRegistryProbeForTest() {
+    presetRegistryProbe = undefined;
+}
 /**
  * Which preset a session actually runs, newest selection winning. The rc host
  * exports `resolveSessionPreset` for exactly this fold; the 0.1.2 host
@@ -42,6 +60,24 @@ export function deriveSessionPreset(host, session) {
     }
     return host.resolveSessionPreset?.(session);
 }
+/** Probe the session-persistence service's cold-read face. */
+function probeColdReader(ctx) {
+    const service = ctx.get('sessionPersistence');
+    if (service === undefined || service === null)
+        return undefined;
+    return typeof service.open === 'function' ? service : undefined;
+}
+/** Read one persisted session's header and full log through a read handle. */
+async function readColdLog(persistence, id) {
+    const handle = await persistence.open(id, 'read');
+    try {
+        const cold = await handle.read(0);
+        return { meta: handle.header, events: cold.events };
+    }
+    finally {
+        await handle.close();
+    }
+}
 export const Config = z.object({
     maxAgeMinutes: z.natural().min(1).default(10),
     stateDir: z.string().default(''),
@@ -160,7 +196,7 @@ export function apply(ctx, config) {
     if (followupReport || resumeInterrupted) {
         const pluginMessage = (text) => createUserMessage({
             content: [{ type: 'text', text }],
-            source: { kind: 'plugin', plugin: name, form: 'snapshot', sections: [{ name: 'restart', text }] },
+            source: { kind: 'ankh-guard', plugin: name, form: 'snapshot', sections: [{ name: 'restart', text }] },
         });
         // Interrupted sessions awaiting their `agent/created` to receive the
         // "continue" followup: session id → exitAt of the interrupting exit.
@@ -180,10 +216,10 @@ export function apply(ctx, config) {
             if (probe === undefined) {
                 probe = (async () => {
                     try {
-                        const persistence = ctx.get('sessionPersistence');
+                        const persistence = probeColdReader(ctx);
                         if (persistence === undefined)
                             return false;
-                        const { events } = await persistence.inspect(id);
+                        const { events } = await readColdLog(persistence, id);
                         return isParkedOnUserInput(events);
                     }
                     catch {
@@ -220,7 +256,19 @@ export function apply(ctx, config) {
                 return;
             const id = agent.id;
             const exitAt = pendingContinue.get(id);
-            const record = followupReport ? pendingRestartRecord(stateDir) : null;
+            let record = followupReport ? pendingRestartRecord(stateDir) : null;
+            // A bare PLANNED outcome with no initiating session (the restart was
+            // driven from outside the host — the operator's terminal already has
+            // the announcement) has no in-host owner: settle the record instead of
+            // waking whichever root session happens to mount first. Records
+            // carrying diagnostics someone must hear about — an unplanned
+            // recovery, a composition rollback, a failed restart — keep the
+            // first-created claim.
+            if (record !== null && record.initiator === undefined
+                && record.unexpected !== true && record.compositionRecovered !== true && record.error === undefined) {
+                acknowledgeRestartRecord(stateDir, record, Date.now());
+                record = null;
+            }
             const owesReport = record !== null && (record.initiator === undefined || id === record.initiator);
             if (exitAt !== undefined) {
                 void (async () => {
@@ -326,10 +374,14 @@ export function apply(ctx, config) {
                 agentOptions.model = selection.model;
             let setup;
             const presets = ctx.get('agentPresets');
-            const persistence = ctx.get('sessionPersistence');
+            const persistence = probeColdReader(ctx);
             if (presets !== undefined && persistence !== undefined) {
-                const inspected = await persistence.inspect(id);
-                const presetId = deriveSessionPreset(agentPresetsHost, { header: inspected.meta, events: inspected.events });
+                const inspected = await readColdLog(persistence, id);
+                const host = await loadPresetRegistry();
+                const presetId = deriveSessionPreset((host ?? {}), {
+                    header: inspected.meta,
+                    events: inspected.events,
+                });
                 setup = async (agentCtx) => { await presets.mount(agentCtx, (await presets.resolve(presetId)).id); };
             }
             return { resumeSessionId: id, agentOptions, ...(setup === undefined ? {} : { setup }) };
@@ -419,6 +471,9 @@ export function apply(ctx, config) {
             }, 250);
             ctx.effect(() => () => { clearInterval(releaseTimer); });
         }
+        // agent/created went @mode serial in 0.1.6: the creation transaction
+        // awaits whatever a listener returns, so delivery stays fire-and-forget
+        // here — return nothing, and never await agent.whenIdle in this listener.
         ctx.on('agent/created', ({ agent }) => {
             if (!ctx.agents.roots().includes(agent))
                 return;
@@ -449,7 +504,7 @@ export function apply(ctx, config) {
                     createUserMessage({
                         content: [{ type: 'text', text }],
                         source: {
-                            kind: 'plugin', plugin: name, form: 'snapshot',
+                            kind: 'ankh-guard', plugin: name, form: 'snapshot',
                             sections: [{ name: 'restart', text }],
                         },
                     }),

package/lib/types/preflight-runner.d.ts

@@ -58,7 +58,7 @@ export interface PreflightComposition {
  * bundle layers in `dsh.profile.bundles` order, the profile user layer, the
  * home-level user layer, `--patch` overlays, the agent-presets roots overlay
  * (rc host line only; the 0.1.2 line's preset package self-ships its root),
- * then the telemetry switch. Two host API generations are mirrored and
+ * then the telemetry switch. Three host API generations are mirrored and
  * feature-detected per run — see the `hostLine` branch below. Exported so
  * the drift tripwire can compare this assembly against the launcher's own
  * dump without booting anything.

package/lib/types/preflight-runner.js

@@ -131,7 +131,7 @@ class PreflightInfraError extends Error {
  * bundle layers in `dsh.profile.bundles` order, the profile user layer, the
  * home-level user layer, `--patch` overlays, the agent-presets roots overlay
  * (rc host line only; the 0.1.2 line's preset package self-ships its root),
- * then the telemetry switch. Two host API generations are mirrored and
+ * then the telemetry switch. Three host API generations are mirrored and
  * feature-detected per run — see the `hostLine` branch below. Exported so
  * the drift tripwire can compare this assembly against the launcher's own
  * dump without booting anything.
@@ -158,6 +158,8 @@ export async function composePreflightPatches(profile, patchFiles, root, home, b
     }
     const composeEntries = appBoot.composeEntries;
     const healProfilesModuleFallback = appBoot.healProfilesModuleFallback;
+    const createProfileResolutionGeneration = appBoot.createProfileResolutionGeneration;
+    const createRuntimeResolution = appBoot.createRuntimeResolution;
     const loadOptionalPatches = appBoot.loadOptionalPatches;
     const loadOverlayPatches = appBoot.loadOverlayPatches;
     const loadProfile = appBoot.loadProfile;
@@ -174,12 +176,21 @@ export async function composePreflightPatches(profile, patchFiles, root, home, b
     // the profile composition: the heal moved behind the async options API and
     // below the profile load (see HealProfilesModuleFallback), and the launcher
     // dropped its agent-presets shipped-root overlay because the preset package
-    // now self-ships its root. DEFAULT_PROFILE_PATCH_RELOAD is a value export
-    // only the new line carries, so it is the feature marker; a version parse
-    // would break on exactly the unreleased builds this runner must dry-run.
-    // Both lines stay supported: prod hosts run the rc line until 0.1.2 lands
-    // on npm.
-    const hostLine = 'DEFAULT_PROFILE_PATCH_RELOAD' in appBoot ? '0.1.2' : 'rc';
+    // now self-ships its root. The 0.1.6 line flipped the default resolution
+    // mode from link to runtime: its compose computes an immutable resolution
+    // generation instead of materializing fallback links, and it removed
+    // DEFAULT_PROFILE_PATCH_RELOAD — the 0.1.2 line's marker. The 0.1.7 line
+    // deleted the fallback projections outright (in-memory runtime resolution
+    // interception): its compose calls createRuntimeResolution and carries
+    // neither older marker, so the markers must be probed newest-first. Each
+    // marker is a value export only its line carries; a version parse would
+    // break on exactly the unreleased builds this runner must dry-run. All
+    // lines stay supported: prod hosts run 0.1.5 until the next npm line lands.
+    const hostLine = 'createRuntimeResolution' in appBoot
+        ? '0.1.7'
+        : 'createProfileResolutionGeneration' in appBoot
+            ? '0.1.6'
+            : 'DEFAULT_PROFILE_PATCH_RELOAD' in appBoot ? '0.1.2' : 'rc';
     if (hostLine === 'rc')
         healProfilesModuleFallback(anchor, resolvedHome);
     const composed = loadProfile(NAME, profile, anchor, resolvedHome, { userLayer: true });
@@ -192,6 +203,22 @@ export async function composePreflightPatches(profile, patchFiles, root, home, b
     if (hostLine === '0.1.2') {
         await healProfilesModuleFallback({ installAnchor: anchor, profile: composed, home: resolvedHome });
     }
+    else if (hostLine === '0.1.6') {
+        // The launcher compose's runtime-mode step (apps/cli composeProfile):
+        // compute the generation AFTER the profile load and root-config rewrite,
+        // materializing nothing. Awaited, so a resolution-graph failure rejects
+        // the compose instead of escaping as an unhandled rejection. The explicit
+        // home keeps the recorded profilesDir on the deployment under check.
+        await createProfileResolutionGeneration({ installAnchor: anchor, profile: composed, home: resolvedHome });
+    }
+    else if (hostLine === '0.1.7') {
+        // The 0.1.7 launcher compose (apps/cli composeProfile): the resolution is
+        // computed in memory right after the profile load and root-config rewrite
+        // — the older lines' fallback projections are gone for good. Awaited, so
+        // a resolution-graph failure rejects the compose instead of escaping as
+        // an unhandled rejection.
+        await createRuntimeResolution({ installAnchor: anchor, profile: composed });
+    }
     const homePatches = loadOptionalPatches(NAME, join(resolvedHome, HOME_PATCH_FILENAME)) ?? [];
     const overlays = patchFiles.flatMap(file => loadOverlayPatches(NAME, resolve(file)));
     const bundlePatches = composed.layers.flatMap(layer => layer.patches);

package/lib/types/restart-context.js

@@ -2,12 +2,17 @@
  * Restart-record context injection and interrupted-session continuity. After
  * a scheduled restart, the FULL report waits for the initiating session's
  * root agent, whenever it resumes (session restore is lazy, so no other
- * session is ever woken for reporting); a record without an initiator is
- * claimed by the first root agent created. Separately, a snapshot written at
- * SIGTERM time (`interrupted-sessions.json`) records which root sessions had
- * a live turn when the process stopped, so the next restart boot can resume
- * those sessions and queue a "continue" turn. Pure logic reads the durable
- * files; the plugin wires them into `agent/created` and `agent.followup`.
+ * session is ever woken for reporting). A record without an initiator splits
+ * by kind: one carrying diagnostics someone must hear about (an unplanned
+ * recovery, a composition rollback, a failed restart) is claimed by the
+ * first root agent created, while a bare planned outcome — the restart was
+ * driven from outside the host and the operator's terminal already has the
+ * announcement — is settled without waking anyone. Separately, a snapshot
+ * written at SIGTERM time (`interrupted-sessions.json`) records which root
+ * sessions had a live turn when the process stopped, so the next restart
+ * boot can resume those sessions and queue a "continue" turn. Pure logic
+ * reads the durable files; the plugin wires them into `agent/created` and
+ * `agent.followup`.
  */
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { stateFile } from "./state-files.js";

package/locale/en.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "Ankh Guard",
+    "description": "Gate self-modification restarts on a green build and test credential."
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "重启守卫",
+    "description": "先证明构建与测试通过，才放行自我修改的重启。"
+  }
+}