gestalt-mobile 0.7.0 → 0.8.0

package/dist/server/server/composition.js

@@ -38,6 +38,8 @@ import { CachedSkillCatalog } from './platform/skills/cached-skill-catalog.js';
 import { compileSkillOverride } from './features/skills/model/skill-profile.js';
 import { SupervisedPlanRegistry } from './features/plans/application/supervised-plan-registry.js';
 import { FilesystemPlanStatusSource } from './platform/plans/filesystem-plan-status-source.js';
+import { checkpointPlanMeasurement } from './platform/plans/plan-measurement-command.js';
+import { PlanMeasurementRefresh } from './platform/plans/plan-measurement-refresh.js';
 const generatedProtocolVersion = 'codex-cli 0.144.3';
 export async function composeRelayApp(options) {
     const root = resolve(options.root);
@@ -52,6 +54,7 @@ export async function composeRelayApp(options) {
     const idempotency = new SqliteIdempotencyStore(database);
     const supervisedPlans = new SupervisedPlanRegistry();
     const planStatusSource = new FilesystemPlanStatusSource(join(dirname(databasePath), 'plans'));
+    const planMeasurementHelperPath = options.planMeasurementHelperPath ?? process.env.GESTALT_MOBILE_ORG_PLAN_HELPER;
     const withPendingInteractions = (session) => (session ? { ...session, pendingInteractions: interactions.list(session.id) } : null);
     const events = new SessionEventBus();
     const workspaces = new FilesystemWorkspaceCatalog(root);
@@ -84,6 +87,7 @@ export async function composeRelayApp(options) {
     const gitFetches = new GitFetchCoordinator(fetchUpstream);
     const gitSummaries = new GitSummaryCache(inspectGit);
     let recoverExitedSession = () => { };
+    let planMeasurementRefresh;
     const runtime = options.startAppServers
         ? new CodexSessionRuntime(options.launchAppServer ?? launchCodexAppServer, undefined, (sessionId, notification) => {
             const occurredAt = new Date().toISOString();
@@ -109,12 +113,21 @@ export async function composeRelayApp(options) {
             return true;
         }, (sessionId) => recoverExitedSession(sessionId), resolveSkills, planStatusSource, (sessionId, update) => {
             supervisedPlans.accept(sessionId, update);
+            planMeasurementRefresh?.accept(sessionId, update);
             if (update.kind === 'updated') {
                 const occurredAt = new Date().toISOString();
-                events.publish(journal.append(sessionId, 'plan.updated', update.plan, occurredAt));
+                events.publish(journal.append(sessionId, 'plan.updated', { plan: update.plan, reason: update.reason }, occurredAt));
             }
-        })
+        }, options.planMeasurementBaseUrl)
         : null;
+    if (runtime && planMeasurementHelperPath) {
+        planMeasurementRefresh = new PlanMeasurementRefresh(async (sessionId) => {
+            const session = sessions.find(sessionId);
+            if (!session)
+                throw new Error('CODEX_SESSION_NOT_RUNNING');
+            return runtime.readPlanMeasurement(session);
+        }, (planPath, stepId, snapshot) => checkpointPlanMeasurement(planMeasurementHelperPath, planPath, stepId, snapshot));
+    }
     const saveSession = (session) => {
         sessions.save(session);
         events.publish(journal.append(session.id, 'session.updated', session, session.updatedAt));
@@ -209,7 +222,12 @@ export async function composeRelayApp(options) {
             release: (session) => RelaySession.rehydrate(session).release(new Date().toISOString()).snapshot,
             remove: (id) => sessions.remove(id),
             idempotency,
-            close: runtime ? (id) => runtime.release(id) : undefined,
+            close: runtime
+                ? (id) => {
+                    planMeasurementRefresh?.stop(id);
+                    return runtime.release(id);
+                }
+                : undefined,
             replyInteraction: runtime
                 ? (sessionId, requestId, value) => runtime.resolveServerRequest(sessionId, requestId, value)
                 : undefined,
@@ -228,10 +246,25 @@ export async function composeRelayApp(options) {
             removeStatus: (id) => planStatusSource.remove(id, supervisedPlans.identity(id) ?? undefined),
             clear: (id) => supervisedPlans.clear(id),
             closed: (id) => {
+                planMeasurementRefresh?.stop(id);
                 const occurredAt = new Date().toISOString();
                 events.publish(journal.append(id, 'plan.closed', {}, occurredAt));
             },
         },
+        ...(runtime
+            ? {
+                planMeasurementRoutes: {
+                    exists: (id) => sessions.find(id) !== null,
+                    authorize: (id, authorization) => runtime.authorizePlanMeasurement(id, authorization),
+                    read: async (id) => {
+                        const session = sessions.find(id);
+                        if (!session)
+                            throw new Error('CODEX_SESSION_NOT_RUNNING');
+                        return runtime.readPlanMeasurement(session);
+                    },
+                },
+            }
+            : {}),
         interactions: {
             resolve: (sessionId, requestId, resolvedAt) => interactions.resolve(sessionId, requestId, resolvedAt),
             validate: (sessionId, requestId, value) => {
@@ -292,6 +325,7 @@ export async function composeRelayApp(options) {
         await restoreActiveSessions();
     });
     app.addHook('onClose', async () => {
+        planMeasurementRefresh?.stopAll();
         runtime?.stopAll();
         planStatusSource.closeAll();
         database.close();

package/dist/server/server/features/plans/application/measurement-snapshot.js

@@ -0,0 +1,41 @@
+/*
+ * Copyright (C) 2026 Dyne.org foundation
+ * Designed by Denis Roio <jaromil@dyne.org>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+export function createPlanMeasurementSnapshot(input) {
+    return Object.freeze({
+        capturedAt: input.capturedAt,
+        weeklyRemainingPercent: weeklyRemainingPercent(input.rateLimits),
+        threadTokens: totalThreadTokens(input.tokenUsage),
+    });
+}
+/** Returns the longest valid rate-limit window, which is the weekly window. */
+export function weeklyRateLimitWindow(windows) {
+    if (!windows)
+        return null;
+    const valid = windows.filter((window) => Number.isFinite(window.durationSeconds) &&
+        window.durationSeconds > 0 &&
+        Number.isFinite(window.usedPercent) &&
+        window.usedPercent >= 0 &&
+        window.usedPercent <= 100);
+    return valid.reduce((weekly, window) => (!weekly || window.durationSeconds > weekly.durationSeconds ? window : weekly), null);
+}
+export function weeklyRemainingPercent(windows) {
+    const weekly = weeklyRateLimitWindow(windows);
+    return weekly ? 100 - weekly.usedPercent : null;
+}
+/**
+ * Adds only the three independent cumulative counters in the normalized
+ * adapter contract. A missing or invalid counter makes token usage unavailable
+ * instead of silently treating it as zero.
+ */
+export function totalThreadTokens(usage) {
+    if (!usage || !Object.values(usage).every(isNonNegativeSafeInteger))
+        return null;
+    const total = usage.inputTokens + usage.cachedInputTokens + usage.outputTokens;
+    return Number.isSafeInteger(total) ? total : null;
+}
+function isNonNegativeSafeInteger(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}

package/dist/server/server/features/plans/application/parse-supervised-plan.js

@@ -142,7 +142,8 @@ function buildSteps(headings) {
 }
 function makeStep(heading) {
     const description = descriptionFor(heading);
-    if (!description)
+    const measurement = measurementFor(heading);
+    if (!description || measurement === null)
         return null;
     if (heading.level === 1) {
         const reviewStatus = heading.properties.get('REVIEW_STATUS');
@@ -158,6 +159,7 @@ function makeStep(heading) {
             reviewStatus: reviewStatus,
             skills: skills.split(/\s+/).filter(Boolean),
             description,
+            ...(measurement ? { measurement } : {}),
             children: [],
         };
     }
@@ -170,9 +172,54 @@ function makeStep(heading) {
         state: heading.state,
         priority: heading.priority,
         description,
+        ...(measurement ? { measurement } : {}),
         children: [],
     };
 }
+const measurementProperties = {
+    STARTED_AT: 'startedAt',
+    UPDATED_AT: 'updatedAt',
+    COMPLETED_AT: 'completedAt',
+    ELAPSED_SECONDS: 'elapsedSeconds',
+    WEEKLY_REMAINING_START: 'weeklyRemainingStart',
+    WEEKLY_REMAINING_CURRENT: 'weeklyRemainingCurrent',
+    WEEKLY_REMAINING_END: 'weeklyRemainingEnd',
+    WEEKLY_PERCENT_USED: 'weeklyPercentUsed',
+    TOKENS_START: 'tokensStart',
+    TOKENS_CURRENT: 'tokensCurrent',
+    TOKENS_END: 'tokensEnd',
+    TOKENS_USED: 'tokensUsed',
+};
+function measurementFor(heading) {
+    const measurement = {};
+    for (const [property, field] of Object.entries(measurementProperties)) {
+        const value = heading.properties.get(property);
+        if (value === undefined)
+            continue;
+        if (property.endsWith('_AT')) {
+            if (!isUtcIsoInstant(value))
+                return null;
+            measurement[field] = value;
+            continue;
+        }
+        if (!/^\d+$/.test(value))
+            return null;
+        const number = Number(value);
+        if (!Number.isSafeInteger(number) || (property.startsWith('WEEKLY_') && number > 100))
+            return null;
+        measurement[field] = number;
+    }
+    return Object.keys(measurement).length === 0 ? undefined : measurement;
+}
+function isUtcIsoInstant(value) {
+    if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{3})?Z$/.test(value))
+        return false;
+    const instant = new Date(value);
+    if (Number.isNaN(instant.getTime()))
+        return false;
+    const canonical = instant.toISOString();
+    return value === canonical || value === canonical.replace('.000Z', 'Z');
+}
 function descriptionFor(heading) {
     const fields = heading.level === 1 ? ['Effort', 'Goal', 'Notes'] : ['Why', 'Change', 'Tests', 'Done when'];
     if (!fields.every((field) => heading.descriptions.has(field)))

package/dist/server/server/features/plans/get-measurement/endpoint.js

@@ -0,0 +1,21 @@
+/*
+ * Copyright (C) 2026 Dyne.org foundation
+ * Designed by Denis Roio <jaromil@dyne.org>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+export function registerGetPlanMeasurement(app, deps) {
+    app.get('/api/sessions/:id/plan-measurement', async (request, reply) => {
+        const id = request.params.id;
+        const authorization = typeof request.headers.authorization === 'string'
+            ? request.headers.authorization
+            : undefined;
+        if (!deps.exists(id) || !deps.authorize(id, authorization))
+            return reply.code(404).send({ code: 'SESSION_NOT_FOUND' });
+        try {
+            return reply.send(await deps.read(id));
+        }
+        catch {
+            return reply.code(503).send({ code: 'PLAN_MEASUREMENT_UNAVAILABLE' });
+        }
+    });
+}

package/dist/server/server/features/plans/get-measurement/response.js

@@ -0,0 +1,6 @@
+/*
+ * Copyright (C) 2026 Dyne.org foundation
+ * Designed by Denis Roio <jaromil@dyne.org>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+export {};

package/dist/server/server/platform/codex/codex-process-launcher.js

@@ -31,5 +31,7 @@ export function codexChildEnvironment(environment) {
     const inherited = { ...process.env };
     delete inherited.GESTALT_MOBILE_ORG_PLAN_STATUS_FILE;
     delete inherited.GESTALT_MOBILE_ORG_PLAN_STATUS_DIRECTORY;
+    delete inherited.GESTALT_MOBILE_ORG_PLAN_MEASUREMENT_URL;
+    delete inherited.GESTALT_MOBILE_ORG_PLAN_MEASUREMENT_TOKEN;
     return { ...inherited, ...environment };
 }

package/dist/server/server/platform/codex/session-runtime.js

@@ -4,6 +4,8 @@
  * SPDX-License-Identifier: AGPL-3.0-or-later
  */
 import { RelaySession, } from '../../features/sessions/model/relay-session.js';
+import { randomUUID } from 'node:crypto';
+import { createPlanMeasurementSnapshot, } from '../../features/plans/application/measurement-snapshot.js';
 import { gestaltQuizDynamicTool } from '../../../shared/contracts/quiz.js';
 export class CodexSessionRuntime {
     launch;
@@ -14,7 +16,8 @@ export class CodexSessionRuntime {
     resolveSkills;
     planStatusSource;
     onPlanStatus;
-    constructor(launch, processes = new Map(), onNotification, onServerRequest, onProcessExit, resolveSkills, planStatusSource, onPlanStatus) {
+    planMeasurementBaseUrl;
+    constructor(launch, processes = new Map(), onNotification, onServerRequest, onProcessExit, resolveSkills, planStatusSource, onPlanStatus, planMeasurementBaseUrl) {
         this.launch = launch;
         this.processes = processes;
         this.onNotification = onNotification;
@@ -23,11 +26,13 @@ export class CodexSessionRuntime {
         this.resolveSkills = resolveSkills;
         this.planStatusSource = planStatusSource;
         this.onPlanStatus = onPlanStatus;
+        this.planMeasurementBaseUrl = planMeasurementBaseUrl;
     }
     pendingRequests = new Map();
     exitUnsubscribers = new Map();
     threadIds = new Map();
     planStatusLeases = new Map();
+    planMeasurementTokens = new Map();
     async start(session, now, settings = {}) {
         const process = await this.launchForSession(session);
         try {
@@ -113,6 +118,24 @@ export class CodexSessionRuntime {
             throw new Error('CODEX_SESSION_NOT_RUNNING');
         await process.rpc.request('turn/interrupt', { threadId: session.threadId, turnId });
     }
+    async readPlanMeasurement(session) {
+        const process = this.processes.get(session.id);
+        if (!process || !session.threadId)
+            throw new Error('CODEX_SESSION_NOT_RUNNING');
+        const [rateLimits, thread] = await Promise.all([
+            process.rpc.request('account/rateLimits/read', {}),
+            process.rpc.request('thread/read', { threadId: session.threadId, includeTurns: true }),
+        ]);
+        return createPlanMeasurementSnapshot({
+            capturedAt: new Date().toISOString(),
+            rateLimits: rateLimitWindows(rateLimits),
+            tokenUsage: threadTokenUsage(thread),
+        });
+    }
+    authorizePlanMeasurement(sessionId, authorization) {
+        const token = this.planMeasurementTokens.get(sessionId);
+        return Boolean(token && authorization === `Bearer ${token}`);
+    }
     async readHistory(session) {
         const process = this.processes.get(session.id);
         if (!process || !session.threadId)
@@ -169,6 +192,7 @@ export class CodexSessionRuntime {
         this.exitUnsubscribers.set(sessionId, process.onExit?.(() => {
             this.processes.delete(sessionId);
             this.threadIds.delete(sessionId);
+            this.planMeasurementTokens.delete(sessionId);
             this.exitUnsubscribers.delete(sessionId);
             this.releasePlanStatus(sessionId);
             this.onProcessExit?.(sessionId);
@@ -181,14 +205,24 @@ export class CodexSessionRuntime {
         if (lease)
             this.planStatusLeases.set(session.id, lease);
         try {
+            const token = randomUUID();
+            this.planMeasurementTokens.set(session.id, token);
             return this.launch({
                 profile: session.profile,
                 cwd: session.workspacePath,
                 skillsConfig: await this.resolveSkills?.(session),
-                ...(lease
+                ...((lease || this.planMeasurementBaseUrl)
                     ? {
                         environment: {
-                            GESTALT_MOBILE_ORG_PLAN_STATUS_DIRECTORY: lease.statusDirectory,
+                            ...(lease
+                                ? { GESTALT_MOBILE_ORG_PLAN_STATUS_DIRECTORY: lease.statusDirectory }
+                                : {}),
+                            ...(this.planMeasurementBaseUrl
+                                ? {
+                                    GESTALT_MOBILE_ORG_PLAN_MEASUREMENT_URL: `${this.planMeasurementBaseUrl}/api/sessions/${session.id}/plan-measurement`,
+                                    GESTALT_MOBILE_ORG_PLAN_MEASUREMENT_TOKEN: token,
+                                }
+                                : {}),
                         },
                     }
                     : {}),
@@ -204,3 +238,41 @@ export class CodexSessionRuntime {
         this.planStatusLeases.delete(sessionId);
     }
 }
+function rateLimitWindows(value) {
+    const limits = asRecord(value)?.rateLimits;
+    if (!Array.isArray(limits))
+        return undefined;
+    return limits.flatMap((limit) => {
+        const record = asRecord(limit);
+        const durationMinutes = record?.windowDurationMins;
+        const usedPercent = record?.usedPercent;
+        return typeof durationMinutes === 'number' && typeof usedPercent === 'number'
+            ? [{ durationSeconds: durationMinutes * 60, usedPercent }]
+            : [];
+    });
+}
+function threadTokenUsage(value) {
+    const turns = asRecord(asRecord(value)?.thread)?.turns;
+    if (!Array.isArray(turns))
+        return undefined;
+    let inputTokens = 0;
+    let cachedInputTokens = 0;
+    let outputTokens = 0;
+    for (const turn of turns) {
+        const usage = asRecord(asRecord(turn)?.tokenUsage);
+        if (!usage)
+            return undefined;
+        const input = usage.inputTokens;
+        const cached = usage.cachedInputTokens;
+        const output = usage.outputTokens;
+        if (typeof input !== 'number' || typeof cached !== 'number' || typeof output !== 'number')
+            return undefined;
+        inputTokens += input;
+        cachedInputTokens += cached;
+        outputTokens += output;
+    }
+    return { inputTokens, cachedInputTokens, outputTokens };
+}
+function asRecord(value) {
+    return value && typeof value === 'object' ? value : undefined;
+}

package/dist/server/server/platform/plans/filesystem-plan-status-source.js

@@ -259,7 +259,7 @@ class ActiveLease {
                     const previousStatusPath = this.activeStatusPath;
                     this.activeStatusPath = statusPath;
                     this.onActiveStatusPath(statusPath);
-                    this.listener({ kind: 'updated', plan: result.plan, identity });
+                    this.listener({ kind: 'updated', plan: result.plan, identity, planPath, reason: signal.reason });
                     if (previousStatusPath && previousStatusPath !== statusPath)
                         await rm(previousStatusPath, { force: true }).catch(() => { });
                 }
@@ -288,12 +288,19 @@ function parseSignal(source) {
             return null;
         if (typeof signal.reason !== 'string' || !isRfc3339Utc(signal.updatedAt))
             return null;
-        return { planPath: signal.planPath, updatedAt: signal.updatedAt };
+        return {
+            planPath: signal.planPath,
+            updatedAt: signal.updatedAt,
+            reason: isPlanSignalReason(signal.reason) ? signal.reason : null,
+        };
     }
     catch {
         return null;
     }
 }
+function isPlanSignalReason(value) {
+    return value === 'authoring-start' || value === 'work-start' || value === 'checkpoint' || value === 'update';
+}
 function isRfc3339Utc(value) {
     return (typeof value === 'string' &&
         /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/.test(value) &&

package/dist/server/server/platform/plans/plan-measurement-command.js

@@ -0,0 +1,13 @@
+/*
+ * Copyright (C) 2026 Dyne.org foundation
+ * Designed by Denis Roio <jaromil@dyne.org>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execute = promisify(execFile);
+export const PLAN_MEASUREMENT_COMMAND_TIMEOUT_MS = 15_000;
+/** Invokes the explicitly configured Org Plan helper without a shell. */
+export async function checkpointPlanMeasurement(helperPath, planPath, stepId, snapshot) {
+    await execute(helperPath, ['measure', 'checkpoint', planPath, stepId, JSON.stringify(snapshot)], { shell: false, timeout: PLAN_MEASUREMENT_COMMAND_TIMEOUT_MS });
+}

package/dist/server/server/platform/plans/plan-measurement-refresh.js

@@ -0,0 +1,89 @@
+/*
+ * Copyright (C) 2026 Dyne.org foundation
+ * Designed by Denis Roio <jaromil@dyne.org>
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+export const PLAN_MEASUREMENT_REFRESH_MS = 60_000;
+/**
+ * Refreshes the current WIP step at a bounded cadence. A refresh is deliberately
+ * owned by the session that owns the plan, so replacing, closing, or stopping a
+ * session cannot leave a timer writing another session's plan.
+ */
+export class PlanMeasurementRefresh {
+    readSnapshot;
+    checkpoint;
+    active = new Map();
+    timers = new Map();
+    inFlight = new Set();
+    constructor(readSnapshot, checkpoint) {
+        this.readSnapshot = readSnapshot;
+        this.checkpoint = checkpoint;
+    }
+    accept(sessionId, update) {
+        const next = activeMeasurement(update);
+        if (!next)
+            return this.stop(sessionId);
+        const current = this.active.get(sessionId);
+        this.active.set(sessionId, next);
+        if (current?.planPath === next.planPath && current.stepId === next.stepId)
+            return;
+        this.clearTimer(sessionId);
+        this.schedule(sessionId);
+    }
+    stop(sessionId) {
+        this.active.delete(sessionId);
+        this.clearTimer(sessionId);
+    }
+    stopAll() {
+        for (const sessionId of this.active.keys())
+            this.stop(sessionId);
+    }
+    schedule(sessionId) {
+        this.timers.set(sessionId, setTimeout(() => {
+            this.timers.delete(sessionId);
+            void this.refresh(sessionId);
+        }, PLAN_MEASUREMENT_REFRESH_MS));
+    }
+    async refresh(sessionId) {
+        const active = this.active.get(sessionId);
+        if (!active || this.inFlight.has(sessionId))
+            return;
+        this.inFlight.add(sessionId);
+        try {
+            await this.checkpoint(active.planPath, active.stepId, await this.readSnapshot(sessionId));
+        }
+        catch {
+            // A transient Codex or helper failure makes this tick unavailable only.
+        }
+        finally {
+            this.inFlight.delete(sessionId);
+            if (this.active.get(sessionId) === active && !this.timers.has(sessionId))
+                this.schedule(sessionId);
+        }
+    }
+    clearTimer(sessionId) {
+        const timer = this.timers.get(sessionId);
+        if (timer)
+            clearTimeout(timer);
+        this.timers.delete(sessionId);
+    }
+}
+function activeMeasurement(update) {
+    if (update.kind !== 'updated')
+        return null;
+    const step = findStep(update.plan, update.plan.currentStepId);
+    return step?.state === 'WIP' ? { planPath: update.planPath, stepId: step.id } : null;
+}
+function findStep(plan, id) {
+    const visit = (steps) => {
+        for (const step of steps) {
+            if (step.id === id)
+                return step;
+            const child = visit(step.children);
+            if (child)
+                return child;
+        }
+        return undefined;
+    };
+    return visit(plan.steps);
+}

package/package.json

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