gestalt-mobile 0.37.0 → 0.38.0

package/README.md

@@ -32,6 +32,17 @@ The command prints the loopback URL when it is ready. Open that URL in a
 browser. Press Ctrl-C, or send SIGINT or SIGTERM, to stop the HTTP server,
 active Codex subprocesses, and database cleanly.
 
+Use `--icon <path>` to replace the installed PWA application icon with a local
+SVG or PNG. Relative paths resolve from the directory where Mobile is started:
+
+```sh
+gestalt-mobile --cwd . --icon ./branding/project-icon.svg
+```
+
+Without `--icon`, Mobile keeps its packaged Gestalt icons. SVG icons are
+declared scalable; PNG dimensions are read from the file. A square PNG of at
+least 512×512 is recommended for consistent launcher presentation.
+
 ### Run this checkout
 
 `npm run start` builds and runs the current checkout with the same managed
@@ -149,6 +160,7 @@ checks with `npm run format:check`, `npm run license:check`, `npm run check`,
 | `--public-origin <origin>` | Loopback Vite origin | Exact browser origin for passkeys; required for non-loopback hosts |
 | `--disable-passkey-auth`   | Off                  | Disable passkey access control and serve every client directly     |
 | `--data-dir <path>`        | XDG state directory  | Directory containing `relay.sqlite`                                |
+| `--icon <path>`            | Gestalt icons        | SVG or PNG used when installing the PWA                            |
 | `--skills <profile>`       |                      | Apply a saved global profile to every session                      |
 | `--skills list`            |                      | List global profiles without starting the server                   |
 | `--help`                   |                      | Print usage without starting the application                       |

package/dist/server/server/app.js

@@ -19,6 +19,7 @@ import { registerOrgPlanAttentionRoutes } from './features/org-plan-attention/re
 import { registerAutopilotRoutes } from './features/autopilot/register-routes.js';
 import { registerFileRoutes } from './features/files/register-routes.js';
 import { registerMaintenanceRoutes } from './features/maintenance/register-routes.js';
+import { registerPwaRoutes } from './features/pwa/register-routes.js';
 export async function buildApp(deps) {
     // Keep the default boundary finite even when an endpoint forgot a narrower schema.
     const app = fastify({ logger: false, bodyLimit: 1024 * 1024 });
@@ -32,6 +33,8 @@ export async function buildApp(deps) {
         return payload;
     });
     await app.register(fastifyCookie);
+    if (deps.pwaIcon)
+        registerPwaRoutes(app, deps.pwaIcon);
     if (deps.staticDir)
         await app.register(fastifyStatic, { root: deps.staticDir });
     if (deps.auth)

package/dist/server/server/cli.js

@@ -14,6 +14,7 @@ import { composeRelayApp } from './composition.js';
 import { CliUsageError, parseConfig } from './config.js';
 import { LauncherProfileCatalog } from './platform/catalog/launcher-profile-catalog.js';
 import { FilesystemSkillProfileStore } from './platform/skills/filesystem-skill-profile-store.js';
