@tt-a1i/hive 2.1.14 → 2.1.16

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable user-facing changes will be documented in this file.
 
+## 2.1.16 - 2026-07-08
+
+Codex resume context reliability.
+
+- Preserves a Codex worker's saved conversation pointer when a resumed start
+  exits because of a temporary CLI, configuration, or resource failure and the
+  underlying Codex session still exists.
+- Treats matching but temporarily unreadable Codex session files as
+  unverifiable instead of clearing the saved session too aggressively.
+- Clears truly stale or missing saved Codex session pointers after a failed
+  resume, so Hive can start fresh instead of repeatedly retrying a broken
+  session id.
+- Uses one shared session-existence path for supported native session stores,
+  keeping resume cleanup behavior consistent across CLI presets.
+
+## 2.1.15 - 2026-07-02
+
+Worker avatars, terminal rendering reliability, and clearer team report delivery.
+
+- Adds custom worker avatars, including upload, crop, validation, persistence,
+  and display across the team UI.
+- Keeps worker avatars out of CLI team-list responses while still showing them
+  in the browser workspace.
+- Improves terminal rendering under heavy output and reconnect/restore flows,
+  reducing stale or duplicated terminal frames.
+- Tightens Dream memory consolidation instructions so procedure references are
+  only used for real saved workflows, skills, procedures, templates, or docs.
+- Makes `team report` delivery wording more accurate when Hive accepts a report
+  and durable Orchestrator delivery is still in progress.
+- Adjusts Orchestrator guidance so accepted dispatches are usually left alone
+  until a member reports, reducing premature status checks or cancels.
+
 ## 2.1.14 - 2026-06-25
 
 Terminal focus and Dream memory reliability.

package/dist/src/cli/team.js

@@ -124,6 +124,23 @@ const GOAL_REPORT_USAGE = 'Usage: team goal report --goal <goal-id> --status pro
 const GOAL_REPORT_STATUSES = new Set(['progress', 'done', 'blocked', 'failed']);
 const usageFor = (command) => (command === 'status' ? STATUS_USAGE : REPORT_USAGE);
 const withUsage = (message, command) => `${message}\n\n${usageFor(command)}`;
+const printOrchestratorDeliveryWarning = (action, payload) => {
+    if (payload.delivery_state === 'delivered' || payload.delivery_state === 'delivering')
+        return;
+    if (payload.delivery_state === 'queued') {
+        const detail = payload.forward_error ? `: ${payload.forward_error}` : '.';
+        console.error(`Hive recorded the ${action}, but Orchestrator did not receive it in real time. It is queued for durable delivery${detail}`);
+        return;
+    }
+    if (payload.delivery_state === 'failed') {
+        const detail = payload.forward_error ? `: ${payload.forward_error}` : '.';
+        console.error(`Hive recorded the ${action}, but could not deliver it to Orchestrator or confirm durable queueing${detail}`);
+        return;
+    }
+    if (payload.forwarded === false && payload.forward_error) {
+        console.error(`Hive recorded the ${action}, but could not deliver it to Orchestrator in real time: ${payload.forward_error}`);
+    }
+};
 const readGeneratedProtocolGuide = (topic) => {
     const protocolPath = join(process.cwd(), '.hive', 'PROTOCOL.md');
     if (!existsSync(protocolPath))
@@ -1043,9 +1060,7 @@ export const runTeamCommand = async (argv) => {
             artifacts: report.artifacts,
         });
         const payload = (await response.json());
-        if (payload.forwarded === false && payload.forward_error) {
-            console.error(`Hive recorded the status update, but could not deliver it to Orchestrator in real time: ${payload.forward_error}`);
-        }
+        printOrchestratorDeliveryWarning('status update', payload);
         if (payload.pending_warning)
             console.error(payload.pending_warning);
         return;
@@ -1064,9 +1079,7 @@ export const runTeamCommand = async (argv) => {
             artifacts: report.artifacts,
         });
         const payload = (await response.json());
-        if (payload.forwarded === false && payload.forward_error) {
-            console.error(`Hive recorded the report, but could not deliver it to Orchestrator in real time: ${payload.forward_error}`);
-        }
+        printOrchestratorDeliveryWarning('report', payload);
         if (payload.pending_warning)
             console.error(payload.pending_warning);
         return;

package/dist/src/server/agent-run-bootstrap.d.ts

