incremnt 0.8.8 → 0.8.10

package/README.md

@@ -110,7 +110,7 @@ incremnt login --session-file ~/Downloads/session.json
 | `coach observations list` | Current persisted coach observations |
 | `coach observations seen --id <id>` | Mark a coach observation as seen |
 | `coach observations dismiss --id <id>` | Dismiss an observation and suppress matching follow-ups |
-| `programs create --file <file>` | Create an inactive saved program from generated-plan JSON |
+| `programs create --file <file>` | Create an inactive saved program from generated-plan JSON, including day-local supersets |
 | `programs propose --file <file>` | Submit a program proposal |
 | `programs proposals` | List proposals |
 | `programs proposal dismiss --id <id>` | Dismiss a proposal |

package/SKILL.md

@@ -26,7 +26,7 @@ Append `--dry-run` to any mutating command to preview the HTTP request as `{ dry
 
 | Command | Reversibility | Notes |
 |---|---|---|
-| `programs create --file <f>` | Reversible in iOS (created inactive) | Creates a saved inactive program from Coach-compatible generated-plan JSON. It does not activate or replace the current plan. Use `records` or `exercises history` first for canonical names. |
+| `programs create --file <f>` | Reversible in iOS (created inactive) | Creates a saved inactive program from Coach-compatible generated-plan JSON, including day-local supersets via `supersetKey`/`supersetOrder`. It does not activate or replace the current plan. Use `records` or `exercises history` first for canonical names. |
 | `programs propose --file <f>` | Reversible (proposal stays pending) | Weights omitted; iOS computes from history. Names must come from `records` or `exercises history`. |
 | `programs proposals` | Read-only lookup | Use before dismissing a proposal. |
 | `programs proposal dismiss --id <id>` | Irreversible | IDs come from `programs proposals`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "incremnt",
-  "version": "0.8.8",
+  "version": "0.8.10",
   "description": "Command-line tool for querying your incremnt strength training data",
   "license": "MIT",
   "type": "module",

package/src/contract.js

@@ -1,4 +1,4 @@
-export const contractVersion = 24;
+export const contractVersion = 26;
 
 export const capabilities = {
   readOnly: false,
@@ -56,6 +56,17 @@ export const commandSchema = [
       { name: 'session-id', type: 'string', format: 'id', required: true, description: 'Session ID' }
     ]
   },
+  {
+    command: 'external changes',
+    id: 'external-changes',
+    description: 'List pending/applied app changes created outside iOS',
+    supportsFields: true,
+    agentNotes: 'Use this after creating programs or importing sessions from CLI/MCP. Pending changes are queued for iOS to apply; applied/skipped/failed statuses come from the app acknowledgement.',
+    options: [
+      { name: 'status', type: 'string', format: 'enum', enum: ['pending', 'applied', 'skipped', 'failed', 'dismissed'], required: false, description: 'Filter by status' },
+      { name: 'limit', type: 'number', required: false, description: 'Max changes to return (default 50, max 100)' }
+    ]
+  },
   {
     command: 'programs list',
     id: 'program-list',
@@ -278,14 +289,35 @@ export const writeCommandSchema = [
   {
     command: 'programs create',
     id: 'programs-create',
-    description: 'Create a saved inactive program from a generated plan file',
+    description: 'Queue an inactive iOS program for app-side import from a generated plan file',
     usage: 'programs create --file <file>',
     dryRun: true,
-    agentNotes: 'Mutation. Creates a brand-new inactive saved program from Coach-compatible generated-plan JSON; it does not activate or replace the current plan. External assistants should draft the JSON file, then run programs create --file <path>. Use records or exercises history before drafting exercise names; do not invent unusual exercise names.',
+    agentNotes: 'Mutation. Queues a brand-new inactive iOS program for app-side import from Coach-compatible generated-plan JSON; it does not activate or replace the current plan. External assistants should draft the JSON file, then run programs create --file <path>. Use external changes to watch pending/applied/failed status. Use records or exercises history before drafting exercise names; do not invent unusual exercise names. Supersets are supported with day-local supersetKey plus supersetOrder; the service converts them to native iOS supersetGroupId fields.',
     options: [
       { name: 'file', type: 'string', format: 'path', required: true, description: 'Path to Coach-compatible generated-plan JSON file' }
     ]
   },
+  {
+    command: 'sessions import',
+    id: 'sessions-import',
+    description: 'Queue generated workout history for iOS dedupe-and-append import',
+    usage: 'sessions import --file <file>',
+    dryRun: true,
+    agentNotes: 'Mutation. File must be JSON shaped as { sessions: [...] } using the iOS export WorkoutSession shape. The app dedupes by id and session fingerprint before appending, then acknowledges the external change.',
+    options: [
+      { name: 'file', type: 'string', format: 'path', required: true, description: 'Path to JSON file with { sessions: [...] }' }
+    ]
+  },
+  {
+    command: 'external changes backfill',
+    id: 'external-changes-backfill',
+    description: 'Backfill pending external changes from older cli-agent programs stranded in hosted snapshot state',
+    usage: 'external changes backfill',
+    dryRun: true,
+    mcp: false,
+    agentNotes: 'Mutation. Operational bridge for the previous CLI-created-program implementation. Recreates pending program.create changes for snapshot programs with externalInputProvenance.source=cli-agent.',
+    options: []
+  },
   {
     command: 'programs propose',
     id: 'programs-propose',
@@ -446,31 +478,48 @@ for (const command of writeCommandSchema) {
 }
 
 export const programDraftSchema = {
-  description: 'JSON structure for programs create --file and programs propose --file. Weights are omitted — iOS calculates from history.',
+  description: 'JSON structure for programs create --file and programs propose --file. This mirrors the current iOS program shape: concrete set reps, optional warmups/notes/RIR, and day-local supersetKey groups. Rep ranges and rest overrides are not supported.',
   required: ['name', 'daysPerWeek', 'equipmentTier', 'days'],
   properties: {
     name: { type: 'string', description: 'Program name' },
     equipmentTier: { type: 'string', enum: ['fullGym', 'benchDumbbells', 'dumbbellsOnly', 'bodyweightOnly'] },
     daysPerWeek: { type: 'integer', minimum: 1, maximum: 7, description: 'Training days per week' },
+    volumeLevel: { type: 'string', enum: ['minimum', 'moderate', 'high'], description: 'Program volume label. Optional, defaults to moderate.' },
+    currentDayIndex: { type: 'integer', minimum: 0, description: 'Initial current day index. Optional, defaults to 0.' },
     trainingWeekdays: { type: 'array', items: { type: 'integer', minimum: 0, maximum: 6 }, description: 'Days of week (0=Sun). Optional.' },
-    rationale: { type: 'string', description: 'Why this program was suggested. Optional.' },
     days: {
       type: 'array',
       minItems: 1,
       items: {
-        required: ['title', 'exercises'],
+        required: ['dayLabel', 'title', 'exercises'],
         properties: {
+          dayLabel: { type: 'string', description: 'Short day label, e.g. "Day 1".' },
           title: { type: 'string', description: 'Day name, e.g. "Upper A"' },
+          subtitle: { type: 'string', description: 'Optional day subtitle.' },
           exercises: {
             type: 'array',
             minItems: 1,
             items: {
-              required: ['name', 'sets', 'reps'],
+              required: ['name', 'muscleGroup', 'sets'],
               properties: {
                 name: { type: 'string', description: 'Exercise name (use canonical names from records or exercises history)' },
-                muscleGroup: { type: 'string', description: 'e.g. "Chest", "Back". Optional.' },
-                sets: { type: 'integer', minimum: 1 },
-                reps: { type: 'integer', minimum: 1 }
+                muscleGroup: { type: 'string', description: 'e.g. "Chest", "Back".' },
+                sets: {
+                  type: 'array',
+                  minItems: 1,
+                  items: {
+                    required: ['weight', 'reps'],
+                    properties: {
+                      weight: { type: 'number', minimum: 0, description: 'Planned load. Use 0 for bodyweight or app-computed/manual adjustment later.' },
+                      reps: { type: 'integer', minimum: 1, maximum: 30 },
+                      isWarmup: { type: 'boolean', description: 'Optional warmup marker.' }
+                    }
+                  }
+                },
+                note: { type: 'string', description: 'Optional prescription note.' },
+                rir: { type: 'integer', minimum: 0, maximum: 5, description: 'Optional app-supported RIR field.' },
+                supersetKey: { type: 'string', description: 'Optional day-local label shared by 2+ exercises to create a native iOS superset.' },
+                supersetOrder: { type: 'integer', minimum: 0, maximum: 24, description: 'Required when supersetKey is present; order within that superset group.' }
               }
             }
           }
@@ -484,7 +533,26 @@ export const proposalSchema = programDraftSchema;
 
 export const writePayloadSchemas = {
   'programs-create': programDraftSchema,
-  'programs-propose': programDraftSchema
+  'programs-propose': programDraftSchema,
+  'sessions-import': {
+    description: 'JSON structure for sessions import --file. Uses the iOS WorkoutSession export shape.',
+    required: ['sessions'],
+    properties: {
+      sessions: {
+        type: 'array',
+        items: {
+          required: ['id', 'date', 'volume', 'exercises'],
+          properties: {
+            id: { type: 'string', description: 'Stable session UUID' },
+            date: { type: 'string', description: 'Session date label or yyyy-MM-dd date' },
+            completedAt: { type: 'string', description: 'Optional ISO completion timestamp' },
+            volume: { type: 'integer', minimum: 0 },
+            exercises: { type: 'array', description: 'Logged exercises in iOS export shape' }
+          }
+        }
+      }
+    }
+  }
 };
 
 // Describes how token scope gates commands, so an agent can decide before

package/src/external-app-change-routes.js

@@ -0,0 +1,274 @@
+export async function handleExternalAppChangeRoute({
+  route,
+  request,
+  response,
+  requestToken,
+  token,
+  readAuthenticator,
+  connectedWriteAuthenticator,
+  mobileSyncAuthenticator,
+  createExternalChangeForAccount,
+  listExternalChangesForAccount,
+  updateExternalChangeResultForAccount,
+  backfillExternalChangesForAccount,
+  readJsonBody,
+  rejectInsufficientScopeForReadToken,
+  json,
+  methodNotAllowed,
+  unauthorized,
+  badRequest,
+  notFound
+}) {
+  if (route.command === 'external-changes') {
+    if (request.method === 'GET' && request.url?.startsWith('/mobile/')) {
+      if (!listExternalChangesForAccount) {
+        methodNotAllowed(response, 'External change pull is not enabled for this service mode.');
+        return true;
+      }
+      const account = mobileSyncAuthenticator
+        ? await mobileSyncAuthenticator(requestToken)
+        : null;
+      if (!account) {
+        unauthorized(response, request);
+        return true;
+      }
+      const status = route.options.status ?? 'pending';
+      try {
+        json(response, 200, await listExternalChangesForAccount(account, { status, limit: 100 }));
+      } catch (error) {
+        badRequest(response, error.message);
+      }
+      return true;
+    }
+
+    if (request.method === 'GET') {
+      if (!listExternalChangesForAccount) {
+        methodNotAllowed(response, 'External change listing is not enabled for this service mode.');
+        return true;
+      }
+      const account = readAuthenticator
+        ? await readAuthenticator(requestToken)
+        : null;
+      if (!account) {
+        unauthorized(response, request);
+        return true;
+      }
+      const parsedLimit = route.options.limit ? parseInt(route.options.limit, 10) : 50;
+      const limit = Number.isFinite(parsedLimit) ? parsedLimit : 50;
+      try {
+        json(response, 200, await listExternalChangesForAccount(account, {
+          status: route.options.status,
+          limit
+        }));
+      } catch (error) {
+        badRequest(response, error.message);
+      }
+      return true;
+    }
+
+    if (request.method === 'POST') {
+      if (!createExternalChangeForAccount) {
+        methodNotAllowed(response, 'External change creation is not enabled for this service mode.');
+        return true;
+      }
+      const account = connectedWriteAuthenticator
+        ? await connectedWriteAuthenticator(requestToken)
+        : requestToken === token
+          ? { id: 'remote-user', email: null }
+          : null;
+      if (!account) {
+        if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+          return true;
+        }
+        unauthorized(response, request);
+        return true;
+      }
+      try {
+        const body = await readJsonBody(request);
+        const result = await createExternalChangeForAccount(account, body ?? {});
+        json(response, 201, { ok: true, externalChange: result });
+        return true;
+      } catch (error) {
+        badRequest(response, error.message);
+        return true;
+      }
+    }
+
+    methodNotAllowed(response, 'Use GET or POST for /cli/external-changes, or GET for /mobile/external-changes.');
+    return true;
+  }
+
+  if (route.command === 'external-change-result') {
+    if (request.method !== 'POST') {
+      methodNotAllowed(response, 'Use POST for /mobile/external-changes/:id/result.');
+      return true;
+    }
+    if (!updateExternalChangeResultForAccount) {
+      methodNotAllowed(response, 'External change result updates are not enabled for this service mode.');
+      return true;
+    }
+    const account = mobileSyncAuthenticator
+      ? await mobileSyncAuthenticator(requestToken)
+      : null;
+    if (!account) {
+      unauthorized(response, request);
+      return true;
+    }
+    try {
+      const body = await readJsonBody(request);
+      const result = await updateExternalChangeResultForAccount(account, route.options.id, body ?? {});
+      if (!result) {
+        notFound(response, 'External change not found.');
+        return true;
+      }
+      json(response, 200, { ok: true, externalChange: result });
+      return true;
+    } catch (error) {
+      badRequest(response, error.message);
+      return true;
+    }
+  }
+
+  if (route.command === 'external-changes-backfill') {
+    if (request.method !== 'POST') {
+      methodNotAllowed(response, 'Use POST for /cli/external-changes/backfill.');
+      return true;
+    }
+    if (!backfillExternalChangesForAccount) {
+      methodNotAllowed(response, 'External change backfill is not enabled for this service mode.');
+      return true;
+    }
+    const account = connectedWriteAuthenticator
+      ? await connectedWriteAuthenticator(requestToken)
+      : requestToken === token
+        ? { id: 'remote-user', email: null }
+        : null;
+    if (!account) {
+      if (await rejectInsufficientScopeForReadToken(response, request, requestToken, readAuthenticator)) {
+        return true;
+      }
+      unauthorized(response, request);
+      return true;
+    }
+    try {
+      const result = await backfillExternalChangesForAccount(account);
+      json(response, 200, result);
+      return true;
+    } catch (error) {
+      badRequest(response, error.message);
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export async function handleAppNotificationRoute({
+  route,
+  request,
+  response,
+  requestToken,
+  token,
+  readAuthenticator,
+  notifications,
+  json,
+  logRequest,
+  methodNotAllowed,
+  unauthorized,
+  notFound,
+  badRequest,
+  internalError,
+  onError
+}) {
+  if (!notifications) return false;
+
+  if (route.command === 'notifications') {
+    if (request.method !== 'GET') {
+      methodNotAllowed(response, 'Use GET for /cli/notifications.');
+      return true;
+    }
+    const notificationAccount = readAuthenticator
+      ? await readAuthenticator(requestToken)
+      : requestToken === token
+        ? { id: 'remote-user', email: null }
+        : null;
+    if (!notificationAccount) {
+      unauthorized(response, request);
+      return true;
+    }
+    const parsedLimit = route.options.limit ? parseInt(route.options.limit, 10) : 50;
+    const limit = Number.isFinite(parsedLimit) && parsedLimit > 0 ? Math.min(parsedLimit, 100) : 50;
+    try {
+      const payload = await notifications.list(notificationAccount.id, {
+        limit,
+        before: route.options.before ?? null
+      });
+      logRequest(request, 200);
+      json(response, 200, payload);
+      return true;
+    } catch (error) {
+      internalError(response, error, onError);
+      return true;
+    }
+  }
+
+  if (route.command === 'notification-read') {
+    if (request.method !== 'POST') {
+      methodNotAllowed(response, 'Use POST for /cli/notifications/:id/read.');
+      return true;
+    }
+    const notificationAccount = readAuthenticator
+      ? await readAuthenticator(requestToken)
+      : requestToken === token
+        ? { id: 'remote-user', email: null }
+        : null;
+    if (!notificationAccount) {
+      unauthorized(response, request);
+      return true;
+    }
+    try {
+      const notification = await notifications.markRead(notificationAccount.id, route.options.notificationId);
+      if (!notification) {
+        notFound(response, 'Notification not found.');
+        return true;
+      }
+      logRequest(request, 200);
+      json(response, 200, notification);
+      return true;
+    } catch (error) {
+      if (error?.message === 'notificationId is required.') {
+        badRequest(response, error.message);
+        return true;
+      }
+      internalError(response, error, onError);
+      return true;
+    }
+  }
+
+  if (route.command === 'notification-read-all') {
+    if (request.method !== 'POST') {
+      methodNotAllowed(response, 'Use POST for /cli/notifications/read-all.');
+      return true;
+    }
+    const notificationAccount = readAuthenticator
+      ? await readAuthenticator(requestToken)
+      : requestToken === token
+        ? { id: 'remote-user', email: null }
+        : null;
+    if (!notificationAccount) {
+      unauthorized(response, request);
+      return true;
+    }
+    try {
+      const result = await notifications.markAllRead(notificationAccount.id);
+      logRequest(request, 200);
+      json(response, 200, result);
+      return true;
+    } catch (error) {
+      internalError(response, error, onError);
+      return true;
+    }
+  }
+
+  return false;
+}

package/src/format.js

@@ -599,15 +599,16 @@ function formatProposalCreated(payload) {
 function formatProgramCreated(payload) {
   if (!payload) return 'No program data.';
   const lines = [
-    header('PROGRAM CREATED'),
+    header('PROGRAM QUEUED'),
     '',
     keyValue('ID', payload.id),
-    keyValue('Status', payload.status ?? 'inactive'),
+    keyValue('External change', payload.externalChangeId ?? payload.externalChange?.id ?? '?'),
+    keyValue('Status', payload.status ?? 'pending'),
     keyValue('Program', payload.name ?? 'Untitled'),
     keyValue('Days/week', String(payload.daysPerWeek ?? '?')),
     keyValue('Days', String(payload.days ?? payload.dayCount ?? '?')),
     '',
-    chalk.dim(' Created as an inactive saved program. Activate it later from iOS Programs.')
+    chalk.dim(' Queued for iOS import. Run `incremnt external changes` to check applied/skipped/failed status.')
   ];
   return lines.join('\n');
 }

package/src/program-draft.js

@@ -18,12 +18,15 @@ export const PROGRAM_DRAFT_LIMITS = {
   dayTitleMaxLen: 120,
   daySubtitleMaxLen: 120,
   noteMaxLen: 1000,
+  supersetKeyMaxLen: 64,
   minWeight: 0,
   maxWeight: 600,
   minReps: 1,
   maxReps: 30,
   minRir: 0,
   maxRir: 5,
+  minSupersetOrder: 0,
+  maxSupersetOrder: 24,
   minSetsPerExercise: 1,
   maxSetsPerExercise: 12,
   minExercisesPerDay: 1,
@@ -81,7 +84,7 @@ function normalizeProgramDraftSet(set) {
 }
 
 function normalizeProgramDraftExercise(exercise, canonicalizeExerciseName, strict = false) {
-  if (!hasOnlyAllowedKeys(exercise, new Set(['name', 'muscleGroup', 'sets', 'rir', 'note']))) return null;
+  if (!hasOnlyAllowedKeys(exercise, new Set(['name', 'muscleGroup', 'sets', 'rir', 'note', 'supersetKey', 'supersetOrder']))) return null;
 
   const name = normalizedExerciseDisplayName(exercise?.name, canonicalizeExerciseName);
   const muscleGroup = String(exercise?.muscleGroup ?? '').trim();
@@ -109,6 +112,20 @@ function normalizeProgramDraftExercise(exercise, canonicalizeExerciseName, stric
   const note = exercise?.note == null ? null : String(exercise.note);
   if (note && note.length > PROGRAM_DRAFT_LIMITS.noteMaxLen) return null;
 
+  const supersetKey = exercise?.supersetKey == null ? null : String(exercise.supersetKey).trim();
+  if (supersetKey != null && (
+    !supersetKey ||
+    supersetKey.length > PROGRAM_DRAFT_LIMITS.supersetKeyMaxLen
+  )) return null;
+
+  const supersetOrder = exercise?.supersetOrder == null ? null : Number(exercise.supersetOrder);
+  if (supersetKey == null && supersetOrder != null) return null;
+  if (supersetKey != null && (
+    !Number.isInteger(supersetOrder) ||
+    supersetOrder < PROGRAM_DRAFT_LIMITS.minSupersetOrder ||
+    supersetOrder > PROGRAM_DRAFT_LIMITS.maxSupersetOrder
+  )) return null;
+
   return {
     name,
     muscleGroup,
@@ -116,10 +133,33 @@ function normalizeProgramDraftExercise(exercise, canonicalizeExerciseName, stric
     nextSuggestion: '',
     sets,
     ...(note ? { note } : {}),
-    ...(rir != null ? { rir } : {})
+    ...(rir != null ? { rir } : {}),
+    ...(supersetKey != null ? { supersetKey, supersetOrder } : {})
   };
 }
 
+function hasValidDaySupersets(exercises) {
+  const grouped = new Map();
+  for (const exercise of exercises) {
+    if (!exercise.supersetKey) continue;
+    const existing = grouped.get(exercise.supersetKey) ?? [];
+    existing.push(exercise);
+    grouped.set(exercise.supersetKey, existing);
+  }
+
+  for (const group of grouped.values()) {
+    if (group.length < 2) return false;
+    const orders = new Set();
+    for (const exercise of group) {
+      if (!Number.isInteger(exercise.supersetOrder)) return false;
+      if (orders.has(exercise.supersetOrder)) return false;
+      orders.add(exercise.supersetOrder);
+    }
+  }
+
+  return true;
+}
+
 function normalizeProgramDraftDay(day, canonicalizeExerciseName, strict = false) {
   if (!hasOnlyAllowedKeys(day, new Set(['dayLabel', 'title', 'subtitle', 'exercises']))) return null;
 
@@ -139,6 +179,7 @@ function normalizeProgramDraftDay(day, canonicalizeExerciseName, strict = false)
     exercises.length < PROGRAM_DRAFT_LIMITS.minExercisesPerDay ||
     exercises.length > PROGRAM_DRAFT_LIMITS.maxExercisesPerDay
   ) return null;
+  if (!hasValidDaySupersets(exercises)) return null;
 
   return { dayLabel, title, subtitle, exercises };
 }
@@ -219,10 +260,15 @@ function defaultChildIdFactory() {
   return randomUUID();
 }
 
+function defaultSupersetIdFactory() {
+  return randomUUID();
+}
+
 export function buildProgramFromDraft(rawProgram, {
   now = new Date(),
   idFactory = defaultProgramIdFactory,
-  childIdFactory = defaultChildIdFactory
+  childIdFactory = defaultChildIdFactory,
+  supersetIdFactory = defaultSupersetIdFactory
 } = {}) {
   const draft = normalizeProgramDraft(rawProgram, { strict: true });
   if (!draft) {
@@ -230,28 +276,44 @@ export function buildProgramFromDraft(rawProgram, {
   }
 
   const createdAt = now instanceof Date ? now.toISOString() : new Date(now).toISOString();
-  const days = draft.days.map((day) => ({
-    id: childIdFactory('day'),
-    dayLabel: day.dayLabel,
-    title: day.title,
-    subtitle: day.subtitle,
-    exercises: day.exercises.map((exercise) => ({
-      id: childIdFactory('exercise'),
-      name: exercise.name,
-      muscleGroup: exercise.muscleGroup,
-      lastSuggestion: exercise.lastSuggestion,
-      nextSuggestion: exercise.nextSuggestion,
-      sets: exercise.sets.map((set) => ({
-        id: childIdFactory('set'),
-        weight: set.weight,
-        reps: set.reps,
-        isComplete: false,
-        isWarmup: set.isWarmup === true
-      })),
-      ...(exercise.note ? { note: exercise.note } : {}),
-      ...(exercise.rir != null ? { rir: exercise.rir } : {})
-    }))
-  }));
+  const days = draft.days.map((day) => {
+    const supersetGroupIds = new Map();
+    const groupIdForKey = (key) => {
+      if (!supersetGroupIds.has(key)) {
+        supersetGroupIds.set(key, supersetIdFactory('superset'));
+      }
+      return supersetGroupIds.get(key);
+    };
+
+    return {
+      id: childIdFactory('day'),
+      dayLabel: day.dayLabel,
+      title: day.title,
+      subtitle: day.subtitle,
+      exercises: day.exercises.map((exercise) => ({
+        id: childIdFactory('exercise'),
+        name: exercise.name,
+        muscleGroup: exercise.muscleGroup,
+        lastSuggestion: exercise.lastSuggestion,
+        nextSuggestion: exercise.nextSuggestion,
+        sets: exercise.sets.map((set) => ({
+          id: childIdFactory('set'),
+          weight: set.weight,
+          reps: set.reps,
+          isComplete: false,
+          isWarmup: set.isWarmup === true
+        })),
+        ...(exercise.note ? { note: exercise.note } : {}),
+        ...(exercise.rir != null ? { rir: exercise.rir } : {}),
+        ...(exercise.supersetKey
+          ? {
+              supersetGroupId: groupIdForKey(exercise.supersetKey),
+              supersetOrder: exercise.supersetOrder
+            }
+          : {})
+      }))
+    };
+  });
 
   return {
     id: idFactory('program'),

package/src/remote.js

@@ -133,6 +133,7 @@ async function throwForbiddenResponse(response, sessionState, commandId) {
 const remoteCommandHandlers = {
   'session-insights': executeRemoteRead,
   'session-show': executeRemoteRead,
+  'external-changes': executeRemoteRead,
   'exercise-history': executeRemoteRead,
   records: executeRemoteRead,
   'program-list': executeRemoteRead,
@@ -245,6 +246,12 @@ function endpointForCommand(baseUrl, normalizedCommand, options) {
       return resolveServiceUrl(baseUrl, `/cli/sessions/${encodeURIComponent(options['session-id'])}/compare`);
     case 'why-did-this-change':
       return resolveServiceUrl(baseUrl, `/cli/sessions/${encodeURIComponent(options['session-id'])}/explain`);
+    case 'external-changes': {
+      const url = resolveServiceUrl(baseUrl, '/cli/external-changes');
+      if (options.status) url.searchParams.set('status', options.status);
+      if (options.limit) url.searchParams.set('limit', options.limit);
+      return url;
+    }
     case 'program-list':
       return resolveServiceUrl(baseUrl, '/cli/programs');
     case 'program-summary':
@@ -501,6 +508,35 @@ export async function buildWriteRequest(commandId, options, sessionState) {
         body: draft
       };
     }
+    case 'sessions-import': {
+      if (!options.file) {
+        const error = new Error('--file is required for sessions import.');
+        error.code = 'MISSING_OPTION';
+        throw error;
+      }
+      const raw = await fs.readFile(options.file, 'utf8');
+      const payload = JSON.parse(raw);
+      return {
+        method: 'POST',
+        url: resolveServiceUrl(baseUrl, '/cli/external-changes').toString(),
+        body: {
+          kind: 'sessions.import',
+          source: {
+            surface: 'cli',
+            command: 'sessions import',
+            version: 1
+          },
+          payload
+        }
+      };
+    }
+    case 'external-changes-backfill': {
+      return {
+        method: 'POST',
+        url: resolveServiceUrl(baseUrl, '/cli/external-changes/backfill').toString(),
+        body: null
+      };
+    }
     case 'programs-propose': {
       if (!options.file) {
         const error = new Error('--file is required for programs propose.');
@@ -719,6 +755,51 @@ const remoteWriteCommandHandlers = {
     return response.json();
   },
 
+  'sessions-import': async (options, sessionState) => {
+    const baseUrl = sessionState.session?.transport?.baseUrl;
+    if (!baseUrl) throw notImplementedError();
+
+    const filePath = options.file;
+    if (!filePath) {
+      const error = new Error('--file is required for sessions import.');
+      error.code = 'MISSING_OPTION';
+      throw error;
+    }
+
+    const raw = await fs.readFile(filePath, 'utf8');
+    const payload = JSON.parse(raw);
+    const body = {
+      kind: 'sessions.import',
+      source: {
+        surface: 'cli',
+        command: 'sessions import',
+        version: 1
+      },
+      payload
+    };
+
+    const endpoint = resolveServiceUrl(baseUrl, '/cli/external-changes');
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${sessionState.session?.auth?.accessToken ?? ''}`
+      },
+      body: JSON.stringify(body)
+    });
+
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'sessions-import');
+    if (!response.ok) {
+      const responsePayload = await response.json().catch(() => null);
+      const error = new Error(responsePayload?.error ?? `Unexpected error (HTTP ${response.status}).`);
+      error.code = 'REMOTE_HTTP_ERROR';
+      throw error;
+    }
+
+    return response.json();
+  },
+
   'programs-proposals': async (options, sessionState) => {
     const baseUrl = sessionState.session?.transport?.baseUrl;
     if (!baseUrl) throw notImplementedError();
@@ -783,6 +864,30 @@ const remoteWriteCommandHandlers = {
     return response.json();
   },
 
+  'external-changes-backfill': async (_options, sessionState) => {
+    const baseUrl = sessionState.session?.transport?.baseUrl;
+    if (!baseUrl) throw notImplementedError();
+
+    const endpoint = resolveServiceUrl(baseUrl, '/cli/external-changes/backfill');
+    const response = await fetch(endpoint, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${sessionState.session?.auth?.accessToken ?? ''}`
+      }
+    });
+
+    if (response.status === 401) throw authenticationFailedError();
+    if (response.status === 403) await throwForbiddenResponse(response, sessionState, 'external-changes-backfill');
+    if (!response.ok) {
+      const payload = await response.json().catch(() => null);
+      const error = new Error(payload?.error ?? `Unexpected error (HTTP ${response.status}).`);
+      error.code = 'REMOTE_HTTP_ERROR';
+      throw error;
+    }
+
+    return response.json();
+  },
+
   'program-share-create': async (options, sessionState) => {
     const baseUrl = sessionState.session?.transport?.baseUrl;
     if (!baseUrl) throw notImplementedError();

package/src/sync-service.js

@@ -24,7 +24,11 @@ import { capabilities as cliCapabilities, contractVersion, officialCommands } fr
 import { canonicalExerciseName, executeReadCommand } from './queries.js';
 import { sanitizeHistory, detectSystemPromptLeak, stripXMLTagBlocks } from './prompt-security.js';
 import { compactScoreHistorySnapshots, enrichScoreSnapshots } from './score-context.js';
-import { buildProgramFromDraft, extractAskProgramDraft } from './program-draft.js';
+import { buildProgramFromDraft, extractAskProgramDraft, normalizeProgramDraft } from './program-draft.js';
+import {
+  handleAppNotificationRoute,
+  handleExternalAppChangeRoute
+} from './external-app-change-routes.js';
 import { extractPlanChangeset } from './plan-changeset.js';
 import { extractProgramScheduleAction } from './program-schedule-action.js';
 import { extractCoachAdvice } from './coach-advice.js';
@@ -89,6 +93,9 @@ const DEFAULT_RATE_LIMIT_RULES = {
   'sync-account-preferences': 30,
   'proposals': 30,
   'proposal-update': 30,
+  'external-changes': 60,
+  'external-change-result': 60,
+  'external-changes-backfill': 10,
   'program-share-create': 30,
   'program-share-list': 60,
   'program-share-public': 120,
@@ -133,6 +140,9 @@ const DEFAULT_RATE_LIMIT_RULES = {
   'social-media-complete': 30,
   'social-media-delete': 30,
   'social-post-update': 30,
+  'notifications': 60,
+  'notification-read': 60,
+  'notification-read-all': 30,
   'social-notifications': 60,
   'social-notification-read': 60,
   'social-notification-read-all': 30,
@@ -311,6 +321,27 @@ function stableAdviceObservationKey(advice) {
   return `ask-advice:${createHash('sha256').update(material).digest('hex').slice(0, 24)}`;
 }
 
+function stableJson(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJson).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function programCreateIdempotencyKey(rawDraft) {
+  const draft = normalizeProgramDraft(rawDraft, { strict: true });
+  if (!draft) {
+    throw new Error('Invalid generated program draft.');
+  }
+  const digest = createHash('sha256')
+    .update(stableJson({ command: 'programs create', version: 1, draft }), 'utf8')
+    .digest('hex');
+  return `program.create:cli-draft:sha256:${digest}`;
+}
+
 function confidenceScore(confidence) {
   if (confidence === 'high') return 0.85;
   if (confidence === 'medium') return 0.7;
@@ -1492,6 +1523,25 @@ function routeRequest(url, method) {
     return { command: 'mobile-sync-push', options: {} };
   }
 
+  if (pathname === '/mobile/external-changes') {
+    return {
+      command: 'external-changes',
+      options: {
+        status: url.searchParams.get('status') ?? 'pending'
+      }
+    };
+  }
+
+  {
+    const externalChangeResultMatch = pathname.match(/^\/mobile\/external-changes\/([^/]+)\/result$/);
+    if (externalChangeResultMatch) {
+      return {
+        command: 'external-change-result',
+        options: { id: decodeURIComponent(externalChangeResultMatch[1]) }
+      };
+    }
+  }
+
   if (pathname === '/mobile/score-snapshots') {
     return {
       command: 'score-snapshots',
@@ -1566,6 +1616,20 @@ function routeRequest(url, method) {
     return { command: 'proposals', options: { status: url.searchParams.get('status') ?? undefined } };
   }
 
+  if (pathname === '/cli/external-changes') {
+    return {
+      command: 'external-changes',
+      options: {
+        status: url.searchParams.get('status') ?? undefined,
+        limit: url.searchParams.get('limit') ?? undefined
+      }
+    };
+  }
+
+  if (pathname === '/cli/external-changes/backfill') {
+    return { command: 'external-changes-backfill', options: {} };
+  }
+
   {
     const programShareCreateMatch = pathname.match(/^\/cli\/programs\/([^/]+)\/share$/);
     if (programShareCreateMatch) {
@@ -2153,9 +2217,9 @@ function routeRequest(url, method) {
     }
   }
 
-  if (pathname === '/cli/social/notifications') {
+  if (pathname === '/cli/notifications' || pathname === '/cli/social/notifications') {
     return {
-      command: 'social-notifications',
+      command: pathname === '/cli/notifications' ? 'notifications' : 'social-notifications',
       options: {
         limit: url.searchParams.get('limit') ?? undefined,
         before: url.searchParams.get('before') ?? undefined
@@ -2163,15 +2227,15 @@ function routeRequest(url, method) {
     };
   }
 
-  if (pathname === '/cli/social/notifications/read-all') {
-    return { command: 'social-notification-read-all', options: {} };
+  if (pathname === '/cli/notifications/read-all' || pathname === '/cli/social/notifications/read-all') {
+    return { command: pathname === '/cli/notifications/read-all' ? 'notification-read-all' : 'social-notification-read-all', options: {} };
   }
 
   {
-    const notificationReadMatch = pathname.match(/^\/cli\/social\/notifications\/([^/]+)\/read$/);
+    const notificationReadMatch = pathname.match(/^\/cli\/(?:social\/)?notifications\/([^/]+)\/read$/);
     if (notificationReadMatch) {
       return {
-        command: 'social-notification-read',
+        command: pathname.startsWith('/cli/notifications/') ? 'notification-read' : 'social-notification-read',
         options: { notificationId: decodeURIComponent(notificationReadMatch[1]) }
       };
     }
@@ -2780,6 +2844,10 @@ export function createSyncServiceRequestHandler({
   createProposalForAccount = null,
   listProposalsForAccount = null,
   updateProposalForAccount = null,
+  createExternalChangeForAccount = null,
+  listExternalChangesForAccount = null,
+  updateExternalChangeResultForAccount = null,
+  backfillExternalChangesForAccount = null,
   createProgramShareForAccount = null,
   listProgramSharesForAccount = null,
   readPublicProgramShare = null,
@@ -2823,6 +2891,7 @@ export function createSyncServiceRequestHandler({
   recordCoachObservationOutcomeForAccount = null,
   recordCoachObservationFeedbackForAccount = null,
   // Social
+  notifications = null,
   social = null,
   onError = null
 }) {
@@ -3810,6 +3879,30 @@ export function createSyncServiceRequestHandler({
         return;
       }
 
+      if (await handleExternalAppChangeRoute({
+        route,
+        request,
+        response,
+        requestToken,
+        token,
+        readAuthenticator,
+        connectedWriteAuthenticator,
+        mobileSyncAuthenticator,
+        createExternalChangeForAccount,
+        listExternalChangesForAccount,
+        updateExternalChangeResultForAccount,
+        backfillExternalChangesForAccount,
+        readJsonBody,
+        rejectInsufficientScopeForReadToken,
+        json,
+        methodNotAllowed,
+        unauthorized,
+        badRequest,
+        notFound
+      })) {
+        return;
+      }
+
       if (route.command === 'score-snapshots') {
         if (request.method === 'POST') {
           if (!insertScoreSnapshotsForAccount) {
@@ -7852,6 +7945,26 @@ export function createSyncServiceRequestHandler({
         }
       }
 
+      if (await handleAppNotificationRoute({
+        route,
+        request,
+        response,
+        requestToken,
+        token,
+        readAuthenticator,
+        notifications,
+        json,
+        logRequest,
+        methodNotAllowed,
+        unauthorized,
+        notFound,
+        badRequest,
+        internalError,
+        onError
+      })) {
+        return;
+      }
+
       if (social && route.command === 'social-notifications') {
         if (request.method !== 'GET') {
           methodNotAllowed(response, 'Use GET for /cli/social/notifications.');
@@ -8014,7 +8127,7 @@ export function createSyncServiceRequestHandler({
       }
 
       if (route.command === 'program-list' && request.method === 'POST') {
-        if (!pushMobileSyncChangesForAccount) {
+        if (!createExternalChangeForAccount) {
           methodNotAllowed(response, 'Program creation is not enabled for this service mode.');
           return;
         }
@@ -8034,25 +8147,28 @@ export function createSyncServiceRequestHandler({
 
         try {
           const body = await readJsonBody(request);
+          const idempotencyKey = programCreateIdempotencyKey(body);
           const program = buildProgramFromDraft(body);
-          await pushMobileSyncChangesForAccount(writeAccount, {
-            deviceId: 'cli-program-create',
-            changes: [
-              {
-                type: 'program',
-                id: program.id,
-                updatedAt: program.externalInputProvenance.createdAt,
-                payload: program
-              }
-            ]
+          const externalChange = await createExternalChangeForAccount(writeAccount, {
+            kind: 'program.create',
+            source: {
+              surface: 'cli',
+              command: 'programs create',
+              version: 1
+            },
+            payload: { program },
+            idempotencyKey
           });
+          const queuedProgram = externalChange?.payload?.program ?? program;
           json(response, 201, {
             ok: true,
-            id: program.id,
-            name: program.name,
-            status: 'inactive',
-            daysPerWeek: program.daysPerWeek,
-            days: program.days.length
+            id: queuedProgram.id,
+            name: queuedProgram.name,
+            status: externalChange.status,
+            externalChangeId: externalChange.id,
+            externalChange,
+            daysPerWeek: queuedProgram.daysPerWeek,
+            days: queuedProgram.days.length
           });
           return;
         } catch (error) {