forge-openclaw-plugin 0.2.69 → 0.2.70

package/dist/server/server/migrations/062_health_mobile_sync_sessions.sql

@@ -0,0 +1,55 @@
+CREATE TABLE IF NOT EXISTS health_mobile_sync_sessions (
+  id TEXT PRIMARY KEY,
+  pairing_session_id TEXT NOT NULL REFERENCES companion_pairing_sessions(id) ON DELETE CASCADE,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  status TEXT NOT NULL DEFAULT 'running',
+  schema_version TEXT NOT NULL DEFAULT 'healthkit-sync-v2',
+  requested_families_json TEXT NOT NULL DEFAULT '[]',
+  source_metadata_json TEXT NOT NULL DEFAULT '{}',
+  expected_counts_json TEXT NOT NULL DEFAULT '{}',
+  received_counts_json TEXT NOT NULL DEFAULT '{}',
+  byte_totals_json TEXT NOT NULL DEFAULT '{}',
+  affected_workout_ids_json TEXT NOT NULL DEFAULT '[]',
+  error_json TEXT NOT NULL DEFAULT '{}',
+  started_at TEXT NOT NULL,
+  completed_at TEXT,
+  failed_at TEXT,
+  aborted_at TEXT,
+  expired_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_health_mobile_sync_sessions_pairing_status
+  ON health_mobile_sync_sessions(pairing_session_id, status, started_at DESC);
+
+CREATE TABLE IF NOT EXISTS health_mobile_sync_chunks (
+  id TEXT PRIMARY KEY,
+  sync_session_id TEXT NOT NULL REFERENCES health_mobile_sync_sessions(id) ON DELETE CASCADE,
+  chunk_id TEXT NOT NULL,
+  sequence INTEGER NOT NULL,
+  family TEXT NOT NULL,
+  checksum_sha256 TEXT NOT NULL,
+  record_count INTEGER NOT NULL DEFAULT 0,
+  byte_count INTEGER NOT NULL DEFAULT 0,
+  payload_json TEXT NOT NULL DEFAULT '{}',
+  payload_summary_json TEXT NOT NULL DEFAULT '{}',
+  received_at TEXT NOT NULL,
+  applied_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE(sync_session_id, chunk_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_health_mobile_sync_chunks_session_sequence
+  ON health_mobile_sync_chunks(sync_session_id, sequence);
+
+CREATE TABLE IF NOT EXISTS health_mobile_sync_family_cursors (
+  id TEXT PRIMARY KEY,
+  pairing_session_id TEXT NOT NULL REFERENCES companion_pairing_sessions(id) ON DELETE CASCADE,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  family TEXT NOT NULL,
+  cursor_json TEXT NOT NULL DEFAULT '{}',
+  updated_at TEXT NOT NULL,
+  UNIQUE(pairing_session_id, family)
+);

package/dist/server/server/src/app.js

@@ -66,7 +66,7 @@ import { registerWebRoutes } from "./web.js";
 import { createManagerRuntime } from "./managers/runtime.js";
 import { isManagerError } from "./managers/type-guards.js";
 import { buildCompanionPairingTransport, getCompanionIrohStatus, stopCompanionIroh } from "./services/companion-iroh.js";
-import { createCompanionPairingSession, createCompanionPairingSessionSchema, createSleepSession, createSleepSessionSchema, createWorkoutSession, createWorkoutSessionSchema, deleteSleepSession, deleteWorkoutSession, getCompanionPairingSessionById, getCompanionOverview, getFitnessViewData, getSleepSessionById, getSleepSessionDetailById, getSleepTimelineOverlaysForRange, getSleepViewData, getVitalsViewData, getHealthZoneProfileForUser, getWorkoutSessionById, getWorkoutSessionDetailById, heartbeatCompanionPairing, heartbeatCompanionPairingSchema, healthZoneProfilePatchSchema, ingestMobileHealthSync, mobileHealthSyncSchema, patchHealthZoneProfileForUser, patchCompanionPairingSourceState, patchCompanionPairingSourceStateSchema, companionSourceKeySchema, requireValidPairing, revokeAllCompanionPairingSessions, revokeAllCompanionPairingSessionsSchema, revokeCompanionPairingSession, updateMobileCompanionSourceState, updateMobileCompanionSourceStateSchema, verifyCompanionPairing, verifyCompanionPairingSchema, updateSleepMetadata, updateSleepMetadataSchema, updateWorkoutMetadata, updateWorkoutMetadataSchema } from "./health.js";
+import { createCompanionPairingSession, createCompanionPairingSessionSchema, createSleepSession, createSleepSessionSchema, createWorkoutSession, createWorkoutSessionSchema, deleteSleepSession, deleteWorkoutSession, getCompanionPairingSessionById, getCompanionOverview, getFitnessViewData, getSleepSessionById, getSleepSessionDetailById, getSleepTimelineOverlaysForRange, getSleepViewData, getVitalsViewData, getHealthZoneProfileForUser, getWorkoutSessionById, getWorkoutSessionDetailById, heartbeatCompanionPairing, heartbeatCompanionPairingSchema, healthZoneProfilePatchSchema, abortMobileHealthSyncSession, completeMobileHealthSyncSession, ingestMobileHealthSync, ingestMobileHealthSyncChunk, mobileHealthSyncChunkSchema, mobileHealthSyncSessionCompleteSchema, mobileHealthSyncSessionStartSchema, mobileHealthSyncSchema, patchHealthZoneProfileForUser, patchCompanionPairingSourceState, patchCompanionPairingSourceStateSchema, companionSourceKeySchema, requireValidPairing, startMobileHealthSyncSession, revokeAllCompanionPairingSessions, revokeAllCompanionPairingSessionsSchema, revokeCompanionPairingSession, updateMobileCompanionSourceState, updateMobileCompanionSourceStateSchema, verifyCompanionPairing, verifyCompanionPairingSchema, updateSleepMetadata, updateSleepMetadataSchema, updateWorkoutMetadata, updateWorkoutMetadataSchema } from "./health.js";
 import { analyzeMovementUserBoxPreflight, createMovementUserBox, createMovementPlace, deleteMovementUserBox, getMovementAllTimeSummary, getMovementBoxDetail, getMovementDayDetail, getMovementMobileBootstrap, getMovementTimeline, getMovementSelectionAggregate, getMovementSettings, getMovementTripDetail, getMovementMonthSummary, invalidateAutomaticMovementBox, listMovementPlaces, movementAutomaticBoxInvalidateSchema, movementMobileBootstrapSchema, movementMobilePlaceMutationSchema, movementMobileStayPatchSchema, movementMobileUserBoxCreateSchema, movementMobileUserBoxPreflightSchema, movementMobileUserBoxPatchSchema, movementMobileAutomaticBoxInvalidateSchema, movementMobileTimelineSchema, movementPlaceMutationSchema, movementPlacePatchSchema, movementSelectionAggregateSchema, movementStayPatchSchema, movementTripPatchSchema, movementUserBoxCreateSchema, movementUserBoxPreflightSchema, movementUserBoxPatchSchema, movementSettingsPatchSchema, movementTimelineQuerySchema, movementTripPointPatchSchema, deleteMovementStay, deleteMovementTrip, deleteMovementTripPoint, updateMovementPlace, updateMovementSettings, updateMovementStay, updateMovementTrip, updateMovementUserBox, updateMovementTripPoint, resolveMovementTimelineSegmentForBox } from "./movement.js";
 import { getScreenTimeAllTimeSummary, getScreenTimeDayDetail, getScreenTimeMonthSummary, getScreenTimeSettings, screenTimeSettingsPatchSchema, updateScreenTimeSettings } from "./screen-time.js";
 import { assertWatchReady, buildWatchBootstrap, ingestWatchCaptureBatch, mobileWatchBootstrapSchema, mobileWatchCaptureBatchSchema, mobileWatchHabitCheckInSchema } from "./watch-mobile.js";
@@ -2969,6 +2969,18 @@ const AGENT_ONBOARDING_ENTITY_CONVERSATION_PLAYBOOKS = [
             "Ask about source or override reason only when that context matters."
         ]
     },
+    {
+        focus: "calendar_overview",
+        openingQuestion: "What are you trying to understand or decide from your calendar picture?",
+        coachingGoal: "Review commitments, work blocks, provider state, and existing timeboxes before creating or changing calendar records.",
+        askSequence: [
+            "Ask what practical calendar question the user wants the overview to answer.",
+            "Ask which day, week, date range, or owner scope matters only if it changes the read.",
+            "Use forge_get_calendar_overview before asking the user to reconstruct availability from memory.",
+            "Reflect the scheduling or planning decision the user is trying to make.",
+            "Move to calendar_event, work_block_template, task_timebox, or calendar_connection only when one concrete follow-up action is visible."
+        ]
+    },
     {
         focus: "calendar_connection",
         openingQuestion: "Which calendar provider are you trying to connect, and what do you want Forge to do with it?",
@@ -3004,6 +3016,29 @@ const AGENT_ONBOARDING_ENTITY_CONVERSATION_PLAYBOOKS = [
             "Ask for a short audit note only if the reason would otherwise be unclear later."
         ]
     },
+    {
+        focus: "operator_overview",
+        openingQuestion: "What are you trying to understand about Forge overall right now?",
+        coachingGoal: "Read the broad Forge state before choosing a specific entity action.",
+        askSequence: [
+            "Ask what broad Forge question the user wants the overview to answer.",
+            "Ask which owner or user scope matters only if several humans or bots are in play.",
+            "Use forge_get_operator_overview before reopening a create or update intake.",
+            "Reflect the attention cue, priority, or handoff decision the overview should support.",
+            "Move into a specific entity flow only when the overview points to a concrete goal, project, task, habit, note, Psyche record, or action."
+        ]
+    },
+    {
+        focus: "operator_context",
+        openingQuestion: "What current work, risk, or next move are you trying to check?",
+        coachingGoal: "Inspect current work, active runs, risk, and next moves before changing records.",
+        askSequence: [
+            "Ask whether the user is checking current work, risk, blockers, active sessions, or the next move.",
+            "Use forge_get_operator_context before mutating tasks, projects, runs, or notes when the current state is uncertain.",
+            "Reflect whether the read is meant to decide continue, stop, reprioritize, update, or create.",
+            "Move to task_run, work_adjustment, task, project, or note flow only when one concrete follow-up is visible."
+        ]
+    },
     {
         focus: "self_observation",
         openingQuestion: "What happened in the situation, and what did you feel, think, or do next?",
@@ -4592,7 +4627,8 @@ function buildAgentOnboardingPayload(request) {
                 calendar_overview: "/api/v1/calendar/overview",
                 operatorOverview: "/api/v1/operator/overview",
                 operator_overview: "/api/v1/operator/overview",
-                operatorContext: "/api/v1/operator/context"
+                operatorContext: "/api/v1/operator/context",
+                operator_context: "/api/v1/operator/context"
             }
         },
         multiUserModel: {
@@ -6355,6 +6391,8 @@ export async function buildServer(options = {}) {
     app.setErrorHandler((error, request, reply) => {
         const validationIssues = error instanceof ZodError ? formatValidationIssues(error) : undefined;
         const routeUrl = request.routeOptions.url || request.url;
+        const isBodyTooLarge = typeof error.code === "string" &&
+            error.code === "FST_ERR_CTP_BODY_TOO_LARGE";
         const validationHelp = validationIssues
             ? buildValidationHelp(request.method, routeUrl, validationIssues)
             : undefined;
@@ -6364,20 +6402,24 @@ export async function buildServer(options = {}) {
                 ? error.statusCode
                 : error instanceof ZodError
                     ? 400
-                    : 500;
+                    : isBodyTooLarge
+                        ? 413
+                        : 500;
         if (!shouldSkipAutomaticDiagnosticRoute(routeUrl)) {
             try {
                 recordDiagnosticLog({
                     level: statusCode >= 500 ? "error" : "warning",
                     source: normalizeDiagnosticSource(request.headers["x-forge-source"]),
                     scope: "api_error",
-                    eventKey: isHttpError(error)
-                        ? error.code
-                        : isManagerError(error)
+                    eventKey: isBodyTooLarge
+                        ? "payload_too_large"
+                        : isHttpError(error)
                             ? error.code
-                            : statusCode === 400
-                                ? "invalid_request"
-                                : "internal_error",
+                            : isManagerError(error)
+                                ? error.code
+                                : statusCode === 400
+                                    ? "invalid_request"
+                                    : "internal_error",
                     message: getErrorMessage(error),
                     route: routeUrl,
                     functionName: "setErrorHandler",
@@ -6401,13 +6443,25 @@ export async function buildServer(options = {}) {
                 ? error.code
                 : isManagerError(error)
                     ? error.code
-                    : statusCode === 400
-                        ? "invalid_request"
-                        : "internal_error",
+                    : isBodyTooLarge
+                        ? "payload_too_large"
+                        : statusCode === 400
+                            ? "invalid_request"
+                            : "internal_error",
             error: validationIssues
                 ? `Request validation failed for ${request.method.toUpperCase()} ${routeUrl}. ${validationHelp?.validationSummary ?? ""}`.trim()
-                : getErrorMessage(error),
+                : isBodyTooLarge
+                    ? "The request body is too large. Use chunked HealthKit sync."
+                    : getErrorMessage(error),
             statusCode,
+            ...(isBodyTooLarge
+                ? {
+                    recommendedMode: "chunked",
+                    maxBytes: typeof request.routeOptions.bodyLimit === "number"
+                        ? request.routeOptions.bodyLimit
+                        : undefined
+                }
+                : {}),
             ...(validationIssues ? { details: validationIssues } : {}),
             ...(validationHelp ?? {}),
             ...(isHttpError(error) && error.details ? error.details : {}),
@@ -7343,7 +7397,27 @@ export async function buildServer(options = {}) {
             watch: buildWatchBootstrap(pairing)
         };
     });
-    app.post("/api/v1/mobile/healthkit/sync", async (request) => ({
+    app.post("/api/v1/mobile/healthkit/sync-sessions", async (request) => ({
+        upload: startMobileHealthSyncSession(mobileHealthSyncSessionStartSchema.parse(request.body ?? {}))
+    }));
+    app.post("/api/v1/mobile/healthkit/sync-sessions/:id/chunks", { bodyLimit: 1_250_000 }, async (request) => {
+        const { id } = request.params;
+        const rawPayloadJson = JSON.stringify((request.body ?? {}).payload ?? {});
+        return {
+            chunk: ingestMobileHealthSyncChunk(id, mobileHealthSyncChunkSchema.parse(request.body ?? {}), rawPayloadJson)
+        };
+    });
+    app.post("/api/v1/mobile/healthkit/sync-sessions/:id/complete", async (request) => {
+        const { id } = request.params;
+        return {
+            sync: completeMobileHealthSyncSession(id, mobileHealthSyncSessionCompleteSchema.parse(request.body ?? {}))
+        };
+    });
+    app.delete("/api/v1/mobile/healthkit/sync-sessions/:id", async (request) => {
+        const { id } = request.params;
+        return { upload: abortMobileHealthSyncSession(id) };
+    });
+    app.post("/api/v1/mobile/healthkit/sync", { bodyLimit: 8_000_000 }, async (request) => ({
         sync: ingestMobileHealthSync(mobileHealthSyncSchema.parse(request.body ?? {}))
     }));
     app.patch("/api/v1/health/workouts/:id", async (request, reply) => {

package/dist/server/server/src/health.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { z } from "zod";
 import { getDatabase, runInTransaction } from "./db.js";
 import { HttpError } from "./errors.js";
@@ -259,6 +259,92 @@ export const mobileHealthSyncSchema = z.object({
     movement: movementSyncPayloadSchema.default({}),
     screenTime: screenTimeSyncPayloadSchema.default({})
 });
+const HEALTH_MOBILE_SYNC_SCHEMA_VERSION = "healthkit-sync-v2";
+const HEALTH_MOBILE_SYNC_CHUNK_TARGET_BYTES = 512_000;
+const HEALTH_MOBILE_SYNC_CHUNK_MAX_BYTES = 1_000_000;
+const HEALTH_MOBILE_SYNC_SESSION_TTL_MS = 1000 * 60 * 60 * 24;
+const mobileHealthSyncFamilySchema = z.enum([
+    "sleep_nights",
+    "sleep_segments",
+    "sleep_raw_records",
+    "workout_summaries",
+    "workout_time_series",
+    "workout_routes",
+    "workout_tombstones",
+    "vitals",
+    "movement",
+    "screen_time"
+]);
+const defaultMobileHealthSyncFamilies = mobileHealthSyncFamilySchema.options;
+export const mobileHealthSyncSessionStartSchema = mobileHealthSyncSchema
+    .pick({
+    sessionId: true,
+    pairingToken: true,
+    device: true,
+    permissions: true,
+    sourceStates: true
+})
+    .extend({
+    schemaVersion: z
+        .string()
+        .trim()
+        .default(HEALTH_MOBILE_SYNC_SCHEMA_VERSION),
+    requestedFamilies: z
+        .array(mobileHealthSyncFamilySchema)
+        .default(defaultMobileHealthSyncFamilies),
+    expectedCounts: z.record(z.string(), z.number().int().nonnegative()).default({}),
+    metadata: z.record(z.string(), z.unknown()).default({})
+});
+const workoutTimeSeriesChunkPayloadSchema = z.object({
+    workouts: z
+        .array(z.object({
+        externalUid: z.string().trim().min(1),
+        samples: z.array(workoutTimeSeriesSampleSchema).default([])
+    }))
+        .default([])
+});
+const workoutRouteChunkPayloadSchema = z.object({
+    workouts: z
+        .array(z.object({
+        externalUid: z.string().trim().min(1),
+        routePoints: z.array(workoutRoutePointSchema).default([])
+    }))
+        .default([])
+});
+const workoutTombstoneChunkPayloadSchema = z.object({
+    workouts: z
+        .array(z.object({
+        externalUid: z.string().trim().min(1),
+        deletedAt: z.string().datetime().nullable().optional(),
+        reason: z.string().trim().default("healthkit_deleted")
+    }))
+        .default([])
+});
+const mobileHealthSyncChunkPayloadSchema = z.object({
+    sleepNights: mobileHealthSyncSchema.shape.sleepNights.optional(),
+    sleepSegments: mobileHealthSyncSchema.shape.sleepSegments.optional(),
+    sleepRawRecords: mobileHealthSyncSchema.shape.sleepRawRecords.optional(),
+    workouts: mobileHealthSyncSchema.shape.workouts.optional(),
+    workoutTimeSeries: workoutTimeSeriesChunkPayloadSchema.shape.workouts.optional(),
+    workoutRoutes: workoutRouteChunkPayloadSchema.shape.workouts.optional(),
+    workoutTombstones: workoutTombstoneChunkPayloadSchema.shape.workouts.optional(),
+    vitals: vitalsSyncPayloadSchema.optional(),
+    movement: movementSyncPayloadSchema.optional(),
+    screenTime: screenTimeSyncPayloadSchema.optional()
+});
+export const mobileHealthSyncChunkSchema = z.object({
+    chunkId: z.string().trim().min(1),
+    sequence: z.number().int().nonnegative(),
+    family: mobileHealthSyncFamilySchema,
+    recordCount: z.number().int().nonnegative().default(0),
+    byteCount: z.number().int().nonnegative().default(0),
+    checksumSha256: z.string().trim().min(1),
+    payload: mobileHealthSyncChunkPayloadSchema.default({})
+});
+export const mobileHealthSyncSessionCompleteSchema = z.object({
+    finalCursor: z.record(z.string(), z.unknown()).default({}),
+    expectedCounts: z.record(z.string(), z.number().int().nonnegative()).default({})
+});
 export const verifyCompanionPairingSchema = z.object({
     sessionId: z.string().trim().min(1),
     pairingToken: z.string().trim().min(1),
@@ -2562,6 +2648,415 @@ function replaceHistoricalSleepSessionsForDate(userId, localDateKey, providerBac
             .run(historical.id);
     }
 }
+function mobileSyncSessionId() {
+    return `hms_${randomUUID().replaceAll("-", "").slice(0, 12)}`;
+}
+function mobileSyncChunkRecordId() {
+    return `hmsc_${randomUUID().replaceAll("-", "").slice(0, 12)}`;
+}
+function expireStaleMobileSyncSessions() {
+    const cutoff = new Date(Date.now() - HEALTH_MOBILE_SYNC_SESSION_TTL_MS).toISOString();
+    const now = nowIso();
+    getDatabase()
+        .prepare(`UPDATE health_mobile_sync_sessions
+       SET status = 'expired', expired_at = ?, updated_at = ?
+       WHERE status = 'running' AND started_at < ?`)
+        .run(now, now, cutoff);
+}
+function readMobileSyncSession(syncSessionId) {
+    return getDatabase()
+        .prepare(`SELECT * FROM health_mobile_sync_sessions WHERE id = ?`)
+        .get(syncSessionId);
+}
+function ensureRunningMobileSyncSession(syncSessionId) {
+    expireStaleMobileSyncSessions();
+    const session = readMobileSyncSession(syncSessionId);
+    if (!session) {
+        throw new HttpError(404, "sync_session_not_found", "The HealthKit sync session does not exist.");
+    }
+    if (session.status !== "running") {
+        throw new HttpError(409, "sync_session_closed", "The HealthKit sync session is no longer accepting chunks.", { status: session.status });
+    }
+    return session;
+}
+function chunkPayloadJson(payload) {
+    return JSON.stringify(payload);
+}
+function chunkPayloadChecksum(payloadJson) {
+    return createHash("sha256").update(payloadJson).digest("hex");
+}
+function summarizeChunkPayload(family, payload) {
+    switch (family) {
+        case "sleep_nights":
+            return { sleepNights: payload.sleepNights?.length ?? 0 };
+        case "sleep_segments":
+            return { sleepSegments: payload.sleepSegments?.length ?? 0 };
+        case "sleep_raw_records":
+            return { sleepRawRecords: payload.sleepRawRecords?.length ?? 0 };
+        case "workout_summaries":
+            return { workouts: payload.workouts?.length ?? 0 };
+        case "workout_time_series":
+            return {
+                workouts: payload.workoutTimeSeries?.length ?? 0,
+                samples: payload.workoutTimeSeries?.reduce((sum, entry) => sum + entry.samples.length, 0) ?? 0
+            };
+        case "workout_routes":
+            return {
+                workouts: payload.workoutRoutes?.length ?? 0,
+                routePoints: payload.workoutRoutes?.reduce((sum, entry) => sum + entry.routePoints.length, 0) ?? 0
+            };
+        case "workout_tombstones":
+            return { workouts: payload.workoutTombstones?.length ?? 0 };
+        case "vitals":
+            return { daySummaries: payload.vitals?.daySummaries.length ?? 0 };
+        case "movement":
+            return {
+                stays: payload.movement?.stays.length ?? 0,
+                trips: payload.movement?.trips.length ?? 0
+            };
+        case "screen_time":
+            return {
+                daySummaries: payload.screenTime?.daySummaries.length ?? 0,
+                hourlySegments: payload.screenTime?.hourlySegments.length ?? 0
+            };
+    }
+}
+function updateMobileSyncSessionProgress(syncSessionId) {
+    const chunks = getDatabase()
+        .prepare(`SELECT family, record_count, byte_count
+       FROM health_mobile_sync_chunks
+       WHERE sync_session_id = ?`)
+        .all(syncSessionId);
+    const receivedCounts = {};
+    const byteTotals = {};
+    for (const chunk of chunks) {
+        receivedCounts[chunk.family] =
+            (receivedCounts[chunk.family] ?? 0) + chunk.record_count;
+        byteTotals[chunk.family] =
+            (byteTotals[chunk.family] ?? 0) + chunk.byte_count;
+    }
+    getDatabase()
+        .prepare(`UPDATE health_mobile_sync_sessions
+       SET received_counts_json = ?, byte_totals_json = ?, updated_at = ?
+       WHERE id = ?`)
+        .run(JSON.stringify(receivedCounts), JSON.stringify(byteTotals), nowIso(), syncSessionId);
+    return {
+        receivedCounts,
+        byteTotals,
+        chunkCount: chunks.length,
+        receivedBytes: chunks.reduce((sum, chunk) => sum + chunk.byte_count, 0)
+    };
+}
+export function startMobileHealthSyncSession(payload) {
+    const parsed = mobileHealthSyncSessionStartSchema.parse(payload);
+    if (parsed.schemaVersion !== HEALTH_MOBILE_SYNC_SCHEMA_VERSION) {
+        throw new HttpError(409, "schema_version_unsupported", "The companion HealthKit sync protocol is not supported by this Forge runtime.", {
+            schemaVersion: HEALTH_MOBILE_SYNC_SCHEMA_VERSION,
+            requestedSchemaVersion: parsed.schemaVersion
+        });
+    }
+    expireStaleMobileSyncSessions();
+    const pairing = requireValidPairing(parsed.sessionId, parsed.pairingToken);
+    const resumeSyncSessionId = typeof parsed.metadata.resumeSyncSessionId === "string"
+        ? parsed.metadata.resumeSyncSessionId.trim()
+        : "";
+    if (resumeSyncSessionId.length > 0) {
+        const existing = readMobileSyncSession(resumeSyncSessionId);
+        if (existing &&
+            existing.pairing_session_id === pairing.id &&
+            existing.status === "running") {
+            const receivedChunkIds = getDatabase()
+                .prepare(`SELECT chunk_id
+           FROM health_mobile_sync_chunks
+           WHERE sync_session_id = ?
+           ORDER BY sequence ASC`)
+                .all(resumeSyncSessionId)
+                .map((row) => row.chunk_id);
+            return {
+                syncSessionId: resumeSyncSessionId,
+                schemaVersion: HEALTH_MOBILE_SYNC_SCHEMA_VERSION,
+                chunkTargetBytes: HEALTH_MOBILE_SYNC_CHUNK_TARGET_BYTES,
+                chunkMaxBytes: HEALTH_MOBILE_SYNC_CHUNK_MAX_BYTES,
+                supportsCompression: false,
+                acceptedFamilies: safeJsonParse(existing.requested_families_json, parsed.requestedFamilies),
+                receivedChunkIds
+            };
+        }
+    }
+    const now = nowIso();
+    const syncSessionId = mobileSyncSessionId();
+    getDatabase()
+        .prepare(`INSERT INTO health_mobile_sync_sessions (
+         id, pairing_session_id, user_id, status, schema_version,
+         requested_families_json, source_metadata_json, expected_counts_json,
+         received_counts_json, byte_totals_json, started_at, created_at, updated_at
+       )
+       VALUES (?, ?, ?, 'running', ?, ?, ?, ?, '{}', '{}', ?, ?, ?)`)
+        .run(syncSessionId, pairing.id, pairing.user_id, HEALTH_MOBILE_SYNC_SCHEMA_VERSION, JSON.stringify(parsed.requestedFamilies), JSON.stringify({
+        sessionId: parsed.sessionId,
+        device: parsed.device,
+        permissions: parsed.permissions,
+        sourceStates: parsed.sourceStates,
+        metadata: parsed.metadata
+    }), JSON.stringify(parsed.expectedCounts), now, now, now);
+    return {
+        syncSessionId,
+        schemaVersion: HEALTH_MOBILE_SYNC_SCHEMA_VERSION,
+        chunkTargetBytes: HEALTH_MOBILE_SYNC_CHUNK_TARGET_BYTES,
+        chunkMaxBytes: HEALTH_MOBILE_SYNC_CHUNK_MAX_BYTES,
+        supportsCompression: false,
+        acceptedFamilies: parsed.requestedFamilies,
+        receivedChunkIds: []
+    };
+}
+export function ingestMobileHealthSyncChunk(syncSessionId, payload, rawPayloadJson) {
+    const parsed = mobileHealthSyncChunkSchema.parse(payload);
+    const session = ensureRunningMobileSyncSession(syncSessionId);
+    const requestedFamilies = safeJsonParse(session.requested_families_json, []);
+    if (requestedFamilies.length > 0 &&
+        !requestedFamilies.includes(parsed.family)) {
+        throw new HttpError(400, "unsupported_family", "This sync session did not request that HealthKit family.", { family: parsed.family });
+    }
+    const existing = getDatabase()
+        .prepare(`SELECT * FROM health_mobile_sync_chunks
+       WHERE sync_session_id = ? AND chunk_id = ?`)
+        .get(syncSessionId, parsed.chunkId);
+    if (existing) {
+        if (existing.checksum_sha256 !== parsed.checksumSha256) {
+            throw new HttpError(409, "chunk_checksum_mismatch", "A chunk with the same id was already accepted with different content.");
+        }
+        const progress = updateMobileSyncSessionProgress(syncSessionId);
+        return {
+            accepted: true,
+            duplicate: true,
+            receivedCount: progress.chunkCount,
+            receivedBytes: progress.receivedBytes,
+            progress
+        };
+    }
+    const payloadJson = chunkPayloadJson(parsed.payload);
+    const checksumPayloadJson = rawPayloadJson ?? payloadJson;
+    const actualByteCount = Buffer.byteLength(checksumPayloadJson, "utf8");
+    if (actualByteCount > HEALTH_MOBILE_SYNC_CHUNK_MAX_BYTES) {
+        throw new HttpError(413, "chunk_too_large", "The HealthKit sync chunk is too large.", {
+            maxBytes: HEALTH_MOBILE_SYNC_CHUNK_MAX_BYTES,
+            actualBytes: actualByteCount
+        });
+    }
+    const serverChecksum = chunkPayloadChecksum(checksumPayloadJson);
+    if (parsed.checksumSha256 !== serverChecksum) {
+        throw new HttpError(409, "chunk_checksum_mismatch", "The HealthKit sync chunk checksum does not match its payload.", { actualBytes: actualByteCount });
+    }
+    const now = nowIso();
+    getDatabase()
+        .prepare(`INSERT INTO health_mobile_sync_chunks (
+         id, sync_session_id, chunk_id, sequence, family, checksum_sha256,
+         record_count, byte_count, payload_json, payload_summary_json,
+         received_at, applied_at, created_at, updated_at
+       )
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+        .run(mobileSyncChunkRecordId(), syncSessionId, parsed.chunkId, parsed.sequence, parsed.family, serverChecksum, parsed.recordCount, parsed.byteCount || actualByteCount, payloadJson, JSON.stringify({
+        ...summarizeChunkPayload(parsed.family, parsed.payload),
+        clientByteCount: parsed.byteCount,
+        actualByteCount,
+        serverChecksum
+    }), now, now, now, now);
+    const progress = updateMobileSyncSessionProgress(syncSessionId);
+    return {
+        accepted: true,
+        duplicate: false,
+        receivedCount: progress.chunkCount,
+        receivedBytes: progress.receivedBytes,
+        progress
+    };
+}
+function mergeMobileHealthSyncChunks(session, chunks) {
+    const pairing = getDatabase()
+        .prepare(`SELECT * FROM companion_pairing_sessions WHERE id = ?`)
+        .get(session.pairing_session_id);
+    if (!pairing) {
+        throw new HttpError(404, "pairing_invalid", "The sync pairing no longer exists.");
+    }
+    const metadata = safeJsonParse(session.source_metadata_json, {});
+    const assembled = mobileHealthSyncSchema.parse({
+        sessionId: metadata.sessionId ?? pairing.id,
+        pairingToken: pairing.pairing_token,
+        device: metadata.device ??
+            {
+                name: pairing.device_name ?? "iPhone",
+                platform: pairing.platform ?? "ios",
+                appVersion: pairing.app_version ?? "",
+                sourceDevice: pairing.device_name ?? "iPhone"
+            },
+        permissions: metadata.permissions ??
+            {
+                healthKitAuthorized: false,
+                backgroundRefreshEnabled: false,
+                motionReady: false,
+                locationReady: false,
+                screenTimeReady: false
+            },
+        sourceStates: metadata.sourceStates,
+        sleepSessions: [],
+        sleepNights: [],
+        sleepSegments: [],
+        sleepRawRecords: [],
+        workouts: [],
+        vitals: { daySummaries: [] },
+        movement: {},
+        screenTime: {}
+    });
+    const workoutsByExternalUid = new Map();
+    const tombstones = [];
+    for (const chunk of chunks.sort((left, right) => left.sequence - right.sequence)) {
+        const payload = mobileHealthSyncChunkPayloadSchema.parse(safeJsonParse(chunk.payload_json, {}));
+        if (payload.sleepNights) {
+            assembled.sleepNights.push(...payload.sleepNights);
+        }
+        if (payload.sleepSegments) {
+            assembled.sleepSegments.push(...payload.sleepSegments);
+        }
+        if (payload.sleepRawRecords) {
+            assembled.sleepRawRecords.push(...payload.sleepRawRecords);
+        }
+        if (payload.workouts) {
+            for (const workout of payload.workouts) {
+                const previous = workoutsByExternalUid.get(workout.externalUid);
+                workoutsByExternalUid.set(workout.externalUid, {
+                    ...(previous ?? workout),
+                    ...workout,
+                    timeSeriesSamples: [
+                        ...(previous?.timeSeriesSamples ?? []),
+                        ...workout.timeSeriesSamples
+                    ],
+                    routePoints: [
+                        ...(previous?.routePoints ?? []),
+                        ...workout.routePoints
+                    ]
+                });
+            }
+        }
+        if (payload.workoutTimeSeries) {
+            for (const entry of payload.workoutTimeSeries) {
+                const workout = workoutsByExternalUid.get(entry.externalUid);
+                if (!workout) {
+                    throw new HttpError(409, "missing_required_chunks", "A workout time-series chunk arrived without a matching workout summary.", { workoutExternalUid: entry.externalUid });
+                }
+                workout.timeSeriesSamples.push(...entry.samples);
+            }
+        }
+        if (payload.workoutRoutes) {
+            for (const entry of payload.workoutRoutes) {
+                const workout = workoutsByExternalUid.get(entry.externalUid);
+                if (!workout) {
+                    throw new HttpError(409, "missing_required_chunks", "A workout route chunk arrived without a matching workout summary.", { workoutExternalUid: entry.externalUid });
+                }
+                workout.routePoints.push(...entry.routePoints);
+            }
+        }
+        if (payload.workoutTombstones) {
+            tombstones.push(...payload.workoutTombstones);
+        }
+        if (payload.vitals) {
+            assembled.vitals.daySummaries.push(...payload.vitals.daySummaries);
+        }
+        if (payload.movement) {
+            assembled.movement.settings = payload.movement.settings;
+            assembled.movement.knownPlaces.push(...payload.movement.knownPlaces);
+            assembled.movement.stays.push(...payload.movement.stays);
+            assembled.movement.trips.push(...payload.movement.trips);
+        }
+        if (payload.screenTime) {
+            assembled.screenTime.settings = payload.screenTime.settings;
+            assembled.screenTime.daySummaries.push(...payload.screenTime.daySummaries);
+            assembled.screenTime.hourlySegments.push(...payload.screenTime.hourlySegments);
+        }
+    }
+    assembled.workouts = [...workoutsByExternalUid.values()].sort((left, right) => right.startedAt.localeCompare(left.startedAt));
+    return { assembled, tombstones };
+}
+function applyWorkoutTombstones(pairing, tombstones) {
+    if (tombstones.length === 0) {
+        return 0;
+    }
+    const deleteStmt = getDatabase().prepare(`DELETE FROM health_workout_sessions
+     WHERE user_id = ? AND source = 'apple_health' AND external_uid = ?`);
+    let deleted = 0;
+    for (const tombstone of tombstones) {
+        const result = deleteStmt.run(pairing.user_id, tombstone.externalUid);
+        deleted += Number(result.changes ?? 0);
+    }
+    return deleted;
+}
+function upsertMobileSyncFamilyCursors(pairing, finalCursor) {
+    const now = nowIso();
+    const stmt = getDatabase().prepare(`INSERT INTO health_mobile_sync_family_cursors (
+       id, pairing_session_id, user_id, family, cursor_json, updated_at
+     )
+     VALUES (?, ?, ?, ?, ?, ?)
+     ON CONFLICT(pairing_session_id, family)
+     DO UPDATE SET cursor_json = excluded.cursor_json, updated_at = excluded.updated_at`);
+    for (const [family, cursor] of Object.entries(finalCursor)) {
+        stmt.run(`hmscur_${randomUUID().replaceAll("-", "").slice(0, 10)}`, pairing.id, pairing.user_id, family, JSON.stringify(cursor), now);
+    }
+}
+export function completeMobileHealthSyncSession(syncSessionId, payload) {
+    const parsed = mobileHealthSyncSessionCompleteSchema.parse(payload);
+    const session = ensureRunningMobileSyncSession(syncSessionId);
+    const chunks = getDatabase()
+        .prepare(`SELECT * FROM health_mobile_sync_chunks
+       WHERE sync_session_id = ?
+       ORDER BY sequence ASC`)
+        .all(syncSessionId);
+    if (chunks.length === 0) {
+        throw new HttpError(409, "missing_required_chunks", "The HealthKit sync session has no accepted chunks.");
+    }
+    const pairing = getDatabase()
+        .prepare(`SELECT * FROM companion_pairing_sessions WHERE id = ?`)
+        .get(session.pairing_session_id);
+    try {
+        const { assembled, tombstones } = mergeMobileHealthSyncChunks(session, chunks);
+        const sync = ingestMobileHealthSync(assembled);
+        const deletedWorkoutCount = applyWorkoutTombstones(pairing, tombstones);
+        upsertMobileSyncFamilyCursors(pairing, parsed.finalCursor);
+        const now = nowIso();
+        getDatabase()
+            .prepare(`UPDATE health_mobile_sync_sessions
+         SET status = 'completed', expected_counts_json = ?, completed_at = ?,
+             updated_at = ?
+         WHERE id = ?`)
+            .run(JSON.stringify(parsed.expectedCounts), now, now, syncSessionId);
+        return {
+            ...sync,
+            upload: {
+                syncSessionId,
+                chunks: chunks.length,
+                deletedWorkoutCount
+            }
+        };
+    }
+    catch (error) {
+        const now = nowIso();
+        getDatabase()
+            .prepare(`UPDATE health_mobile_sync_sessions
+         SET status = 'failed', failed_at = ?, error_json = ?, updated_at = ?
+         WHERE id = ?`)
+            .run(now, JSON.stringify({
+            message: error instanceof Error ? error.message : String(error)
+        }), now, syncSessionId);
+        throw error;
+    }
+}
+export function abortMobileHealthSyncSession(syncSessionId) {
+    const session = ensureRunningMobileSyncSession(syncSessionId);
+    const now = nowIso();
+    getDatabase()
+        .prepare(`UPDATE health_mobile_sync_sessions
+       SET status = 'aborted', aborted_at = ?, updated_at = ?
+       WHERE id = ?`)
+        .run(now, now, session.id);
+    return { syncSessionId, status: "aborted" };
+}
 export function ingestMobileHealthSync(payload) {
     const parsed = mobileHealthSyncSchema.parse(payload);
     ensureLegacyAppleSleepHistoryRepaired();

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "forge-openclaw-plugin",
   "name": "Forge",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
-  "version": "0.2.69",
+  "version": "0.2.70",
   "activation": {
     "onStartup": true,
     "onCapabilities": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.2.69",
+  "version": "0.2.70",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
   "type": "module",
   "license": "Apache-2.0",
@@ -105,6 +105,7 @@
     "follow-redirects": "^1.16.0",
     "hono": "^4.12.18",
     "ip-address": "^10.2.0",
+    "ws": "^8.20.1",
     "uuid": "^14.0.0"
   },
   "scripts": {

package/server/migrations/062_health_mobile_sync_sessions.sql

@@ -0,0 +1,55 @@
+CREATE TABLE IF NOT EXISTS health_mobile_sync_sessions (
+  id TEXT PRIMARY KEY,
+  pairing_session_id TEXT NOT NULL REFERENCES companion_pairing_sessions(id) ON DELETE CASCADE,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  status TEXT NOT NULL DEFAULT 'running',
+  schema_version TEXT NOT NULL DEFAULT 'healthkit-sync-v2',
+  requested_families_json TEXT NOT NULL DEFAULT '[]',
+  source_metadata_json TEXT NOT NULL DEFAULT '{}',
+  expected_counts_json TEXT NOT NULL DEFAULT '{}',
+  received_counts_json TEXT NOT NULL DEFAULT '{}',
+  byte_totals_json TEXT NOT NULL DEFAULT '{}',
+  affected_workout_ids_json TEXT NOT NULL DEFAULT '[]',
+  error_json TEXT NOT NULL DEFAULT '{}',
+  started_at TEXT NOT NULL,
+  completed_at TEXT,
+  failed_at TEXT,
+  aborted_at TEXT,
+  expired_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_health_mobile_sync_sessions_pairing_status
+  ON health_mobile_sync_sessions(pairing_session_id, status, started_at DESC);
+
+CREATE TABLE IF NOT EXISTS health_mobile_sync_chunks (
+  id TEXT PRIMARY KEY,
+  sync_session_id TEXT NOT NULL REFERENCES health_mobile_sync_sessions(id) ON DELETE CASCADE,
+  chunk_id TEXT NOT NULL,
+  sequence INTEGER NOT NULL,
+  family TEXT NOT NULL,
+  checksum_sha256 TEXT NOT NULL,
+  record_count INTEGER NOT NULL DEFAULT 0,
+  byte_count INTEGER NOT NULL DEFAULT 0,
+  payload_json TEXT NOT NULL DEFAULT '{}',
+  payload_summary_json TEXT NOT NULL DEFAULT '{}',
+  received_at TEXT NOT NULL,
+  applied_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  UNIQUE(sync_session_id, chunk_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_health_mobile_sync_chunks_session_sequence
+  ON health_mobile_sync_chunks(sync_session_id, sequence);
+
+CREATE TABLE IF NOT EXISTS health_mobile_sync_family_cursors (
+  id TEXT PRIMARY KEY,
+  pairing_session_id TEXT NOT NULL REFERENCES companion_pairing_sessions(id) ON DELETE CASCADE,
+  user_id TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  family TEXT NOT NULL,
+  cursor_json TEXT NOT NULL DEFAULT '{}',
+  updated_at TEXT NOT NULL,
+  UNIQUE(pairing_session_id, family)
+);

package/skills/forge-openclaw/SKILL.md

@@ -185,11 +185,16 @@ Health rule:
 
 - Sleep and sports records are first-class health surfaces, not generic notes or tasks.
 - Use `forge_get_sleep_overview` and `forge_get_sports_overview` for review and trend reading.
-- In `forge_get_agent_onboarding.entityRouteModel.readModelOnlySurfaces`, the health
-  overview routes are published under both the plain names `sleepOverview` and
-  `sportsOverview` and the entity-style aliases `sleep_overview` and
-  `sports_overview`. Treat those as read-only overview surfaces, not batch CRUD
-  entities.
+- In `forge_get_agent_onboarding.entityRouteModel.readModelOnlySurfaces`, operator,
+  calendar, self-observation, sleep, and sports read models are published with
+  both camelCase names and entity-style aliases where useful, including
+  `operatorOverview`, `operatorContext`, `calendarOverview`, `sleepOverview`,
+  `sportsOverview`, `operator_overview`, `operator_context`,
+  `calendar_overview`, `self_observation`, `sleep_overview`, and
+  `sports_overview`. Treat those as read-only surfaces, not batch CRUD entities.
+- Use `forge_get_operator_overview` for a broad Forge status read, `forge_get_operator_context`
+  for current work and risk, and `forge_get_calendar_overview` before calendar-aware
+  planning or scheduling mutations.
 - Use the shared batch entity tools for ordinary `sleep_session` and `workout_session` create, update, delete, and search work. Do not force agents into a large one-route-per-entity mental model when the batch routes already cover the record cleanly.
 - Use `forge_update_sleep_session` and `forge_update_workout_session` only when the job is reflective enrichment on one existing health record after review, such as attaching notes, tags, mood, meaning, or Forge links.
 - Habit-generated workouts and imported HealthKit workouts belong to the same workout record model, so do not invent a separate storage path for sport sessions.

package/skills/forge-openclaw/entity_conversation_playbooks.md

@@ -237,10 +237,11 @@ Use this quick split before the conversation gets too detailed.
   `preference_signal`, and `self_observation` are action workflows. Start from what
   the user is trying to do, then use the dedicated action tool or note-backed write
   model.
-- `sleep_overview` and `sports_overview` are read-model-only surfaces. Use them when
-  the user wants to review nights, workouts, training load, recovery context, or
-  health patterns before deciding whether one stored `sleep_session` or
-  `workout_session` needs enrichment.
+- `operator_overview`, `operator_context`, `calendar_overview`, `sleep_overview`,
+  and `sports_overview` are read-model-only surfaces. Use them when the user wants
+  to understand current Forge state, work risk, calendar commitments, nights,
+  workouts, training load, recovery context, or health patterns before deciding
+  whether a stored entity needs creation or enrichment.
 - Movement, Life Force, and Workbench are specialized domain areas. Use their
   dedicated route families for timelines and overlays, energy profile/templates and
   fatigue signals, and Workbench flow execution or result artifacts. When available,
@@ -282,6 +283,19 @@ still knowing the exact write/read family before it acts.
 - `calendar_connection`: specialized CRUD. Use provider discovery, connection CRUD,
   selected-calendar rediscovery, sync, and delete routes rather than batch entity
   tools.
+- `operator_overview`: read-model-only operator surface. Use
+  `forge_get_operator_overview` or `/api/v1/operator/overview` when the user wants
+  the current Forge picture, attention cues, or broad status before choosing a
+  specific entity action.
+- `operator_context`: read-model-only operator surface. Use
+  `forge_get_operator_context` or `/api/v1/operator/context` when the user wants
+  current work, active runs, risks, board context, or next moves before mutating
+  anything.
+- `calendar_overview`: read-model-only calendar surface. Use
+  `forge_get_calendar_overview` or `/api/v1/calendar/overview` when the user wants
+  mirrored events, work blocks, timeboxes, provider state, or availability before
+  creating a `calendar_event`, `work_block_template`, `task_timebox`, or
+  `calendar_connection`.
 - `task_run`: action workflow. Use task-run start, heartbeat, focus, complete, and
   release routes; never treat status changes as proof of live work.
 - `work_adjustment`: action workflow. Use the signed work-adjustment route for real
@@ -1061,6 +1075,81 @@ Preferred opening question:
 
 - "Which task or project should this time correction belong to?"
 
+## Operator Overview
+
+Aim: read the broad Forge state before choosing a specific action, without turning a
+status check into generic intake.
+
+Arc:
+
+1. Ask what the user is trying to understand about Forge overall.
+2. Read the operator overview before asking the user to reconstruct active work,
+   attention cues, or broad status from memory.
+3. Reflect the practical decision the overview should support.
+4. Move into a specific entity flow only when the overview points to a concrete goal,
+   project, task, habit, note, Psyche record, or follow-up action.
+
+Helpful follow-up lanes:
+
+- whether the user wants a broad status read, a priority decision, or a handoff
+- which owner or user scope matters if several humans or bots are involved
+- what decision the overview should help them make next
+
+Route note:
+
+- `operator_overview` is a read-model-only operator surface. Use
+  `forge_get_operator_overview` or `/api/v1/operator/overview`; do not create,
+  update, or delete `operator_overview` through batch CRUD.
+- If the read reveals a specific record that needs work, switch to that record's
+  normal route posture after the user chooses the follow-up.
+
+Ready to review when:
+
+- the broad question is clear enough
+- any owner or user scope that changes the read is clear enough
+
+Preferred opening question:
+
+- "What are you trying to understand about Forge overall right now?"
+
+## Operator Context
+
+Aim: inspect current work, active runs, risk, and next moves before changing records.
+
+Arc:
+
+1. Ask whether the user is checking current work, risk, blockers, active sessions, or
+   the next move.
+2. Read operator context before reopening a create or update intake.
+3. Reflect what the read is meant to decide: continue, stop, reprioritize, update, or
+   create.
+4. Move to task-run, work-adjustment, task, project, or note flow only when one
+   concrete follow-up is visible.
+
+Helpful follow-up lanes:
+
+- current task or active run
+- blocked or stale work
+- next move versus broad review
+- owner or user scope when bot and human work are both present
+
+Route note:
+
+- `operator_context` is a read-model-only operator surface. Use
+  `forge_get_operator_context` or `/api/v1/operator/context`; do not mutate it
+  through batch CRUD.
+- If the user decides to start, complete, release, or adjust work after the read,
+  switch to the dedicated action workflow for that operation.
+
+Ready to review when:
+
+- the current-work question is clear
+- any user or owner scope is clear enough
+
+Preferred opening question:
+
+- "What current work, risk, or next move are you trying to check?"
+
 ## Self Observation
 
 Aim: capture one observed episode in a structured chain without letting a loose note
@@ -1251,6 +1340,46 @@ Preferred opening question:
 
 - "What are you trying to understand from your workout picture right now?"
 
+## Calendar Overview
+
+Aim: review commitments, work blocks, provider state, and existing timeboxes before
+creating or changing calendar records.
+
+Arc:
+
+1. Ask what the user is trying to understand or decide from the calendar picture.
+2. Ask for the date range or owner scope only if it changes the read.
+3. Read the calendar overview before asking the user to recreate availability from
+   memory.
+4. Reflect the practical decision the overview should support.
+5. Move to `calendar_event`, `work_block_template`, `task_timebox`, or
+   `calendar_connection` only when a specific follow-up action is visible.
+
+Helpful follow-up lanes:
+
+- which day, week, or date range matters
+- whether the question is availability, conflicts, provider health, work blocks, or
+  existing timeboxes
+- what scheduling or planning decision the review should support
+
+Route note:
+
+- `calendar_overview` is a read-model-only calendar surface. Use
+  `forge_get_calendar_overview` or `/api/v1/calendar/overview`; do not create,
+  update, or delete `calendar_overview` through batch CRUD.
+- If the review reveals a concrete scheduling action, switch to the stored
+  `calendar_event`, `work_block_template`, or `task_timebox` batch route, or to the
+  specialized `calendar_connection` lifecycle route.
+
+Ready to review when:
+
+- the user's practical calendar question is clear
+- the relevant date range or owner scope is clear enough
+
+Preferred opening question:
+
+- "What are you trying to understand or decide from your calendar picture?"
+
 ## Calendar Connection
 
 Aim: connect the right provider deliberately without turning setup into a credential