+import { loadPwaIcon } from './platform/pwa/load-pwa-icon.js';
 const runFile = promisify(execFile);
 export const usage = `Usage: gestalt-mobile [options]
 
@@ -24,6 +25,7 @@ Options:
   --public-origin <origin> Exact HTTPS browser origin for passkeys (localhost may use HTTP)
   --disable-passkey-auth Disable passkey access control (unsafe on shared or network hosts)
   --data-dir <path>  Directory for persistent application data
+  --icon <path>      SVG or PNG used as the installed PWA application icon
   --skills <profile> Use a global skill profile for every session
   --skills list      List saved global skill profiles without starting the server
   --help             Show this help
@@ -205,6 +207,14 @@ export async function runCli(dependencies = {}) {
         stderr.write(`Unknown skill profile: ${config.skillsProfile}\n\n${usage}\n`);
         return 2;
     }
+    let pwaIcon;
+    try {
+        pwaIcon = config.iconPath ? await loadPwaIcon(config.iconPath) : undefined;
+    }
+    catch (error) {
+        stderr.write(`${error instanceof Error ? error.message : 'Invalid --icon file'}\n\n${usage}\n`);
+        return 2;
+    }
     const diagnosis = await (dependencies.runStartupDoctor ?? runStartupDoctor)(cwd);
     if (diagnosis.report)
         stderr.write(diagnosis.report);
@@ -219,6 +229,7 @@ export async function runCli(dependencies = {}) {
         relyingParty: config.relyingParty,
         passkeyAuthEnabled: config.passkeyAuthEnabled,
         staticDir: packagedClientDir(moduleUrl),
+        pwaIcon,
         profiles: new LauncherProfileCatalog(),
         installedCodexVersion,
         installedKimiVersion,

package/dist/server/server/composition.js

@@ -149,18 +149,18 @@ export async function composeRelayApp(options) {
         reconcile: async (sessionId) => {
             const session = sessions.find(sessionId);
             if (!session)
-                return;
+                return false;
             // Kimi sessions own no child-process projection; one detached history
             // read supplies the whole reconciliation, mirroring the codex tail.
             if (session.provider === 'kimi') {
                 if (!kimiRuntime)
-                    return;
+                    return false;
                 const history = await kimiRuntime.readHistory(session);
                 // Forget may commit while the detached history reader is still in
                 // flight. Revalidate ownership before handing its result to the
                 // registry, whose publisher intentionally keeps the journal strict.
                 if (!sessions.find(sessionId))
-                    return;
+                    return false;
                 const occurredAt = new Date().toISOString();
                 activity.observe({
                     sessionId,
@@ -169,16 +169,22 @@ export async function composeRelayApp(options) {
                     ...(session.threadId ? { threadId: session.threadId } : {}),
                     ...(history.activeTurnId ? { turnId: history.activeTurnId } : {}),
                 });
-                return;
+                return true;
             }
             if (!runtime)
-                return;
+                return false;
             const history = await runtime.readHistory(session);
-            // Forget may commit while the detached history reader is still in
-            // flight. Revalidate ownership before handing its result to the
-            // registry, whose publisher intentionally keeps the journal strict.
+            const children = await runtime.listDirectChildren(session);
+            const childProcesses = new Map();
+            await mapWithConcurrency([...children], 4, async (child) => {
+                childProcesses.set(child.id, await runtime.inspectChildProcesses(session, child));
+            });
+            // The writer read is also asynchronous; it cannot publish after the
+            // durable owner has gone away either.
             if (!sessions.find(sessionId))
-                return;
+                return false;
+            // Publish only after the entire authoritative read succeeds. A fresh
+            // root with stale child topology is not a valid supervision snapshot.
             const occurredAt = new Date().toISOString();
             activity.observe({
                 sessionId,
@@ -187,19 +193,11 @@ export async function composeRelayApp(options) {
                 ...(session.threadId ? { threadId: session.threadId } : {}),
                 ...(history.activeTurnId ? { turnId: history.activeTurnId } : {}),
             });
-            const children = await runtime.listDirectChildren(session);
-            const childProcesses = new Map();
-            await mapWithConcurrency([...children], 4, async (child) => {
-                childProcesses.set(child.id, await runtime.inspectChildProcesses(session, child));
-            });
-            // The writer read is also asynchronous; it cannot publish after the
-            // durable owner has gone away either.
-            if (!sessions.find(sessionId))
-                return;
             activity.childrenReconciled(sessionId, occurredAt, children.map((child) => ({
                 ...child,
                 processes: childProcesses.get(child.id) ?? [],
             })));
+            return true;
         },
     });
     const autopilot = new AutopilotCoordinator({
@@ -1028,6 +1026,7 @@ export async function composeRelayApp(options) {
             },
             logger: console,
             staticDir: options.staticDir,
+            pwaIcon: options.pwaIcon,
             recentThreads: recentThreadsForRelay,
             bootstrap: {
                 workspaces,

package/dist/server/server/config.js

@@ -15,6 +15,7 @@ const optionNames = new Set([
     '--data-dir',
     '--public-origin',
     '--skills',
+    '--icon',
 ]);
 const flagNames = new Set(['--disable-passkey-auth']);
 export function parseConfig(args, cwd = process.cwd()) {
@@ -57,8 +58,14 @@ export function parseConfig(args, cwd = process.cwd()) {
         root: resolve(cwd, values.get('--cwd') ?? '.'),
         dataDir: values.get('--data-dir'),
         skillsProfile: values.get('--skills'),
+        iconPath: values.has('--icon') ? resolveIconPath(cwd, values.get('--icon')) : undefined,
     };
 }
+function resolveIconPath(cwd, value) {
+    if (!/\.(?:png|svg)$/i.test(value))
+        throw new CliUsageError('--icon must reference an SVG or PNG file');
+    return resolve(cwd, value);
+}
 export function normalizePublicOrigin(value) {
     if (!/^[a-z][a-z\d+.-]*:\/\/[^/?#\s\\\\]+\/?$/i.test(value))
         throw new CliUsageError('--public-origin must be a bare origin without a path, query, or fragment');

package/dist/server/server/features/agent-activity/registry.js

@@ -157,7 +157,9 @@ export class AgentActivityRegistry {
         const now = this.options.now?.() ?? new Date().toISOString();
         this.reconciling(sessionId, now);
         try {
-            await this.options.reconcile?.(sessionId);
+            const observed = await this.options.reconcile?.(sessionId);
+            if (observed !== true)
+                throw new Error('AGENT_ACTIVITY_RECONCILE_NO_EVIDENCE');
             if (this.#generation.get(sessionId) === generation)
                 this.reconciled(sessionId, this.options.now?.() ?? now);
         }

package/dist/server/server/features/autopilot/application/policy.js

@@ -91,7 +91,7 @@ export function decideAutopilot(input) {
         return { kind: 'safetyPause', reason: 'actionRateExceeded' };
     if (!activity || activity.confidence !== 'fresh')
         return { kind: 'reconcile' };
-    if (Date.parse(now) - Date.parse(activity.root.lastActivityAt) > policy.staleAfterMs)
+    if (Date.parse(now) - Date.parse(activity.root.observedAt) > policy.staleAfterMs)
         return { kind: 'reconcile' };
     const disposition = classifyAgentActivity(activity);
     if (disposition === 'attention')

package/dist/server/server/features/autopilot/application/service.js

@@ -417,9 +417,11 @@ export class AutopilotCoordinator {
             case 'scheduleContinuation':
                 if (session?.activeTurnId || this.deps.pendingInteraction(sessionId))
                     break;
+                const plan = this.deps.plan(sessionId)?.plan;
                 if (this.deps.executorController &&
-                    this.deps.plan(sessionId)?.plan &&
-                    this.currentExecutor(sessionId, this.deps.plan(sessionId).plan, prior.consecutiveNoProgress, prior.executor)) {
+                    plan &&
+                    !this.requiresRootBoundary(prior, plan) &&
+                    this.currentExecutor(sessionId, plan, prior.consecutiveNoProgress, prior.executor)) {
                     this.enqueue(sessionId, async () => {
                         await this.enforceSupervisedLifecycle(sessionId, 'stateChanged');
                     });
@@ -1012,6 +1014,7 @@ export class AutopilotCoordinator {
         if (this.deps.executorController &&
             retained &&
             !current.executor?.replacement &&
+            !this.requiresRootBoundary(current, retained.plan) &&
             this.currentExecutor(sessionId, retained.plan, current.consecutiveNoProgress, current.executor)) {
             const now = this.deps.now();
             const cancelled = this.cancelScheduledControl(current, now);
@@ -1159,6 +1162,10 @@ export class AutopilotCoordinator {
             !state?.requestedEnabled ||
             this.deps.pendingInteraction(sessionId))
             return false;
+        // Checkpoints are root-owned report boundaries. Once an executor has made
+        // one eligible, never mechanically resume it past the unreported result.
+        if (this.requiresRootBoundary(state, retained.plan))
+            return false;
         const executor = this.currentExecutor(sessionId, retained.plan, state.consecutiveNoProgress, state.executor);
         const executorChanged = executor ? this.persistExecutor(sessionId, executor) : false;
         if (executor && (await this.reconcileSplitBrain(sessionId, executor)))
@@ -1167,6 +1174,18 @@ export class AutopilotCoordinator {
             this.supersedeExecutorCommands(sessionId, retained.identity, retained.plan, executor);
         if (executorChanged && this.wakeForExecutorChange(sessionId, executor))
             return true;
+        if (executor && this.executorTurnActive(executor, this.deps.activity(sessionId))) {
+            // A malformed root yield must not send a duplicate continuation into a
+            // still-running executor. A valid parked lease already owns its wake;
+            // otherwise retain one bounded reconciliation watchdog as the fallback.
+            const parkedLease = state.supervision?.waitLease;
+            const parkedWakeLive = state.supervision?.outcome === 'parked' &&
+                parkedLease &&
+                this.parkedSubscriptions.get(sessionId) === parkedLease.id;
+            if (!parkedWakeLive)
+                this.armExecutorRefresh(sessionId, this.deps.policy.executorContinuationMaxMs);
+            return true;
+        }
         const decision = decideSupervisedLifecycle({
             plan: retained.plan,
             event,
@@ -1249,6 +1268,21 @@ export class AutopilotCoordinator {
             }
         }
     }
+    requiresRootBoundary(state, plan) {
+        const reportedL2 = new Set(state.checkpoints?.reportedL2Ids ?? []);
+        const reportedL1 = new Set(state.checkpoints?.reportedL1Ids ?? []);
+        const epochs = new Map(state.checkpoints?.completionEpochs?.map((entry) => [entry.target, entry]) ?? []);
+        const epochNeedsReport = (target) => {
+            const epoch = epochs.get(target);
+            return Boolean(epoch?.reopened || epoch?.completed === false);
+        };
+        return plan.steps.some((l1) => l1.children.some((l2) => l2.state === 'DONE' &&
+            (!reportedL2.has(JSON.stringify([l1.id, l2.id])) ||
+                epochNeedsReport(checkpointTarget('l2', l1.id, l2.id)))) ||
+            (l1.state === 'DONE' &&
+                l1.reviewStatus === 'REVIEWED' &&
+                (!reportedL1.has(l1.id) || epochNeedsReport(checkpointTarget('l1', l1.id)))));
+    }
     currentExecutor(sessionId, plan, continuationCount, persisted) {
         const stepIndex = plan.steps.findIndex((step) => step.id === plan.currentStepId || step.state === 'WIP');
         const index = stepIndex >= 0 ? stepIndex : plan.steps.findIndex((step) => step.state !== 'DONE');
@@ -1987,6 +2021,14 @@ export class AutopilotCoordinator {
                 child.state === 'awaitingAgent' ||
                 child.ownedProcesses?.some((process) => process.state === 'running' || process.state === 'detached-active')));
     }
+    executorTurnActive(executor, activity) {
+        if (activity?.confidence !== 'fresh')
+            return false;
+        const child = activity.subagents.find((candidate) => (candidate.threadId ?? candidate.id) === executor.threadId &&
+            candidate.taskPath === executor.taskPath &&
+            (candidate.continuationGeneration ?? 1) === executor.continuationGeneration);
+        return child?.state === 'working' || child?.state === 'awaitingAgent';
+    }
     /** Builds both GET and pre-commit event payloads from the same prospective facts. */
     snapshotFor(next, prospectiveControl) {
         const session = this.deps.session(next.sessionId);
@@ -2180,7 +2222,7 @@ export class AutopilotCoordinator {
             // yield to. A later activity/watchdog event will evaluate it again.
             const activity = this.deps.activity(sessionId);
             if (activity?.confidence === 'fresh' &&
-                Date.parse(this.deps.now()) - Date.parse(activity.root.lastActivityAt) <=
+                Date.parse(this.deps.now()) - Date.parse(activity.root.observedAt) <=
                     this.deps.policy.staleAfterMs) {
                 this.evaluate(sessionId);
             }

package/dist/server/server/features/pwa/register-routes.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2026 Dyne.org foundation
+ * Designed by Denis Roio <jaromil@dyne.org>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+const manifestBase = {
+    id: '/',
+    name: 'Gestalt Mobile',
+    short_name: 'Gestalt',
+    description: 'A mobile interface for durable Codex development sessions.',
+    start_url: '/',
+    scope: '/',
+    display: 'standalone',
+    background_color: '#141414',
+    theme_color: '#141414',
+    categories: ['productivity', 'utilities'],
+};
+/** Overrides only install metadata; ordinary client assets stay package-static. */
+export function registerPwaRoutes(app, icon) {
+    const iconPath = `/install-icon.${icon.extension}`;
+    app.get('/manifest.webmanifest', async (_request, reply) => reply
+        .header('Cache-Control', 'no-cache')
+        .type('application/manifest+json')
+        .send({
+        ...manifestBase,
+        icons: [
+            {
+                src: iconPath,
+                sizes: icon.sizes,
+                type: icon.contentType,
+                purpose: 'any',
+            },
+        ],
+    }));
+    app.get(iconPath, async (_request, reply) => reply.header('Cache-Control', 'no-cache').type(icon.contentType).send(icon.bytes));
+}

package/dist/server/server/platform/pwa/load-pwa-icon.js

@@ -0,0 +1,36 @@
+/*
+ * Copyright (C) 2026 Dyne.org foundation
+ * Designed by Denis Roio <jaromil@dyne.org>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { readFile } from 'node:fs/promises';
+import { extname } from 'node:path';
+const maxIconBytes = 5 * 1024 * 1024;
+const pngSignature = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+export async function loadPwaIcon(path) {
+    let bytes;
+    try {
+        bytes = await readFile(path);
+    }
+    catch {
+        throw new Error(`Unable to read --icon file: ${path}`);
+    }
+    if (bytes.length === 0 || bytes.length > maxIconBytes)
+        throw new Error('--icon must be a non-empty SVG or PNG no larger than 5 MiB');
+    const extension = extname(path).toLowerCase();
+    if (extension === '.svg') {
+        if (!/<svg(?:\s|>)/i.test(bytes.toString('utf8')))
+            throw new Error('--icon SVG does not contain an <svg> root');
+        return { bytes, contentType: 'image/svg+xml', extension: 'svg', sizes: 'any' };
+    }
+    if (extension !== '.png' ||
+        bytes.length < 24 ||
+        !bytes.subarray(0, 8).equals(pngSignature) ||
+        bytes.toString('ascii', 12, 16) !== 'IHDR')
+        throw new Error('--icon PNG has an invalid header');
+    const width = bytes.readUInt32BE(16);
+    const height = bytes.readUInt32BE(20);
+    if (width === 0 || height === 0)
+        throw new Error('--icon PNG has invalid dimensions');
+    return { bytes, contentType: 'image/png', extension: 'png', sizes: `${width}x${height}` };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gestalt-mobile",
-  "version": "0.37.0",
+  "version": "0.38.0",
   "description": "Mobile-first web relay for durable Codex development sessions",
   "keywords": [
     "codex",