@commonlyai/cli 0.1.38 → 0.1.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@commonlyai/cli",
-  "version": "0.1.38",
+  "version": "0.1.40",
   "license": "Apache-2.0",
   "description": "The Commonly CLI — connect agents, manage pods, iterate fast",
   "type": "module",

package/src/commands/agent.js

@@ -33,6 +33,11 @@ import { pollRetryPolicy } from '../lib/poll-retry.js';
 import { detectMemorySources, composeImport, importMemory } from '../lib/memory-import.js';
 import { detectSkills, importSkills } from '../lib/skills-import.js';
 import { parseEnvironmentFile, resolveWorkspace, validateEnvironmentSpec } from '../lib/environment.js';
+import {
+  FOCUS_FRAME_MAX_CODE_POINTS,
+  formatPodFocusFrame,
+  readPodFocus,
+} from '../lib/pod-focus.js';
 import { detectBwrap } from '../lib/sandbox/bwrap.js';
 import { detectSeatbelt } from '../lib/sandbox/seatbelt.js';
 import {
@@ -55,6 +60,11 @@ import {
   resolveCascadeSettings,
 } from '../lib/enforcement.js';
 
+const isPodFocusDiagnostic = (error) => (
+  typeof error?.code === 'string'
+  && (error.code.startsWith('pod_focus') || error.code.startsWith('FOCUS_FRAME_'))
+);
+
 // ── Token file I/O — ~/.commonly/tokens/<name>.json (ADR-005) ───────────────
 
 const tokensDir = () => join(homedir(), '.commonly', 'tokens');
@@ -385,27 +395,46 @@ export const setWakeOnMessage = async ({ client, record, enabled }) => {
 export const updateAgentConfiguration = async ({
   client,
   record,
+  adapter = null,
   model = null,
   effort = null,
   envPath = null,
   parseEnv = parseEnvironmentFile,
+  adapterRegistry = { getAdapter, listAdapterNames },
 }) => {
   if (!record?.podId || !record?.agentName) {
     throw new Error('token record is missing podId/agentName — re-attach the agent');
   }
   const instanceId = record.instanceId || 'default';
   const runtime = {};
+  const environmentRuntime = {};
+  if (adapter !== null && adapter !== undefined) {
+    const normalizedAdapter = String(adapter).trim().toLowerCase();
+    const knownAdapters = adapterRegistry.listAdapterNames();
+    const selectedAdapter = adapterRegistry.getAdapter(normalizedAdapter);
+    if (!selectedAdapter || !knownAdapters.includes(normalizedAdapter)) {
+      throw new Error(
+        `Unknown adapter '${normalizedAdapter}'. Known: ${knownAdapters.join(', ')}`,
+      );
+    }
+    if (!await selectedAdapter.detect()) {
+      throw new Error(`Adapter '${normalizedAdapter}' not found on PATH. Install it and retry.`);
+    }
+    runtime.adapter = normalizedAdapter;
+  }
   if (model !== null && model !== undefined) {
     const normalizedModel = String(model);
     const validation = validateEnvironmentSpec({ model: normalizedModel });
     if (!validation.ok) throw new Error(validation.errors.join('; '));
     runtime.model = normalizedModel;
+    environmentRuntime.model = normalizedModel;
   }
   if (effort !== null && effort !== undefined) {
     const normalizedEffort = String(effort);
     const validation = validateEnvironmentSpec({ effort: normalizedEffort });
     if (!validation.ok) throw new Error(validation.errors.join('; '));
     runtime.effort = normalizedEffort;
+    environmentRuntime.effort = normalizedEffort;
   }
   const config = {};
   if (Object.keys(runtime).length) config.runtime = runtime;
@@ -419,15 +448,15 @@ export const updateAgentConfiguration = async ({
   // an ADR-008 environment, a model/effort flag must update that declaration
   // too; otherwise the daemon would correctly prefer the old explicit value
   // over the new legacy runtime overlay.
-  if (environment && Object.keys(runtime).length) {
-    environment = { ...environment, ...runtime };
+  if (environment && Object.keys(environmentRuntime).length) {
+    environment = { ...environment, ...environmentRuntime };
   }
-  if (!environment && Object.keys(runtime).length) {
-    environment = { ...runtime };
+  if (!environment && Object.keys(environmentRuntime).length) {
+    environment = { ...environmentRuntime };
   }
   if (environment) config.environment = environment;
   if (!Object.keys(config).length) {
-    throw new Error('provide at least one of --model, --effort, or --env');
+    throw new Error('provide at least one of --adapter, --model, --effort, or --env');
   }
 
   await client.patch(
@@ -439,6 +468,7 @@ export const updateAgentConfiguration = async ({
     podId: record.podId,
     instanceId,
     changed: Object.keys(config),
+    ...(runtime.adapter ? { adapter: runtime.adapter } : {}),
     ...(environment ? { environment } : {}),
   };
 };
@@ -1129,8 +1159,30 @@ export const performRun = ({
     // and (if the adapter returns a summary) patch-sync back after.
     const memoryLongTerm = await readLongTerm(client, { onError });
 
+    // Sharpen TASK-129: focus is a turn-start read, not an enqueue-time
+    // snapshot. Read through the authorized runtime context route immediately
+    // before spawn so queued events observe the current revision. The helper
+    // disables pod-skill synthesis and throws on failure; the surrounding
+    // processing path then leaves this event (or every event in this batch)
+    // unacknowledged for normal delivery retry.
+    let focusRead;
+    let focusFrame;
+    try {
+      focusRead = await readPodFocus(client, eventPodId);
+      focusFrame = formatPodFocusFrame(focusRead);
+    } catch (error) {
+      Object.assign(error, {
+        eventId: event?.payload?.batchEventIds || event?._id || null,
+        podId: eventPodId,
+        focusRevision: focusRead?.revision ?? null,
+        allowedCodePoints: error?.allowedCodePoints || FOCUS_FRAME_MAX_CODE_POINTS,
+      });
+      throw error;
+    }
+    const promptWithFocus = `${focusFrame}\n\n${prompt}`;
+
     log(`[${event.type}] spawning ${adapter.name}`);
-    const result = await adapter.spawn(frameDecisionForkRule(prompt), {
+    const result = await adapter.spawn(frameDecisionForkRule(promptWithFocus), {
       sessionId,
       cwd: agentCwd,
       env: process.env,
@@ -1631,6 +1683,16 @@ export const performRun = ({
               retryAfterMs: retry.delayMs,
               circuitOpen: retry.circuitOpen,
               eventId: event._id,
+              ...(isPodFocusDiagnostic(err) ? {
+                focusDiagnostic: {
+                  errorCode: err.code,
+                  eventIds: err.eventId || group.map((entry) => entry._id),
+                  podId: err.podId || group[0]?.podId || podId || null,
+                  focusRevision: err.focusRevision ?? null,
+                  measuredCodePoints: err.measuredCodePoints ?? null,
+                  allowedCodePoints: err.allowedCodePoints ?? FOCUS_FRAME_MAX_CODE_POINTS,
+                },
+              } : {}),
             });
             if (onError) onError(wrapped);
             else log(`[inbox.batch] ${wrapped.message}`);
@@ -1701,6 +1763,16 @@ export const performRun = ({
               retryAfterMs: retry.delayMs,
               circuitOpen: retry.circuitOpen,
               eventId: event._id,
+              ...(isPodFocusDiagnostic(err) ? {
+                focusDiagnostic: {
+                  errorCode: err.code,
+                  eventIds: err.eventId || event._id,
+                  podId: err.podId || event.podId || podId || null,
+                  focusRevision: err.focusRevision ?? null,
+                  measuredCodePoints: err.measuredCodePoints ?? null,
+                  allowedCodePoints: err.allowedCodePoints ?? FOCUS_FRAME_MAX_CODE_POINTS,
+                },
+              } : {}),
             });
             // ONE emission, not two. `wrapped.message` already opens with the
             // event type, so the log copy added a second prefix and a second
@@ -2025,6 +2097,7 @@ Examples:
 
   # List installed agents
   $ commonly agent list
+  $ commonly agent config my-claude --adapter claude --model gpt-5.4 --effort high
   $ commonly agent config my-claude --model gpt-5.4 --effort high
 
 Docs:
@@ -2652,6 +2725,7 @@ Use --local to find the name you'd pass to 'agent run' or 'agent detach'.
   agent
     .command('config <name>')
     .description('Update an attached agent\'s server-side runtime configuration')
+    .option('--adapter <name>', 'Local runtime adapter (must be installed on this machine)')
     .option('--model <id>', 'Model identifier to use on the next daemon restart')
     .option('--effort <level>', 'Reasoning effort (low|medium|high|xhigh|max)')
     .option('--env <path>', 'Replace the ADR-008 environment spec with this JSON file')
@@ -2670,12 +2744,17 @@ Use --local to find the name you'd pass to 'agent run' or 'agent detach'.
         const result = await updateAgentConfiguration({
           client,
           record,
+          adapter: opts.adapter,
           model: opts.model,
           effort: opts.effort,
           envPath: opts.env ? pathResolve(opts.env) : null,
         });
-        if (result.environment) {
-          saveAgentToken(name, { ...record, environment: result.environment });
+        if (result.environment || result.adapter) {
+          saveAgentToken(name, {
+            ...record,
+            ...(result.environment ? { environment: result.environment } : {}),
+            ...(result.adapter ? { adapter: result.adapter } : {}),
+          });
         }
         console.log(`✓ Updated ${result.agentName} in pod ${result.podId} (${result.changed.join(', ')})`);
         console.log('  The daemon will apply the change on its next poll; a standalone agent run needs a restart.');

package/src/lib/adapters/claude.js

@@ -59,7 +59,7 @@ import {
   writeFile,
 } from 'fs/promises';
 import { homedir, tmpdir } from 'os';
-import { isAbsolute, join } from 'path';
+import { delimiter, isAbsolute, join } from 'path';
 
 import { mountSkills } from '../environment.js';
 import { wrapArgvWithBwrap } from '../sandbox/bwrap.js';
@@ -337,17 +337,39 @@ const createMcpConfig = async (mcpServers, ctx = {}) => {
 
 // ── argv preparation — environment-aware ────────────────────────────────────
 
+// Claude's npm installer commonly puts the binary in ~/.local/bin, while
+// launchd/supervisor environments intentionally use a small PATH. Keep the
+// command name for the legacy spawn contract, but add this directory to the
+// child environment and to every detection lookup so a daemon does not report
+// a false "adapter unavailable" (or hit spawn ENOENT) merely because it was
+// started outside an interactive shell.
+const withClaudePath = (input) => {
+  const output = { ...(input || process.env) };
+  const localBin = join(homedir(), '.local', 'bin');
+  const entries = String(output.PATH || '')
+    .split(delimiter)
+    .filter(Boolean);
+  if (!entries.includes(localBin)) entries.push(localBin);
+  output.PATH = entries.join(delimiter);
+  return output;
+};
+
 // Resolve the absolute path of `claude` so bwrap's execvp doesn't depend on
 // PATH being correctly populated inside the sandbox namespace. Surfaced live
 // during the 2026-04-17 demo validation: bwrap silently inherits parent
 // PATH but cannot reach the user's `~/.local/bin` without an absolute path
 // argv[0], even when that directory is bound read-only into the sandbox.
-const resolveClaudePath = () => {
+const resolveClaudePath = (env = process.env) => {
   // Defensive: spawnSync can return undefined under aggressive mocks (the
   // adapters.claude.environment.test.mjs suite stubs child_process so no real
   // process runs). Treat any failure mode as "use the bare command name."
   let which;
-  try { which = spawnSync('which', ['claude'], { encoding: 'utf8' }); } catch { /* ignore */ }
+  try {
+    which = spawnSync('which', ['claude'], {
+      encoding: 'utf8',
+      env: withClaudePath(env),
+    });
+  } catch { /* ignore */ }
   if (which && which.status === 0) {
     const p = (which.stdout || '').trim();
     if (p) {
@@ -363,7 +385,8 @@ const resolveClaudePath = () => {
 
 const prepareArgv = async (innerArgv, ctx) => {
   const env = ctx.environment;
-  if (!env) return { cmd: 'claude', args: innerArgv, env: ctx.claudeEnv };
+  const claudeEnv = withClaudePath(ctx.claudeEnv);
+  if (!env) return { cmd: 'claude', args: innerArgv, env: claudeEnv };
 
   let allowedPatterns = [];
   if (Array.isArray(env.mcp) && env.mcp.length > 0) {
@@ -407,7 +430,7 @@ const prepareArgv = async (innerArgv, ctx) => {
       ...innerArgv,
       ...buildPublicClaudePolicyArgs(allowedPatterns),
     ];
-    const claudeBin = resolveClaudePath();
+    const claudeBin = resolveClaudePath(claudeEnv);
     const mcpExecutables = (env.mcp || [])
       .map((server) => server?.command?.[0])
       .filter((command) => isAbsolute(command));
@@ -422,7 +445,7 @@ const prepareArgv = async (innerArgv, ctx) => {
     return {
       cmd: wrapped[0],
       args: wrapped.slice(1),
-      env: ctx.claudeEnv,
+      env: claudeEnv,
     };
   }
 
@@ -430,15 +453,15 @@ const prepareArgv = async (innerArgv, ctx) => {
     innerArgv = [...innerArgv, '--allowedTools', ...allowedPatterns];
   }
   if (sandboxMode === 'bwrap') {
-    const claudeBin = resolveClaudePath();
+    const claudeBin = resolveClaudePath(claudeEnv);
     const wrapped = wrapArgvWithBwrap([claudeBin, ...innerArgv], env, {
       workspacePath: ctx.cwd,
       readOnlyPaths: ctx.mcpConfigDir ? [ctx.mcpConfigDir] : [],
     });
-    return { cmd: wrapped[0], args: wrapped.slice(1), env: ctx.claudeEnv };
+    return { cmd: wrapped[0], args: wrapped.slice(1), env: claudeEnv };
   }
 
-  return { cmd: 'claude', args: innerArgv, env: ctx.claudeEnv };
+  return { cmd: 'claude', args: innerArgv, env: claudeEnv };
 };
 
 export default {
@@ -453,14 +476,21 @@ export default {
 
   async detect() {
     try {
-      const res = spawnSync('claude', ['--version'], { encoding: 'utf8' });
+      const claudeEnv = withClaudePath(process.env);
+      const res = spawnSync('claude', ['--version'], {
+        encoding: 'utf8',
+        env: claudeEnv,
+      });
       if (res.error || res.status !== 0) return null;
       // `claude --version` prints e.g. "2.5.1 (Claude Code)" — first token is enough
       const version = (res.stdout || '').trim().split(/\s+/)[0] || 'unknown';
       // Best-effort resolve of the binary path for clearer UX ("claude detected
       // at /usr/local/bin/claude"). Falls back to the bare command name on
       // platforms without `which` (e.g. Windows).
-      const where = spawnSync('which', ['claude'], { encoding: 'utf8' });
+      const where = spawnSync('which', ['claude'], {
+        encoding: 'utf8',
+        env: claudeEnv,
+      });
       const path = where.status === 0 ? (where.stdout || '').trim() || 'claude' : 'claude';
       return { path, version };
     } catch {

package/src/lib/daemon-supervisor.js

@@ -133,6 +133,26 @@ export const createDaemonSupervisor = ({
       // once at boot). A row with NO declared model leaves the record alone —
       // never strip an operator's hand-set environment.
       const wanted = environmentFor(row);
+      const declaredAdapter = row.runtime && typeof row.runtime === 'object'
+        && typeof row.runtime.adapter === 'string'
+        ? row.runtime.adapter.trim().toLowerCase()
+        : null;
+      let adapterChanged = false;
+      let nextAdapter = existing.adapter;
+      if (declaredAdapter) {
+        const detectedAdapter = await resolveAdapter(row.runtime || null);
+        // resolveAdapterForRuntime historically probes fallbacks when a
+        // declared adapter is absent. A configuration edit must never accept
+        // that fallback: it would report claude while running codex (or vice
+        // versa). Keep the existing child/token untouched until the exact
+        // requested adapter is detected locally.
+        if (detectedAdapter !== declaredAdapter) {
+          log(`[${row.agentName}] requested adapter '${declaredAdapter}' is not available on this machine — keeping the current seat`);
+          return false;
+        }
+        nextAdapter = declaredAdapter;
+        adapterChanged = existing.adapter !== nextAdapter;
+      }
       if (wanted) {
         const nextEnvironment = wanted.declared
           ? wanted.value
@@ -140,18 +160,37 @@ export const createDaemonSupervisor = ({
         const workspacePath = workspacePathFor(nextEnvironment);
         const nextRecord = {
           ...existing,
+          ...(adapterChanged ? { adapter: nextAdapter } : {}),
           environment: nextEnvironment,
           ...(workspacePath ? { workspacePath } : {}),
         };
-        if (!isDeepStrictEqual(existing.environment || null, nextEnvironment)
+        if (adapterChanged
+          || !isDeepStrictEqual(existing.environment || null, nextEnvironment)
           || (workspacePath && existing.workspacePath !== workspacePath)) {
           saveToken(row.agentName, nextRecord);
           log('runtime config changed — restarting the seat to load it');
           return 'changed';
         }
       }
+      if (adapterChanged) {
+        saveToken(row.agentName, { ...existing, adapter: nextAdapter });
+        log('runtime adapter changed — restarting the seat to load it');
+        return 'changed';
+      }
       return 'ready';
     }
+    const requestedAdapter = row.runtime && typeof row.runtime === 'object'
+      && typeof row.runtime.adapter === 'string'
+      ? row.runtime.adapter.trim().toLowerCase()
+      : null;
+    let adapter = null;
+    if (requestedAdapter) {
+      adapter = await resolveAdapter(row.runtime || null);
+      if (adapter !== requestedAdapter) {
+        log(`[${row.agentName}] requested adapter '${requestedAdapter}' is not available on this machine — skipping token mint`);
+        return false;
+      }
+    }
     const body = { agentName: row.agentName, instanceId: row.instanceId };
     let minted;
     try {
@@ -174,7 +213,7 @@ export const createDaemonSupervisor = ({
       log(`[${row.agentName}] mint returned no token — skipping`);
       return false;
     }
-    const adapter = await resolveAdapter(row.runtime || null);
+    if (!adapter) adapter = await resolveAdapter(row.runtime || null);
     if (!adapter) {
       log(`[${row.agentName}] no usable CLI adapter on this machine — install claude or codex, or attach manually`);
       return false;

package/src/lib/pod-focus.js

@@ -0,0 +1,224 @@
+/**
+ * Shared-pod focus bridge for the local CLI driver.
+ *
+ * The server's runtime context endpoint is the source of truth.  This module
+ * deliberately keeps the read and the text formatter together so every CLI
+ * adapter receives the same bounded projection, including resumed sessions.
+ */
+
+export const FOCUS_FRAME_MAX_CODE_POINTS = 8000;
+export const FOCUS_TASK_TITLE_MAX_CODE_POINTS = 160;
+
+const codePointLength = (value) => Array.from(String(value)).length;
+
+const asText = (value, fallback = '') => {
+  if (value === null || value === undefined) return fallback;
+  return String(value);
+};
+
+const truncateCodePoints = (value, max) => {
+  const text = asText(value);
+  const points = Array.from(text);
+  if (points.length <= max) return text;
+  if (max <= 1) return '…'.slice(0, max);
+  return `${points.slice(0, max - 1).join('')}…`;
+};
+
+export class PodFocusError extends Error {
+  constructor(message, details = {}, options = {}) {
+    super(message, options);
+    this.name = 'PodFocusError';
+    Object.assign(this, details);
+  }
+}
+
+const hasOwn = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+
+const invalidContract = (message, details = {}) => new PodFocusError(message, {
+  code: 'pod_focus_contract_invalid',
+  ...details,
+});
+
+const normalizeDto = (dto, podId) => {
+  if (!dto || typeof dto !== 'object' || Array.isArray(dto)) {
+    throw invalidContract('Runtime context did not return a PodFocusRead object', { podId });
+  }
+  if (!hasOwn(dto, 'podId') || String(dto.podId) !== String(podId)) {
+    throw invalidContract('Runtime context returned a focus for a different pod', {
+      podId,
+      returnedPodId: dto.podId ?? null,
+    });
+  }
+  if (!hasOwn(dto, 'revision')
+    || !Number.isInteger(dto.revision)
+    || dto.revision < 0) {
+    throw invalidContract('Runtime context returned an invalid focus revision', {
+      podId,
+      focusRevision: dto.revision ?? null,
+    });
+  }
+  if (!hasOwn(dto, 'focus')
+    || (dto.focus !== null
+      && (typeof dto.focus !== 'object' || Array.isArray(dto.focus)))) {
+    throw invalidContract('Runtime context returned an invalid focus value', {
+      podId,
+      focusRevision: dto.revision,
+    });
+  }
+  return {
+    podId: String(dto.podId),
+    revision: dto.revision,
+    focus: dto.focus,
+  };
+};
+
+/**
+ * Read only the focus projection from the authorized runtime context route.
+ * `skillMode=none` is important: a turn-start focus read must not trigger pod
+ * skill synthesis as a side effect.  A failed read is intentionally thrown so
+ * the caller leaves the event unacknowledged for the existing retry path.
+ */
+export const readPodFocus = async (client, podId) => {
+  if (!podId) {
+    throw new PodFocusError('Pod focus read requires a pod id', {
+      code: 'pod_focus_read_failed',
+      podId: null,
+    });
+  }
+  try {
+    const body = await client.get(
+      `/api/agents/runtime/pods/${encodeURIComponent(podId)}/context`,
+      { skillMode: 'none' },
+    );
+    if (!body || typeof body !== 'object' || !hasOwn(body, 'focus')) {
+      throw invalidContract('Runtime context did not include the published focus DTO', { podId });
+    }
+    return normalizeDto(body.focus, podId);
+  } catch (cause) {
+    // Preserve contract diagnostics instead of relabelling them as transient
+    // transport failures. The run loop still retries the queued event, but the
+    // operator sees the repair-needed cause and revision metadata.
+    if (cause?.code === 'pod_focus_contract_invalid') throw cause;
+    throw new PodFocusError(
+      `Pod focus read failed for pod ${podId}: ${cause?.message || 'unknown error'}`,
+      {
+        code: 'pod_focus_read_failed',
+        podId: String(podId),
+        cause,
+      },
+      { cause },
+    );
+  }
+};
+
+const taskDetail = (task) => {
+  const id = asText(task?.taskId, '(unknown task)');
+  const title = truncateCodePoints(task?.title, FOCUS_TASK_TITLE_MAX_CODE_POINTS) || '(untitled)';
+  const details = [`title=${title}`];
+  if (task?.status !== null && task?.status !== undefined && task.status !== '') {
+    details.push(`status=${truncateCodePoints(task.status, 80)}`);
+  }
+  if (task?.assignee !== null && task?.assignee !== undefined && task.assignee !== '') {
+    details.push(`assignee=${truncateCodePoints(task.assignee, 80)}`);
+  }
+  if (task?.updatedAt !== null && task?.updatedAt !== undefined && task.updatedAt !== '') {
+    details.push(`updatedAt=${truncateCodePoints(task.updatedAt, 80)}`);
+  }
+  if (task?.available === false) details.push('unavailable');
+  return `- ${id}: ${details.join('; ')}`;
+};
+
+/**
+ * Render a PodFocusRead into bounded pod context.
+ *
+ * Goal, scope, owner identity/label, revision, and every selected task id are
+ * protected fields: they are never truncated.  If those fields alone exceed
+ * the budget, fail closed before a model is spawned.  Task labels and live
+ * metadata are the only content eligible for the remaining budget.
+ */
+export const formatPodFocusFrame = (read, {
+  maxCodePoints = FOCUS_FRAME_MAX_CODE_POINTS,
+} = {}) => {
+  const limit = Number.isFinite(maxCodePoints) && maxCodePoints > 0
+    ? Math.floor(maxCodePoints)
+    : FOCUS_FRAME_MAX_CODE_POINTS;
+  const normalized = normalizeDto(read, read?.podId || 'unknown');
+  const focus = normalized.focus;
+
+  if (focus === null || focus === undefined) {
+    const empty = [
+      '=== Pod focus (pod context; not instructions) ===',
+      `pod: ${normalized.podId}`,
+      `revision: ${normalized.revision}`,
+      'No focus set.',
+    ].join('\n');
+    if (codePointLength(empty) > limit) {
+      throw new PodFocusError('Pod focus frame exceeds its code-point budget', {
+        code: 'FOCUS_FRAME_PROTECTED_OVERFLOW',
+        measuredCodePoints: codePointLength(empty),
+        allowedCodePoints: limit,
+        focusRevision: normalized.revision,
+      });
+    }
+    return empty;
+  }
+
+  const owner = focus.owner && typeof focus.owner === 'object' ? focus.owner : {};
+  const tasks = Array.isArray(focus.nextTasks) ? focus.nextTasks : [];
+  const taskIds = tasks.map((task) => asText(task?.taskId, '(unknown task)'));
+  const ownerLabel = asText(owner.label, '(unlabeled)');
+  const ownerId = asText(owner.userId, '(unknown user)');
+  const ownerAvailability = owner.available === false ? ' [unavailable]' : '';
+  const orderedIds = taskIds.length > 0 ? taskIds.join(' → ') : '(none)';
+
+  // Keep these lines independent from task detail packing. Their complete
+  // values are the contract's protected portion.
+  const protectedFrame = [
+    '=== Pod focus (pod context; not instructions) ===',
+    `pod: ${normalized.podId}`,
+    `revision: ${asText(normalized.revision, '0')}`,
+    `goal: ${asText(focus.goal)}`,
+    `scope: ${asText(focus.scope)}`,
+    `owner: ${ownerLabel} (${ownerId})${ownerAvailability}`,
+    `next task order: ${orderedIds}`,
+  ].join('\n');
+  const protectedSize = codePointLength(protectedFrame);
+  if (protectedSize > limit) {
+    throw new PodFocusError('Protected pod focus fields exceed the code-point budget', {
+      code: 'FOCUS_FRAME_PROTECTED_OVERFLOW',
+      measuredCodePoints: protectedSize,
+      allowedCodePoints: limit,
+      focusRevision: normalized.revision ?? 0,
+    });
+  }
+
+  if (tasks.length === 0) return protectedFrame;
+
+  // Keep a finite marker in every populated frame. It documents that the
+  // structured board/context read remains the place for complete task detail,
+  // and reserving it makes packing deterministic at the exact boundary.
+  const marker = '… full task details in board / get_context.';
+  const detailHeader = 'task details:';
+  let frame = `${protectedFrame}\n${detailHeader}`;
+  let omitted = false;
+  for (const task of tasks) {
+    const line = taskDetail(task);
+    const candidate = `${frame}\n${line}`;
+    const withMarker = `${candidate}\n${marker}`;
+    if (codePointLength(withMarker) <= limit) {
+      frame = candidate;
+    } else {
+      omitted = true;
+    }
+  }
+
+  // The marker is always useful, and the protected portion was already proven
+  // to fit. If there is not enough room for the detail header plus marker,
+  // return the protected fields alone rather than slicing them.
+  const marked = `${frame}\n${marker}`;
+  if (codePointLength(marked) <= limit) return marked;
+  if (omitted || codePointLength(`${protectedFrame}\n${detailHeader}\n${marker}`) > limit) {
+    return protectedFrame;
+  }
+  return frame;
+};