@@ -21,6 +21,9 @@ import { type SessionCaptureSnapshot } from './session-capture.js';
  */
 export declare const buildSpawnPathEnvEntry: (parentEnv: NodeJS.ProcessEnv, hiveBinDir: string, platform: NodeJS.Platform) => NodeJS.ProcessEnv;
 export declare const buildAgentRunBootstrap: (workspace: WorkspaceSummary, agentId: string, config: AgentLaunchConfigInput, sessionStore: AgentSessionStorePort, getCommandPreset: (id: string) => CommandPresetRecord | undefined, agent?: AgentSummary) => {
+    sessionCaptureDiscriminator: {
+        contentIncludes: string[];
+    } | undefined;
     sessionCaptureSnapshot: {
         discriminator?: {
             contentIncludes: string | readonly string[];

package/dist/src/server/agent-run-bootstrap.js

@@ -79,6 +79,7 @@ export const buildAgentRunBootstrap = (workspace, agentId, config, sessionStore,
         ? undefined
         : snapshotSessionIdsForCapture(workspace.path, startConfig.sessionIdCapture, discriminator);
     return {
+        sessionCaptureDiscriminator: discriminator,
         sessionCaptureSnapshot,
         startConfig,
         startEnv: {

package/dist/src/server/agent-run-exit-handler.js

@@ -1,10 +1,5 @@
-import { shouldClearResumedSessionOnExit } from './agent-exit-classification.js';
 import { completeLiveRun } from './agent-run-sync.js';
-const clearResumedSessionOnFailure = (context, exitCode) => {
-    if (shouldClearResumedSessionOnExit(exitCode) && context.startConfig.resumedSessionId) {
-        context.sessionStore.clearLastSessionId(context.workspace.id, context.agentId);
-    }
-};
+import { clearResumedSessionAfterExitIfStale } from './resumed-session-cleanup.js';
 export const handleAgentRunExit = (context, { exitCode, endedAt, runId }) => {
     context.registry.setPendingExitCode(runId, exitCode);
     const liveRun = context.registry.get(runId);
@@ -20,7 +15,7 @@ export const handleAgentRunExit = (context, { exitCode, endedAt, runId }) => {
     try {
         completeLiveRun(liveRun, exitCode, endedAt, context.store);
         if (!liveRun.userStopped)
-            clearResumedSessionOnFailure(context, exitCode);
+            clearResumedSessionAfterExitIfStale({ ...context, exitCode });
         context.onAgentExit(context.workspace.id, context.agentId);
         return true;
     }

package/dist/src/server/agent-run-start-context.d.ts

@@ -1,8 +1,9 @@
 import type { WorkspaceSummary } from '../shared/types.js';
-import type { PersistedAgentRun } from './agent-run-store.js';
+import type { AgentLaunchConfigInput, PersistedAgentRun } from './agent-run-store.js';
 import type { AgentSessionStorePort } from './agent-runtime-ports.js';
 import type { AgentTokenRegistry } from './agent-tokens.js';
 import type { LiveRunRegistry } from './live-run-registry.js';
+import type { SessionCaptureSnapshot } from './session-capture.js';
 export type PersistedRunStatus = PersistedAgentRun['status'];
 export interface AgentRunStarterStorePort {
     insertAgentRun: (runId: string, agentId: string, startedAt: number, pid: number | null, status?: PersistedRunStatus, exitCode?: number | null, endedAt?: number | null) => void;
@@ -13,10 +14,9 @@ export interface AgentRunExitContext {
     handledRunExits: Set<string>;
     onAgentExit: (workspaceId: string, agentId: string) => void;
     registry: LiveRunRegistry;
+    sessionCaptureDiscriminator?: SessionCaptureSnapshot['discriminator'];
     sessionStore: AgentSessionStorePort;
-    startConfig: {
-        resumedSessionId?: string | null;
-    };
+    startConfig: Pick<AgentLaunchConfigInput, 'resumedSessionId' | 'sessionIdCapture'>;
     store: AgentRunStarterStorePort;
     token: string;
     tokenRegistry: AgentTokenRegistry;

package/dist/src/server/agent-run-starter.js

@@ -1,4 +1,4 @@
-import { classifyCompletedRunStatus, shouldClearResumedSessionOnExit, } from './agent-exit-classification.js';
+import { classifyCompletedRunStatus } from './agent-exit-classification.js';
 import { buildAgentRunBootstrap, startAgentRunCapture } from './agent-run-bootstrap.js';
 import { handleAgentRunExit } from './agent-run-exit-handler.js';
 import { buildAgentStartupInstructions, buildWorkflowAgentStartupInstructions, } from './agent-startup-instructions.js';
@@ -7,13 +7,14 @@ import { ensureCodexDirectoryTrusted } from './codex-trust-store.js';
 import { FEATURE_FLAGS_ALL_OFF } from './feature-flags.js';
 import { createPostStartInputWriter, isInteractiveAgentCommand } from './post-start-input-writer.js';
 import { isResumeLaunchConfig } from './preset-launch-support.js';
+import { clearResumedSessionAfterExitIfStale } from './resumed-session-cleanup.js';
 import { normalizeExecutableToken } from './startup-command-parser.js';
 import { buildMemoryDigestSafely, logMemoryDigestInjection, rollbackMemoryDigestInjection, } from './team-memory-injection.js';
 export const createAgentRunStarter = ({ agentManager, registry, onAgentExit, store, sessionStore, tokenRegistry, getCommandPreset, getAgent, restartPolicy, getFlags, memoryInjection, }) => async (workspace, agentId, config, hivePort) => {
     if (!agentManager)
         throw new Error('Agent manager is required to start agents');
     const agent = getAgent?.(workspace.id, agentId);
-    const { sessionCaptureSnapshot, startConfig, startEnv } = buildAgentRunBootstrap(workspace, agentId, config, sessionStore, getCommandPreset, agent);
+    const { sessionCaptureDiscriminator, sessionCaptureSnapshot, startConfig, startEnv } = buildAgentRunBootstrap(workspace, agentId, config, sessionStore, getCommandPreset, agent);
     const handledRunExits = new Set();
     const abortedRunIds = new Set();
     const startedAt = Date.now();
@@ -23,6 +24,7 @@ export const createAgentRunStarter = ({ agentManager, registry, onAgentExit, sto
         handledRunExits,
         onAgentExit,
         registry,
+        sessionCaptureDiscriminator,
         sessionStore,
         startConfig,
         store,
@@ -105,9 +107,14 @@ export const createAgentRunStarter = ({ agentManager, registry, onAgentExit, sto
     if (run.status === 'error') {
         liveRun.status = classifyCompletedRunStatus(run.exitCode);
         store.updatePersistedRun(run.runId, liveRun.status, run.exitCode, Date.now());
-        if (startConfig.resumedSessionId && shouldClearResumedSessionOnExit(run.exitCode)) {
-            sessionStore.clearLastSessionId(workspace.id, agentId);
-        }
+        clearResumedSessionAfterExitIfStale({
+            agentId,
+            exitCode: run.exitCode,
+            sessionCaptureDiscriminator,
+            sessionStore,
+            startConfig,
+            workspace,
+        });
         tokenRegistry.revokeIfMatches(agentId, token);
         // Ensure §12 three-state: failed spawn must flip AgentSummary to stopped.
         onAgentExit(workspace.id, agentId);

package/dist/src/server/agent-startup-instructions.d.ts

@@ -9,6 +9,7 @@ export declare const buildAgentLegacyIdentityMarker: ({ agent, workspace, }: {
     workspace: WorkspaceSummary;
 }) => string;
 export declare const WORKER_STARTUP_READY_STATUS = "ready: startup prompt received; Hive CLI channel OK; waiting for dispatch.";
+export declare const REVIEWER_STARTUP_READY_STATUS = "ready: reviewer available as the final review gate. If review finds issues, have them fixed and send the work back to me until no issues remain before reporting completion to the user.";
 export declare const buildAgentStartupInstructions: ({ agent, memoryDigest, workspace, flags, }: {
     agent: AgentSummary;
     memoryDigest?: string | null | undefined;

package/dist/src/server/agent-startup-instructions.js

@@ -5,6 +5,8 @@ import { TASKS_RELATIVE_PATH } from './tasks-file.js';
 export const buildAgentSessionBindingMarker = ({ agent, workspace, }) => `Hive session binding: workspace_id=${workspace.id}; agent_id=${agent.id}`;
 export const buildAgentLegacyIdentityMarker = ({ agent, workspace, }) => `You are ${escapeHiveEnvelopeText(agent.name)} (${agent.role}) in workspace ${escapeHiveEnvelopeText(workspace.name)}.`;
 export const WORKER_STARTUP_READY_STATUS = 'ready: startup prompt received; Hive CLI channel OK; waiting for dispatch.';
+export const REVIEWER_STARTUP_READY_STATUS = 'ready: reviewer available as the final review gate. If review finds issues, have them fixed and send the work back to me until no issues remain before reporting completion to the user.';
+const getStartupReadyStatus = (agent) => agent.role === 'reviewer' ? REVIEWER_STARTUP_READY_STATUS : WORKER_STARTUP_READY_STATUS;
 export const buildAgentStartupInstructions = ({ agent, memoryDigest, workspace, flags = FEATURE_FLAGS_ALL_OFF, }) => {
     const { workflowsEnabled } = flags;
     const lines = [
@@ -35,7 +37,8 @@ export const buildAgentStartupInstructions = ({ agent, memoryDigest, workspace,
         lines.push('Available team commands:', '- team status "<finding>" [--artifact <path>]                     escalate a patrol finding to the Orchestrator', '- team status --stdin [--artifact <path>]                         same, body read from stdin', '- team recall "<query>" [--limit <n>] [--window <n>]               search prior team messages/reports in this workspace', '- team memory show <memory-id>                                     inspect a memory entry and its evidence', '- team memory search "<query>" [--limit <n>]                         search active workspace memory', '- team --help                                                     command syntax only', '', 'You observe only: no dispatches are ever assigned to you, and `team report` is not available to your role.', '', 'Hive sentinel boundaries:', ...getHiveTeamRules(agent, flags));
     }
     else {
-        lines.push('Available team commands:', '- team report "<result>" [--dispatch <id>] [--artifact <path>]    report done / failed / blocked', '- team report --stdin [--dispatch <id>] [--artifact <path>]       same, body read from stdin (multi-line / quotes / special chars)', '- team status "<state>" [--artifact <path>]                       progress / standby update at any time; never closes a dispatch', '- team status --stdin [--artifact <path>]                         same, body read from stdin', '- team recall "<query>" [--limit <n>] [--window <n>]               search prior team messages/reports in this workspace', '- team memory show <memory-id>                                     inspect a memory entry and its evidence', '- team memory search "<query>" [--limit <n>]                         search active workspace memory', '- team memory dream show <dream-run-id>                            inspect a pending Dream run only when the Orchestrator assigns memory review', '- team --help                                                     command syntax only; NOT a way to report', '', 'Startup handshake:', `- After reading this startup message, immediately run exactly once: \`team status "${WORKER_STARTUP_READY_STATUS}"\`.`, '- This readiness status tells the Orchestrator this member started successfully; it does not close any dispatch.', '- Do not use `team report` for startup readiness. Use `team report` only after you receive an assigned dispatch task.', '', 'Syntax notes:', '- The body is the first positional argument; flag order is free: `team report "result" --dispatch X` and `team report --dispatch X "result"` are both valid.', "- Long bodies (multi-line / quotes / shell metacharacters) always go through `--stdin`, piped in via your shell (POSIX: a quoted heredoc `<<'EOF' … EOF` to stop $var / backtick expansion; Windows cmd: `type body.txt |` or `< body.txt`; PowerShell: `Get-Content -Raw -Encoding utf8 body.txt |`). `--stdin` only reads from stdin and relies on no shell syntax of its own.", '- On error the CLI also prints USAGE — fix the arguments against it.', '', 'Hive member boundaries:', ...getHiveTeamRules(agent, flags));
+        const startupReadyStatus = getStartupReadyStatus(agent);
+        lines.push('Available team commands:', '- team report "<result>" [--dispatch <id>] [--artifact <path>]    report done / failed / blocked', '- team report --stdin [--dispatch <id>] [--artifact <path>]       same, body read from stdin (multi-line / quotes / special chars)', '- team status "<state>" [--artifact <path>]                       progress / standby update at any time; never closes a dispatch', '- team status --stdin [--artifact <path>]                         same, body read from stdin', '- team recall "<query>" [--limit <n>] [--window <n>]               search prior team messages/reports in this workspace', '- team memory show <memory-id>                                     inspect a memory entry and its evidence', '- team memory search "<query>" [--limit <n>]                         search active workspace memory', '- team memory dream show <dream-run-id>                            inspect a pending Dream run only when the Orchestrator assigns memory review', '- team --help                                                     command syntax only; NOT a way to report', '', 'Startup handshake:', `- After reading this startup message, immediately run exactly once: \`team status "${startupReadyStatus}"\`.`, '- This readiness status tells the Orchestrator this member started successfully; it does not close any dispatch.', '- Do not use `team report` for startup readiness. Use `team report` only after you receive an assigned dispatch task.', '', 'Syntax notes:', '- The body is the first positional argument; flag order is free: `team report "result" --dispatch X` and `team report --dispatch X "result"` are both valid.', "- Long bodies (multi-line / quotes / shell metacharacters) always go through `--stdin`, piped in via your shell (POSIX: a quoted heredoc `<<'EOF' … EOF` to stop $var / backtick expansion; Windows cmd: `type body.txt |` or `< body.txt`; PowerShell: `Get-Content -Raw -Encoding utf8 body.txt |`). `--stdin` only reads from stdin and relies on no shell syntax of its own.", '- On error the CLI also prints USAGE — fix the arguments against it.', '', 'Hive member boundaries:', ...getHiveTeamRules(agent, flags));
     }
     lines.push('', '</hive-message>', '');
     return lines.join('\n');

package/dist/src/server/hive-team-guidance.js

@@ -23,6 +23,7 @@ export const buildOrchestratorReminderTail = ({ workflowsEnabled }) => {
         '(a) `team list`, then `team send "<member-name>" "<task>"` to dispatch to a suitable existing member by name. Prefer user-created/user-managed members already in the current team; stale names fail. ' +
         `If no existing member fits, a member is stopped/queued/not prompt-ready, or independent branches need more members, report that condition and recommend what member the user may start or add; do not take a branch yourself. Use \`team spawn <role> [--cli <${BUILTIN_COMMAND_PRESET_CLI_LIST}>] [--ephemeral]\` only when the user explicitly authorizes it or workspace policy permits autonomous staffing for this task. ` +
         '(b) `team cancel --dispatch <id> "<reason>"` to close an obsolete dispatch. ' +
+        'Accepted dispatches should normally be left alone until the member reports. Do not cancel or send status checks unless progress is genuinely overdue or the user asks. ' +
         (workflowsEnabled
             ? '(c) `team workflow run --stdin` to fan out across 3+ members or run a staged review→fix — never a loop of `team send` (no barrier, no UI group, no stop button). (d) plain text only for clarification, status/final synthesis, or the explicitly allowed trivial check. '
             : '(c) plain text only for clarification, status/final synthesis, or the explicitly allowed trivial check. ') +
@@ -58,6 +59,7 @@ const CORE_ORCHESTRATOR_RULES = [
     'Do not keep a non-trivial parallel branch for yourself just to avoid dispatching.',
     'If a dispatch must be changed or cancelled, use `team cancel --dispatch <id> "<reason>"`, then resend the full updated task if needed.',
     'Each `team send` creates a separate dispatch and requires a separate `team report`.',
+    'Accepted dispatches should normally be left alone until the member reports. Do not cancel or send status checks unless progress is genuinely overdue or the user asks.',
     'Treat stopped, queued, delivery-failed, and prompt-readiness-timeout as current-team runtime conditions to report or retry, not proof that the member is unsuitable.',
     '`team spawn` is persistent by default. When authorized to create task-scoped capacity, prefer `--ephemeral` unless the user asks for persistent capacity.',
     'All Hive members in one workspace share the same filesystem root with no per-member isolation. Split dispatches so no two members edit the same files/modules at the same time; if work would collide, serialize it or assign one owner.',

package/dist/src/server/resumed-session-cleanup.d.ts

@@ -0,0 +1,15 @@
+import type { WorkspaceSummary } from '../shared/types.js';
+import type { AgentLaunchConfigInput } from './agent-run-store.js';
+import type { AgentSessionStorePort } from './agent-runtime-ports.js';
+import { type SessionCaptureSnapshot } from './session-capture.js';
+interface ResumedSessionCleanupInput {
+    agentId: string;
+    exitCode: number | null;
+    sessionCaptureDiscriminator?: SessionCaptureSnapshot['discriminator'];
+    sessionStore: AgentSessionStorePort;
+    startConfig: Pick<AgentLaunchConfigInput, 'resumedSessionId' | 'sessionIdCapture'>;
+    workspace: WorkspaceSummary;
+}
+export declare const shouldClearResumedSessionAfterExit: ({ exitCode, sessionCaptureDiscriminator, startConfig, workspace, }: Omit<ResumedSessionCleanupInput, "agentId" | "sessionStore">) => boolean;
+export declare const clearResumedSessionAfterExitIfStale: (input: ResumedSessionCleanupInput) => boolean;
+export {};

package/dist/src/server/resumed-session-cleanup.js

@@ -0,0 +1,26 @@
+import { shouldClearResumedSessionOnExit } from './agent-exit-classification.js';
+import { getCapturedSessionExistence } from './session-capture.js';
+export const shouldClearResumedSessionAfterExit = ({ exitCode, sessionCaptureDiscriminator, startConfig, workspace, }) => {
+    if (!shouldClearResumedSessionOnExit(exitCode))
+        return false;
+    const resumedSessionId = startConfig.resumedSessionId;
+    if (!resumedSessionId)
+        return false;
+    const capture = startConfig.sessionIdCapture;
+    if (!capture)
+        return true;
+    const capturedSessionExists = getCapturedSessionExistence(workspace.path, capture, resumedSessionId, sessionCaptureDiscriminator);
+    if (capturedSessionExists === undefined)
+        return false;
+    return !capturedSessionExists;
+};
+export const clearResumedSessionAfterExitIfStale = (input) => {
+    if (!shouldClearResumedSessionAfterExit(input))
+        return false;
+    if (input.sessionStore.getLastSessionId(input.workspace.id, input.agentId) !==
+        input.startConfig.resumedSessionId) {
+        return false;
+    }
+    input.sessionStore.clearLastSessionId(input.workspace.id, input.agentId);
+    return true;
+};

package/dist/src/server/route-types.d.ts

@@ -118,6 +118,7 @@ export interface CreateWorkspaceBody {
 }
 export interface CreateWorkerBody {
     autostart?: boolean;
+    avatar?: string | null;
     command_preset_id?: string | null;
     description?: string;
     name: string;

package/dist/src/server/routes-team.js

@@ -340,6 +340,7 @@ export const teamRoutes = [
                 status,
             });
             sendJson(response, 202, {
+                delivery_state: result.deliveryState,
                 dispatch_id: result.dispatch?.id ?? null,
                 forward_error: result.forwardError,
                 forwarded: result.forwarded,
@@ -351,6 +352,7 @@ export const teamRoutes = [
         else {
             const result = store.reportTask(projectId, fromAgentId, reportInput);
             sendJson(response, 202, {
+                delivery_state: result.deliveryState,
                 dispatch_id: result.dispatch?.id ?? null,
                 forward_error: result.forwardError,
                 forwarded: result.forwarded,
@@ -379,6 +381,7 @@ export const teamRoutes = [
             text: resultText,
         });
         sendJson(response, 202, {
+            delivery_state: result.deliveryState,
             dispatch_id: result.dispatch?.id ?? null,
             forward_error: result.forwardError,
             forwarded: result.forwarded,

package/dist/src/server/routes-workers.d.ts

@@ -0,0 +1,2 @@
+import type { RouteDefinition } from './route-types.js';
+export declare const workerRoutes: RouteDefinition[];

package/dist/src/server/routes-workers.js

@@ -0,0 +1,112 @@
+import { normalizeWorkerAvatar } from '../shared/worker-avatar.js';
+import { resolveCommandPresetLaunchConfig, resolveStartupCommandLaunchConfig, } from './agent-launch-resolver.js';
+import { BadRequestError } from './http-errors.js';
+import { autostartAgent } from './orchestrator-autostart.js';
+import { getDefaultRoleDescription } from './role-templates.js';
+import { getRequiredParam, readJsonBody, route, sendJson } from './route-helpers.js';
+import { enrichTeamList } from './team-list-enrichment.js';
+import { serializeTeamListItem } from './team-list-serializer.js';
+import { requireUiTokenFromRequest } from './ui-auth-helpers.js';
+import { resolveWorkspaceUiLanguage } from './workspace-ui-language.js';
+const getRuntimePort = (request) => String(request.socket.localPort ?? '');
+const readWorkerAvatar = (value) => {
+    try {
+        return normalizeWorkerAvatar(value);
+    }
+    catch (error) {
+        throw new BadRequestError(error instanceof Error ? error.message : String(error));
+    }
+};
+const getSerializedWorker = (workspaceId, workerId, store) => {
+    const worker = store.listWorkers(workspaceId).find((item) => item.id === workerId);
+    if (!worker) {
+        throw new Error(`Worker not found: ${workerId}`);
+    }
+    const [enriched] = enrichTeamList(workspaceId, store, [worker]);
+    if (!enriched)
+        throw new Error(`Worker enrichment failed: ${workerId}`);
+    return serializeTeamListItem(enriched, undefined, { includeAvatar: true });
+};
+export const workerRoutes = [
+    route('POST', '/api/workspaces/:workspaceId/workers', async ({ params, request, response, store }) => {
+        const workspaceId = getRequiredParam(response, params, 'workspaceId', 'Workspace id is required');
+        if (!workspaceId) {
+            return;
+        }
+        requireUiTokenFromRequest(request, store.validateUiToken, store.authorizeRemoteTunnelRequest);
+        const body = await readJsonBody(request);
+        const avatar = Object.hasOwn(body, 'avatar') ? readWorkerAvatar(body.avatar) : null;
+        const presetId = body.command_preset_id ?? null;
+        const startupCommand = typeof body.startup_command === 'string' ? body.startup_command : null;
+        const language = resolveWorkspaceUiLanguage(store.settings, workspaceId, body.ui_language);
+        const launchConfig = startupCommand?.trim()
+            ? resolveStartupCommandLaunchConfig(store.settings, startupCommand, presetId)
+            : presetId
+                ? resolveCommandPresetLaunchConfig(store.settings, presetId)
+                : undefined;
+        if (presetId && !startupCommand?.trim() && !launchConfig) {
+            throw new Error(`Command preset not found: ${presetId}`);
+        }
+        const worker = store.addWorker(workspaceId, {
+            ...body,
+            avatar,
+            description: typeof body.description === 'string'
+                ? body.description
+                : getDefaultRoleDescription(body.role, language),
+        });
+        if (launchConfig) {
+            try {
+                store.configureAgentLaunch(workspaceId, worker.id, launchConfig);
+            }
+            catch (error) {
+                store.deleteWorker(workspaceId, worker.id);
+                throw error;
+            }
+        }
+        const agentStart = body.autostart === true
+            ? await autostartAgent(store, workspaceId, worker.id, getRuntimePort(request), {
+                missingConfigError: 'No worker launch config available',
+            })
+            : { ok: false, error: null, run_id: null };
+        sendJson(response, 201, {
+            ...getSerializedWorker(workspaceId, worker.id, store),
+            agent_start: agentStart,
+        });
+    }),
+    route('DELETE', '/api/workspaces/:workspaceId/workers/:workerId', ({ params, request, response, store }) => {
+        const workspaceId = getRequiredParam(response, params, 'workspaceId', 'Workspace id and worker id are required');
+        const workerId = getRequiredParam(response, params, 'workerId', 'Workspace id and worker id are required');
+        if (!workspaceId || !workerId) {
+            return;
+        }
+        requireUiTokenFromRequest(request, store.validateUiToken, store.authorizeRemoteTunnelRequest);
+        store.deleteWorker(workspaceId, workerId);
+        response.statusCode = 204;
+        response.end();
+    }),
+    route('PATCH', '/api/workspaces/:workspaceId/workers/:workerId', async ({ params, request, response, store }) => {
+        const workspaceId = getRequiredParam(response, params, 'workspaceId', 'Workspace id and worker id are required');
+        const workerId = getRequiredParam(response, params, 'workerId', 'Workspace id and worker id are required');
+        if (!workspaceId || !workerId) {
+            return;
+        }
+        requireUiTokenFromRequest(request, store.validateUiToken, store.authorizeRemoteTunnelRequest);
+        const body = await readJsonBody(request);
+        const hasName = Object.hasOwn(body, 'name');
+        const hasAvatar = Object.hasOwn(body, 'avatar');
+        if (!hasName && !hasAvatar) {
+            sendJson(response, 400, { error: 'name or avatar is required' });
+            return;
+        }
+        if (hasName && typeof body.name !== 'string') {
+            sendJson(response, 400, { error: 'name must be a string' });
+            return;
+        }
+        const avatar = hasAvatar ? readWorkerAvatar(body.avatar) : undefined;
+        store.updateWorkerProfile(workspaceId, workerId, {
+            ...(hasName ? { name: body.name } : {}),
+            ...(hasAvatar ? { avatar: avatar ?? null } : {}),
+        });
+        sendJson(response, 200, getSerializedWorker(workspaceId, workerId, store));
+    }),
+];

package/dist/src/server/routes-workspaces.js

@@ -1,8 +1,6 @@
-import { resolveCommandPresetLaunchConfig, resolveStartupCommandLaunchConfig, } from './agent-launch-resolver.js';
 import { PtyInactiveError } from './http-errors.js';
-import { autostartAgent, autostartOrchestrator } from './orchestrator-autostart.js';
+import { autostartOrchestrator } from './orchestrator-autostart.js';
 import { seedOrchestratorLaunchConfig } from './orchestrator-launch.js';
-import { getDefaultRoleDescription } from './role-templates.js';
 import { getRequiredParam, readJsonBody, route, sendJson } from './route-helpers.js';
 import { authenticateCliAgent, requireCommandForRole } from './team-authz.js';
 import { enrichTeamList } from './team-list-enrichment.js';
@@ -15,7 +13,7 @@ import { resolveWorkspaceUiLanguage, writeWorkspaceUiLanguage } from './workspac
    into the team list payload. Display-only ages — no timeout or heartbeat is
    derived from them; `queued` rows age from createdAt (submittedAt is null
    until delivery). */
-const serializeTeamListWithOpenDispatches = (store, workspaceId) => {
+const serializeTeamListWithOpenDispatches = (store, workspaceId, options = {}) => {
     const now = Date.now();
     const workflowAgentId = getWorkflowAgentId(workspaceId);
     const openByWorker = new Map();
@@ -35,17 +33,7 @@ const serializeTeamListWithOpenDispatches = (store, workspaceId) => {
         });
         openByWorker.set(dispatch.toAgentId, list);
     }
-    return enrichTeamList(workspaceId, store, store.listWorkers(workspaceId)).map((worker) => serializeTeamListItem(worker, openByWorker.get(worker.id)));
-};
-const getSerializedWorker = (workspaceId, workerId, store) => {
-    const worker = store.listWorkers(workspaceId).find((item) => item.id === workerId);
-    if (!worker) {
-        throw new Error(`Worker not found: ${workerId}`);
-    }
-    const [enriched] = enrichTeamList(workspaceId, store, [worker]);
-    if (!enriched)
-        throw new Error(`Worker enrichment failed: ${workerId}`);
-    return serializeTeamListItem(enriched);
+    return enrichTeamList(workspaceId, store, store.listWorkers(workspaceId)).map((worker) => serializeTeamListItem(worker, openByWorker.get(worker.id), options));
 };
 const getRuntimePort = (request) => String(request.socket.localPort ?? '');
 export const workspaceRoutes = [
@@ -92,7 +80,7 @@ export const workspaceRoutes = [
             return;
         }
         requireUiTokenFromRequest(request, store.validateUiToken, store.authorizeRemoteTunnelRequest);
-        sendJson(response, 200, serializeTeamListWithOpenDispatches(store, workspaceId));
+        sendJson(response, 200, serializeTeamListWithOpenDispatches(store, workspaceId, { includeAvatar: true }));
     }),
     route('GET', '/api/workspaces/:workspaceId/team', ({ params, request, response, store }) => {
         const workspaceId = getRequiredParam(response, params, 'workspaceId', 'Workspace id is required');
@@ -114,75 +102,6 @@ export const workspaceRoutes = [
         store.drainReportOutbox(workspaceId, agent.id);
         sendJson(response, 200, serializeTeamListWithOpenDispatches(store, workspaceId));
     }),
-    route('POST', '/api/workspaces/:workspaceId/workers', async ({ params, request, response, store }) => {
-        const workspaceId = getRequiredParam(response, params, 'workspaceId', 'Workspace id is required');
-        if (!workspaceId) {
-            return;
-        }
-        requireUiTokenFromRequest(request, store.validateUiToken, store.authorizeRemoteTunnelRequest);
-        const body = await readJsonBody(request);
-        const presetId = body.command_preset_id ?? null;
-        const startupCommand = typeof body.startup_command === 'string' ? body.startup_command : null;
-        const language = resolveWorkspaceUiLanguage(store.settings, workspaceId, body.ui_language);
-        const launchConfig = startupCommand?.trim()
-            ? resolveStartupCommandLaunchConfig(store.settings, startupCommand, presetId)
-            : presetId
-                ? resolveCommandPresetLaunchConfig(store.settings, presetId)
-                : undefined;
-        if (presetId && !startupCommand?.trim() && !launchConfig) {
-            throw new Error(`Command preset not found: ${presetId}`);
-        }
-        const worker = store.addWorker(workspaceId, {
-            ...body,
-            description: typeof body.description === 'string'
-                ? body.description
-                : getDefaultRoleDescription(body.role, language),
-        });
-        if (launchConfig) {
-            try {
-                store.configureAgentLaunch(workspaceId, worker.id, launchConfig);
-            }
-            catch (error) {
-                store.deleteWorker(workspaceId, worker.id);
-                throw error;
-            }
-        }
-        const agentStart = body.autostart === true
-            ? await autostartAgent(store, workspaceId, worker.id, getRuntimePort(request), {
-                missingConfigError: 'No worker launch config available',
-            })
-            : { ok: false, error: null, run_id: null };
-        sendJson(response, 201, {
-            ...getSerializedWorker(workspaceId, worker.id, store),
-            agent_start: agentStart,
-        });
-    }),
-    route('DELETE', '/api/workspaces/:workspaceId/workers/:workerId', ({ params, request, response, store }) => {
-        const workspaceId = getRequiredParam(response, params, 'workspaceId', 'Workspace id and worker id are required');
-        const workerId = getRequiredParam(response, params, 'workerId', 'Workspace id and worker id are required');
-        if (!workspaceId || !workerId) {
-            return;
-        }
-        requireUiTokenFromRequest(request, store.validateUiToken, store.authorizeRemoteTunnelRequest);
-        store.deleteWorker(workspaceId, workerId);
-        response.statusCode = 204;
-        response.end();
-    }),
-    route('PATCH', '/api/workspaces/:workspaceId/workers/:workerId', async ({ params, request, response, store }) => {
-        const workspaceId = getRequiredParam(response, params, 'workspaceId', 'Workspace id and worker id are required');
-        const workerId = getRequiredParam(response, params, 'workerId', 'Workspace id and worker id are required');
-        if (!workspaceId || !workerId) {
-            return;
-        }
-        requireUiTokenFromRequest(request, store.validateUiToken, store.authorizeRemoteTunnelRequest);
-        const body = await readJsonBody(request);
-        if (typeof body.name !== 'string') {
-            sendJson(response, 400, { error: 'name is required' });
-            return;
-        }
-        store.renameWorker(workspaceId, workerId, body.name);
-        sendJson(response, 200, getSerializedWorker(workspaceId, workerId, store));
-    }),
     route('POST', '/api/workspaces/:workspaceId/user-input', async ({ params, request, response, store }) => {
         const workspaceId = getRequiredParam(response, params, 'workspaceId', 'Workspace id is required');
         if (!workspaceId) {

package/dist/src/server/routes.js

@@ -17,6 +17,7 @@ import { teamMemoryRoutes } from './routes-team-memory.js';
 import { teamRecallRoutes } from './routes-team-recall.js';
 import { uiRoutes } from './routes-ui.js';
 import { versionRoutes } from './routes-version.js';
+import { workerRoutes } from './routes-workers.js';
 import { workflowScheduleRoutes } from './routes-workflow-schedules.js';
 import { workflowRoutes } from './routes-workflows.js';
 import { workspaceMemoryRoutes } from './routes-workspace-memory.js';
@@ -25,6 +26,7 @@ import { workspaceUploadRoutes } from './routes-workspace-uploads.js';
 import { workspaceRoutes } from './routes-workspaces.js';
 const routes = [
     ...workspaceRoutes,
+    ...workerRoutes,
     ...scenarioRoutes,
     ...workspaceUploadRoutes,
     ...openWorkspaceRoutes,

package/dist/src/server/runtime-store-contract.d.ts

@@ -34,6 +34,11 @@ export interface RuntimeStore {
     addWorker: (workspaceId: string, input: WorkerInput) => AgentSummary;
     addWorkerWithLaunch: (workspaceId: string, input: WorkerInput, launchConfig: AgentLaunchConfigInput) => AgentSummary;
     deleteWorker: (workspaceId: string, workerId: string) => void;
+    updateWorkerProfile: (workspaceId: string, workerId: string, input: {
+        avatar?: string | null;
+        name?: string;
+    }) => AgentSummary;
+    updateWorkerAvatar: (workspaceId: string, workerId: string, avatar: string | null) => AgentSummary;
     renameWorker: (workspaceId: string, workerId: string, name: string) => AgentSummary;
     recordUserInput: (workspaceId: string, orchestratorId: string, text: string) => void;
     deliverUserInput: (workspaceId: string, orchestratorId: string, text: string) => Promise<void>;

package/dist/src/server/runtime-store.js

@@ -81,6 +81,8 @@ export const createRuntimeStore = (options = {}) => {
         },
         addWorker: (workspaceId, input) => services.workspaceStore.addWorker(workspaceId, input),
         addWorkerWithLaunch: workerMutations.addWorkerWithLaunch,
+        updateWorkerProfile: (workspaceId, workerId, input) => services.workspaceStore.updateWorkerProfile(workspaceId, workerId, input),
+        updateWorkerAvatar: (workspaceId, workerId, avatar) => services.workspaceStore.updateWorkerAvatar(workspaceId, workerId, avatar),
         renameWorker: (workspaceId, workerId, name) => services.workspaceStore.renameWorker(workspaceId, workerId, name),
         deleteWorker: workerMutations.deleteWorker,
         recordUserInput: services.teamOps.recordUserInput,

package/dist/src/server/session-capture-codex.d.ts

@@ -1,5 +1,6 @@
 export declare const getCodexHome: (pattern?: string, platform?: NodeJS.Platform) => string;
 export declare const readCodexSessionFirstLine: (filePath: string, maxBytes?: number) => string | null;
+export declare const getCodexSessionExistence: (cwd: string, sessionId: string, pattern?: string, platform?: NodeJS.Platform, codexHome?: string) => boolean | undefined;
 export declare const hasCodexSession: (cwd: string, sessionId: string, pattern?: string, platform?: NodeJS.Platform, codexHome?: string) => boolean;
 export declare const snapshotCodexSessionIds: (cwd: string, codexHome?: string, platform?: NodeJS.Platform) => Set<string>;
 export declare const captureCodexSessionId: (cwd: string, knownSessionIds: Set<string>, onCapture: (sessionId: string) => void, timeoutMs?: number, intervalMs?: number, codexHome?: string) => Promise<void>;