@ours.network/fleet 2.2.6 → 2.3.0

package/dist/rooms-tasks/add-member.js

@@ -5,13 +5,13 @@ import { join } from 'node:path';
 import { replaceFileAtomically, withFileLock } from '../atomic-file.js';
 import { canonicalJson } from '../canonical-json.js';
 import { stateRoot } from '../paths.js';
-import { getTask, TaskStateError } from './task-state.js';
+import { allocateTaskMemberNames, getTask, TaskStateError } from './task-state.js';
 import { getRoomRecord } from './room-state.js';
 import { prepareExecutionPlan } from './member-overrides.js';
 import { sealTemplateSnapshot } from './templates.js';
-import { provisionMembers } from './provision.js';
+import { assertMemberNameAvailable, provisionMembers } from './provision.js';
 import { EMPTY_TASK_LAYOUT, EMPTY_TASK_ROOM } from './empty-layout.js';
-import { layoutOwnedMemberName } from './layout-member-retirement.js';
+import { allocateLayoutMemberName } from './layout-member-retirement.js';
 import { validLayoutKey } from './layout-config.js';
 export class MemberAdditionRejected extends TaskStateError {
     accepted = false;
@@ -71,7 +71,11 @@ export async function requestMemberAddition(input) {
                 }
             })();
             const receipt = { taskId, requestId: r.requestId,
-                roleId: layoutOwnedMemberName(task.layout.run_id, r.slot), hash, state: 'running' };
+                roleId: allocateLayoutMemberName(task.layout.run_id, r.slot, [
+                    { label: r.role, source: 'role_override' },
+                    { label: input.cfg.agentTemplateRoleRefs?.[r.agentTemplate], source: 'template_ref' },
+                    { label: r.slot, source: 'participant_key' }
+                ]), hash, state: 'running' };
             const save = () => { replaceFileAtomically(path, JSON.stringify(receipt) + '\n', 0o600); publishFleetResourceCommit(path); };
             save();
             running.add(path);
@@ -89,7 +93,14 @@ export async function requestMemberAddition(input) {
         if (!room || !['active', 'review'].includes(task.state) || task.terminal_intent || room.state !== 'active'
             || room.task_id !== taskId || room.room_identity_cid !== task.room_identity_cid)
             throw new MemberAdditionRejected('Adding an agent requires an active task room');
-        const roleId = `${taskId.slice(0, 8)}-${r.slot}-1`;
+        // Keyed tasks take the next durable role ordinal; unkeyed tasks keep the legacy one-per-slot name.
+        const allocationKey = `add:${r.requestId}`;
+        const roleId = allocateTaskMemberNames(taskId, [{ allocationKey, candidates: [
+                    { label: r.role, source: 'role_override' },
+                    { label: input.cfg.agentTemplateRoleRefs?.[r.agentTemplate], source: 'template_ref' },
+                    { label: r.role, source: 'room_role' }, { label: r.slot, source: 'slot' }
+                ] }], assertMemberNameAvailable)?.[0]
+            ?? `${taskId.slice(0, 8)}-${r.slot}-1`;
         if (room.member_seats.some(s => s.role_name === roleId))
             throw new MemberAdditionRejected('This member slot already exists');
         const plan = (() => {
@@ -107,7 +118,7 @@ export async function requestMemberAddition(input) {
         save();
         running.add(path);
         void (input.provision ?? provisionMembers)({ cfg: input.cfg, cowork: input.cowork, configPath: input.configPath, binPath: input.binPath,
-            taskId, roomId: room.room_id, template, goal: task.title, brief: task.brief, append: true }).then(result => {
+            taskId, roomId: room.room_id, template, goal: task.title, brief: task.brief, append: true, allocationKey }).then(result => {
             const seat = result.member_seats.find(s => s.role_name === roleId);
             receipt.state = seat?.seat_state === 'active' && getTask(taskId).member_roles.some(m => m.name === roleId) ? 'succeeded' : 'attention';
             if (receipt.state === 'attention')

package/dist/rooms-tasks/cli.js

@@ -39,7 +39,7 @@ function cliAnonymousOverride(argv) {
         throw new Error('--anonymous and --no-anonymous are mutually exclusive');
     return enabled ? true : disabled ? false : undefined;
 }
-import { getTask, getDeletingTask, TaskStateError, reviewRevision, } from './task-state.js';
+import { getTask, getDeletingTask, resolveTaskRef, TaskStateError, reviewRevision, } from './task-state.js';
 import { getRoomRecord, RoomStateError, } from './room-state.js';
 import { createCoworkAdapter } from './cowork-adapter.js';
 import { markdownCode, markdownProse, renderMarkdownFailure, renderMarkdownList, renderMarkdownResult, roomStatus, taskStatus, } from './markdown.js';
@@ -212,6 +212,17 @@ function isKnownRoomStateMessage(message) {
         new RegExp(`^room ${SAFE_ID_WORD} close cannot move backward to [A-Za-z_]+$`, 'u'),
     ].some(pattern => pattern.test(message));
 }
+/** Canonical ID for a CLI task argument holding an ID or a mission key. */
+function cliTaskRef(ref, json) {
+    try {
+        return resolveTaskRef(ref);
+    }
+    catch (error) {
+        if (json)
+            die(error);
+        dieTaskRoom(error);
+    }
+}
 function dieTaskRoom(e) {
     if (e instanceof TaskRoomApplicationError)
         e = taskRoomPublicError(e.code, e.fields);
@@ -282,7 +293,7 @@ function dieTaskRoom(e) {
 }
 const taskListMarkdown = (tasks, title = 'Tasks') => renderMarkdownList({
     icon: '📋', title, empty: 'No tasks found.',
-    records: tasks.map(t => `${taskStatus(t.state)} ${markdownCode(t.task_id)} — ${markdownProse(t.title)}`
+    records: tasks.map(t => `${taskStatus(t.state)} ${t.key ? `${markdownCode(t.key)} ` : ''}${markdownCode(t.task_id)} — ${markdownProse(t.title)}`
         + ` — List ${markdownCode(t.list_name ?? 'default')}`
         + (t.deletion?.status === 'pending' ? ' — Deletion pending'
             + (t.deletion.error ? `: ${markdownProse(t.deletion.error)}` : '') : '')
@@ -295,6 +306,7 @@ const taskActionMarkdown = (title, task, fields = []) => {
     return renderMarkdownResult({
         icon: '📋', title,
         fields: [
+            ...(task.key ? [{ label: 'Key', value: task.key, kind: 'code' }] : []),
             { label: 'ID', value: task.task_id, kind: 'code' },
             { label: 'Status', value: taskStatus(task.state), kind: 'markdown' },
             { label: 'List', value: task.list_name ?? 'default', kind: 'code' },
@@ -800,16 +812,55 @@ export function registerTaskCommands(parent, cOpt) {
         }
     });
     taskCmd.command('list-create <name>')
-        .description('create a named task list')
+        .description('create a named task list; its mission keys read <PREFIX>-1, <PREFIX>-2, ...')
+        .option('--prefix <prefix>', 'mission key prefix: 1-6 Latin letters or digits starting with a letter (default: suggested from the name)')
         .option('--json', 'JSON output')
         .action(async (name, opts) => {
         try {
-            const list = await taskRoomService().createTaskList({ actor: { kind: 'local_control', surface: 'cli' }, name });
+            const list = await taskRoomService().createTaskList({ actor: { kind: 'local_control', surface: 'cli' }, name, prefix: opts.prefix });
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, list }, null, 2));
+                return;
+            }
+            console.log(renderMarkdownResult({ icon: '📚', title: 'Task list created', fields: [{ label: 'Name', value: list.name },
+                    { label: 'Prefix', value: list.prefix ?? '', kind: 'code' }] }));
+        }
+        catch (e) {
+            if (opts.json)
+                die(e);
+            dieTaskRoom(e);
+        }
+    });
+    taskCmd.command('migrate-keys')
+        .description('assign mission keys and frozen agent names to tasks created before mission keys (idempotent)')
+        .option('--json', 'JSON output')
+        .action(async (opts) => {
+        try {
+            await taskRoomService().prepareMissionKeys();
+            if (opts.json) {
+                console.log(JSON.stringify({ schema_version: 1, migrated: true }, null, 2));
+                return;
+            }
+            console.log(renderMarkdownResult({ icon: '🔑', title: 'Mission keys are up to date', fields: [] }));
+        }
+        catch (e) {
+            if (opts.json)
+                die(e);
+            dieTaskRoom(e);
+        }
+    });
+    taskCmd.command('list-prefix <name> <prefix>')
+        .description('change the prefix for new mission keys of a list; issued keys never change')
+        .option('--json', 'JSON output')
+        .action(async (name, prefix, opts) => {
+        try {
+            const list = await taskRoomService().setTaskListPrefix({ actor: { kind: 'local_control', surface: 'cli' }, name, prefix });
             if (opts.json) {
                 console.log(JSON.stringify({ schema_version: 1, list }, null, 2));
                 return;
             }
-            console.log(renderMarkdownResult({ icon: '📚', title: 'Task list created', fields: [{ label: 'Name', value: list.name }] }));
+            console.log(renderMarkdownResult({ icon: '📚', title: 'Task list prefix changed', fields: [{ label: 'Name', value: list.name },
+                    { label: 'Prefix', value: list.prefix ?? '', kind: 'code' }] }));
         }
         catch (e) {
             if (opts.json)
@@ -859,6 +910,7 @@ export function registerTaskCommands(parent, cOpt) {
         .requiredOption('--list <name>', 'destination task list')
         .option('--json', 'JSON output')
         .action(async (id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const task = await taskRoomService().moveTask({ actor: { kind: 'local_control', surface: 'cli' }, taskId: id, list: opts.list });
             if (opts.json) {
@@ -877,6 +929,7 @@ export function registerTaskCommands(parent, cOpt) {
         .description('show task details')
         .option('--json', 'JSON output')
         .action(async (id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const service = taskRoomService(opts.configuration);
             const { task: t, orchestration: room } = service.getTask(id);
@@ -892,6 +945,7 @@ export function registerTaskCommands(parent, cOpt) {
             console.log(renderMarkdownResult({
                 icon: '📋', title: 'Task details',
                 fields: [
+                    ...(t.key ? [{ label: 'Key', value: t.key, kind: 'code' }] : []),
                     { label: 'ID', value: t.task_id, kind: 'code' },
                     { label: 'Title', value: t.title },
                     { label: 'Status', value: taskStatus(t.state), kind: 'markdown' },
@@ -932,6 +986,7 @@ export function registerTaskCommands(parent, cOpt) {
         .description('resume proven stopped task members in-place; never create identities or replay invites')
         .option('--json', 'JSON output')
         .action(async (id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const { recoverTaskMembers } = await import('./recovery.js');
             const task = getTask(id), cfg = loadConfig(opts.configuration);
@@ -969,6 +1024,7 @@ export function registerTaskCommands(parent, cOpt) {
         .option('--no-loops', 'disable loops for current member')
         .option('--json', 'JSON output')
         .action(async (id, opts, command) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const service = taskRoomService(opts.configuration);
             const t = await service.startTask({
@@ -1002,6 +1058,7 @@ export function registerTaskCommands(parent, cOpt) {
         .requiredOption('--reason <reason>', 'blocking reason')
         .option('--json', 'JSON output')
         .action((id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const previous = getTask(id).state;
             const t = taskRoomService().blockTask({
@@ -1024,6 +1081,7 @@ export function registerTaskCommands(parent, cOpt) {
         .description('unblock a task')
         .option('--json', 'JSON output')
         .action((id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const prior = getTask(id);
             const previous = prior.state;
@@ -1047,6 +1105,7 @@ export function registerTaskCommands(parent, cOpt) {
         .description('move a task to review')
         .option('--json', 'JSON output')
         .action((id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const previous = getTask(id).state;
             const t = taskRoomService().reviewTask({
@@ -1072,6 +1131,7 @@ export function registerTaskCommands(parent, cOpt) {
         .option('--request-key <key>', 'retry key: repeating the same key and text returns the original entry')
         .option('--json', 'JSON output')
         .action((id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             if (opts.text !== undefined && opts.textFile !== undefined)
                 throw new Error('use --text or --text-file, not both');
@@ -1112,6 +1172,7 @@ export function registerTaskCommands(parent, cOpt) {
         .option('--expected-revision <n>', 'package revision you last read; --clear is refused if it changed since')
         .option('--json', 'JSON output')
         .action(async (id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             if (opts.markdown !== undefined && opts.markdownFile !== undefined)
                 throw new Error('use --markdown or --markdown-file, not both');
@@ -1165,6 +1226,7 @@ export function registerTaskCommands(parent, cOpt) {
         .option('--summary-file <path>', 'completion summary from file')
         .option('--json', 'JSON output')
         .action(async (id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const previous = getTask(id).state;
             let summary = opts.summary;
@@ -1208,6 +1270,7 @@ export function registerTaskCommands(parent, cOpt) {
         try {
             if (id !== confirmId)
                 throw taskRoomPublicError('task_confirmation_mismatch');
+            id = resolveTaskRef(id);
             const previous = getTask(id).state;
             const plan = await taskRoomService(opts.configuration).cancelTask({
                 actor: { kind: 'local_control', surface: 'cli' }, taskId: id,
@@ -1246,6 +1309,8 @@ export function registerTaskCommands(parent, cOpt) {
         try {
             if (id !== confirmId)
                 throw taskRoomPublicError('task_confirmation_mismatch');
+            // A deleted key still maps to its canonical ID, so a repeated delete stays idempotent.
+            id = resolveTaskRef(id, { allowDeleted: true });
             const accepted = await taskRoomService(opts.configuration).requestTaskDeletion({
                 actor: { kind: 'local_control', surface: 'cli' }, taskId: id,
             });
@@ -1293,6 +1358,7 @@ export function registerTaskCommands(parent, cOpt) {
         .description('internal: settle a previously accepted task terminal intent')
         .option('--json', 'JSON output')
         .action(async (id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const app = taskRoomService(opts.configuration);
             const t = await app.settleTask({
@@ -1318,6 +1384,7 @@ export function registerTaskCommands(parent, cOpt) {
         .description('internal: continue an accepted room-provisioning operation')
         .option('--json', 'JSON output')
         .action(async (id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             await withFileLock(taskProvisioningWorkerLockPath(id), async () => {
                 const app = taskRoomService(opts.configuration);
@@ -1352,6 +1419,7 @@ export function registerTaskCommands(parent, cOpt) {
         .option('--json', 'JSON output')
         .option('--operation-id <id>', 'accepted operation ID; status updates apply only while it is current')
         .action(async (id, operation, room, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             if (!['start', 'open', 'close-room', 'close'].includes(operation))
                 throw new Error(`unknown layout operation: ${operation}`);
@@ -1371,6 +1439,7 @@ export function registerTaskCommands(parent, cOpt) {
         .description('internal: settle a previously accepted task deletion')
         .option('--json', 'JSON output')
         .action(async (id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const app = taskRoomService(opts.configuration);
             const result = await app.settleTaskDeletion({
@@ -1416,6 +1485,7 @@ export function registerTaskCommands(parent, cOpt) {
         .option('--no-loops', 'disable loops for current member')
         .option('--json', 'JSON output')
         .action(async (id, opts, command) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const previous = getTask(id).state;
             console.error('warning: `fleet task work` is deprecated; use `fleet task start`');
@@ -1463,6 +1533,7 @@ export function registerTaskCommands(parent, cOpt) {
         .option('--summary-file <path>', 'completion summary from file')
         .option('--json', 'JSON output')
         .action(async (id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const previous = getTask(id).state;
             let summary = opts.summary;
@@ -1581,6 +1652,7 @@ export function registerRoomCommands(parent, cOpt) {
         .description('show room details')
         .option('--json', 'JSON output')
         .action(async (id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const { room: cowork, orchestration: r } = await taskRoomService(opts.configuration).getRoomDetail(id);
             if (opts.json) {
@@ -1620,6 +1692,7 @@ export function registerRoomCommands(parent, cOpt) {
         .description('open room in Cowork local console')
         .option('--json', 'JSON output')
         .action(async (id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const { room, orchestration } = await taskRoomService(opts.configuration).getRoomDetail(id);
             const url = `http://localhost:4460/room/${id}`;
@@ -1646,6 +1719,7 @@ export function registerRoomCommands(parent, cOpt) {
         .description('show room members')
         .option('--json', 'JSON output')
         .action(async (id, opts) => {
+        id = cliTaskRef(id, opts.json);
         try {
             const { orchestration: r, members } = await taskRoomService(opts.configuration).getRoomMembers(id);
             if (opts.json) {

package/dist/rooms-tasks/config.js

@@ -1,3 +1,4 @@
+import { normalizeMissionPrefix } from './mission-keys.js';
 import { existsSync, readFileSync } from 'node:fs';
 import { isAbsolute } from 'node:path';
 import { createHash } from 'node:crypto';
@@ -105,7 +106,17 @@ export function validateTasksConfig(raw, path) {
         throw new RoomsTasksConfigError(path, 'tasks.close_room_on_done: must be a boolean');
     if (raw.retain_completed_for !== undefined && typeof raw.retain_completed_for !== 'string')
         throw new RoomsTasksConfigError(path, 'tasks.retain_completed_for: must be a duration string');
+    let defaultPrefix;
+    if (raw.default_prefix !== undefined) {
+        try {
+            defaultPrefix = normalizeMissionPrefix(raw.default_prefix);
+        }
+        catch (error) {
+            throw new RoomsTasksConfigError(path, `tasks.default_prefix: ${error.message}`);
+        }
+    }
     return {
+        ...(defaultPrefix ? { default_prefix: defaultPrefix } : {}),
         default_room_template: raw.default_room_template,
         create_mode: createMode,
         close_room_on_done: raw.close_room_on_done,

package/dist/rooms-tasks/layout-member-retirement.d.ts

@@ -1,7 +1,22 @@
 import { type TempLifecycleDeps } from '../temp-lifecycle.js';
+import type { LabelCandidate } from './member-naming.js';
 import type { LayoutInstance, RoomLayoutState } from './layout.js';
 import type { RoomMemberSeat } from './types.js';
+/** Name a pre-mission-key layout run derived for every participant; still the recovery fallback. */
+export declare function legacyLayoutMemberName(runId: string, key: string): string;
+/**
+ * The owned name for a layout participant: the durable allocation recorded on
+ * its task (fresh or frozen), else the legacy hash. This is the ownership
+ * proof retirement checks before its launch, CID and provenance fences.
+ */
 export declare function layoutOwnedMemberName(runId: string, key: string): string;
+/**
+ * Allocate (or reuse) the participant's durable role-scoped name before it is
+ * spawned. Every launch goes through the task allocator, which confirms a
+ * reused allocation is durable before returning it; retirement uses the
+ * side-effect-free layoutOwnedMemberName instead.
+ */
+export declare function allocateLayoutMemberName(runId: string, key: string, candidates: LabelCandidate[]): string;
 /** Retire a local layout factory result, never a borrowed binding. The runtime
  * instance and CID fence replacement supervisors even when already stopped.
  */

package/dist/rooms-tasks/layout-member-retirement.js

@@ -9,6 +9,8 @@ import { agentDir, stateRoot } from '../paths.js';
 import { readTempSupervisor, secureStoppedTempArchive, stopTempSupervisor, tempArchiveForCreationAction } from '../temp-lifecycle.js';
 import { assertMemberIdentityAbsent, removeExactMemberIdentity, waitForLivenessAbsent } from './close.js';
 import { assertMemberNotPermanent } from './member-ownership.js';
+import { allocateTaskMemberNames, recordedMemberName } from './task-state.js';
+import { assertMemberNameAvailable } from './provision.js';
 import { retireTaskMemberService } from './task-service-retirement.js';
 function proof(path) {
     const stat = lstatSync(path);
@@ -16,9 +18,32 @@ function proof(path) {
         throw Error('LAYOUT_MEMBER_UNSAFE_PROOF');
     return readFileSync(path, 'utf8');
 }
-export function layoutOwnedMemberName(runId, key) {
+/** Name a pre-mission-key layout run derived for every participant; still the recovery fallback. */
+export function legacyLayoutMemberName(runId, key) {
     return `layout-${createHash('sha256').update(runId + ':' + key).digest('hex').slice(0, 16)}`;
 }
+const taskOfRun = (runId) => runId.startsWith('task-') && /^task-[0-9a-z]{9}[0-9a-f]{8}$/.test(runId) ? runId.slice(5) : undefined;
+/**
+ * The owned name for a layout participant: the durable allocation recorded on
+ * its task (fresh or frozen), else the legacy hash. This is the ownership
+ * proof retirement checks before its launch, CID and provenance fences.
+ */
+export function layoutOwnedMemberName(runId, key) {
+    const taskId = taskOfRun(runId);
+    return (taskId && recordedMemberName(taskId, `layout:${runId}:${key}`)) || legacyLayoutMemberName(runId, key);
+}
+/**
+ * Allocate (or reuse) the participant's durable role-scoped name before it is
+ * spawned. Every launch goes through the task allocator, which confirms a
+ * reused allocation is durable before returning it; retirement uses the
+ * side-effect-free layoutOwnedMemberName instead.
+ */
+export function allocateLayoutMemberName(runId, key, candidates) {
+    const taskId = taskOfRun(runId);
+    if (!taskId)
+        return legacyLayoutMemberName(runId, key);
+    return allocateTaskMemberNames(taskId, [{ allocationKey: `layout:${runId}:${key}`, candidates }], assertMemberNameAvailable)?.[0] ?? legacyLayoutMemberName(runId, key);
+}
 function assertOwned(instance, runId, key) {
     if (instance.remote || !instance.agent || instance.temporary !== true
         || instance.agent !== layoutOwnedMemberName(runId, key) || instance.supervisor !== stateRoot())

package/dist/rooms-tasks/layout-service.d.ts

@@ -1,6 +1,7 @@
 import { type AgentTemplateDefinition } from '../config.js';
 import { RoomLayout, type LayoutInstance, type LayoutSupervisor, type RoomLayoutState } from './layout.js';
 import { type RoomLayoutDefinition } from './layout-config.js';
+import type { LabelCandidate } from './member-naming.js';
 export declare class NativeLayoutSupervisor implements LayoutSupervisor {
     private configPath;
     private runId;
@@ -12,7 +13,7 @@ export declare class NativeLayoutSupervisor implements LayoutSupervisor {
     inspect(agent: string, temporary: boolean): Promise<LayoutInstance>;
     private call;
     verify(i: LayoutInstance): Promise<void>;
-    spawn(key: string, template: string, snapshot?: AgentTemplateDefinition): Promise<LayoutInstance>;
+    spawn(key: string, template: string, snapshot?: AgentTemplateDefinition, labels?: LabelCandidate[]): Promise<LayoutInstance>;
     join(i: LayoutInstance, invite: string, roomCid: string, membership?: {
         roomId: string;
         role: string;

package/dist/rooms-tasks/layout-service.js

@@ -13,7 +13,7 @@ import { createCoworkAdapter } from './cowork-adapter.js';
 import { callRemoteLayoutBinding } from './layout-binding-client.js';
 import { readClientProfile } from '../client-profile.js';
 import { tempSupervisorLiveness } from '../temp-lifecycle.js';
-import { layoutOwnedMemberName, retireOwnedLayoutMember } from './layout-member-retirement.js';
+import { allocateLayoutMemberName, retireOwnedLayoutMember, } from './layout-member-retirement.js';
 import { EMPTY_TASK_LAYOUT, emptyTaskLayout } from './empty-layout.js';
 export class NativeLayoutSupervisor {
     configPath;
@@ -48,11 +48,13 @@ export class NativeLayoutSupervisor {
         return this.request(i.agent, i.temporary, { ...request, instance: i });
     }
     async verify(i) { await this.call(i, { action: 'verify' }); }
-    async spawn(key, template, snapshot) {
+    async spawn(key, template, snapshot, labels = []) {
         const definition = snapshot ?? this.templates[template];
         if (!definition)
             throw Error(`agent template not found in run snapshot: ${template}`);
-        const name = layoutOwnedMemberName(this.runId, key);
+        // The first allocation is durable on the task; recovery reuses it once its durability is confirmed.
+        // Labels come from the run snapshot only.
+        const name = allocateLayoutMemberName(this.runId, key, labels);
         const taskId = this.runId.startsWith('task-') ? this.runId.slice(5) : undefined;
         const task = taskId ? (await import('./task-state.js')).getTask(taskId) : undefined;
         if (task && task.layout?.run_id !== this.runId)
@@ -196,6 +198,7 @@ export class RoomLayoutService {
         const source = scope.source ?? this.definition(name);
         const definition = scope.definition ? scope.definition(structuredClone(source)) : source;
         const templates = {};
+        const roleLabels = {};
         for (const [key, participant] of Object.entries(definition.participants)) {
             if (bindings[key] || !participant.agent_template)
                 continue;
@@ -203,9 +206,12 @@ export class RoomLayoutService {
             if (!template)
                 throw Error(`agent template not found: ${participant.agent_template}`);
             templates[participant.agent_template] = { ...structuredClone(template), ...(scope.cwd ? { cwd: scope.cwd } : {}) };
+            const roleRef = cfg.agentTemplateRoleRefs?.[participant.agent_template];
+            if (roleRef)
+                roleLabels[participant.agent_template] = roleRef;
         }
         const engine = this.engine(id);
-        await engine.create(definition, layoutSupervisorId(), bindings, templates);
+        await engine.create(definition, layoutSupervisorId(), bindings, templates, roleLabels);
         return { id, state: engine.snapshot() };
     }
 }

package/dist/rooms-tasks/layout.d.ts

@@ -53,7 +53,7 @@ export interface LayoutSupervisor {
     id: string;
     /** Must verify current launch, CID, live session and standalone ownership. */
     verify(instance: LayoutInstance): Promise<void>;
-    spawn(key: string, template: string, definition?: import('../config.js').AgentTemplateDefinition): Promise<LayoutInstance>;
+    spawn(key: string, template: string, definition?: import('../config.js').AgentTemplateDefinition, labels?: import('./member-naming.js').LabelCandidate[]): Promise<LayoutInstance>;
     join(instance: LayoutInstance, invite: string, roomCid: string, membership?: {
         roomId: string;
         role: string;
@@ -84,6 +84,8 @@ export interface RoomLayoutState {
     agent_templates?: Record<string, import('../config.js').AgentTemplateDefinition>;
     definition: LayoutDefinition;
     controller: string;
+    /** Named Role of each source Agent Template, sealed at run creation; later config edits never rename members. */
+    role_labels?: Record<string, string>;
     participants: Record<string, ParticipantState>;
     rooms: Record<string, RoomState>;
     /** Runtime additions leave the pinned source definition unchanged. */
@@ -115,7 +117,7 @@ export declare class RoomLayout {
     snapshot(): RoomLayoutState;
     private save;
     private verify;
-    create(definition: LayoutDefinition, controller: string, bindings?: Record<string, LayoutInstance>, agentTemplates?: RoomLayoutState['agent_templates']): Promise<void>;
+    create(definition: LayoutDefinition, controller: string, bindings?: Record<string, LayoutInstance>, agentTemplates?: RoomLayoutState['agent_templates'], roleLabels?: RoomLayoutState['role_labels']): Promise<void>;
     private checkOwnerRoles;
     private operation;
     private mutation;

package/dist/rooms-tasks/layout.js

@@ -16,6 +16,21 @@ function need(ok, message) { if (!ok)
 function instanceKey(definition, participant, room) {
     return definition.participants[participant]?.instance_scope === 'room' ? `${room}:${participant}` : participant;
 }
+/**
+ * Naming labels for a participant, after its template's named Role (added by
+ * the supervisor): a runtime-added member's room role, else its room role when
+ * every room it joins agrees (or its own room when room-scoped), else its key.
+ */
+function participantLabels(s, participant, template, room) {
+    const added = s.additional_members?.[participant];
+    // Runs created before sealing have no role_labels: fall back to room roles, never to current config.
+    const sealed = s.role_labels && own(s.role_labels, template) ? s.role_labels[template] : undefined;
+    const roles = Object.entries(s.definition.rooms)
+        .filter(([key, spec]) => spec.members.includes(participant) && (!room || room === key))
+        .map(([, spec]) => spec.roles?.[participant] ?? participant);
+    const agreed = added?.role ?? (new Set(roles).size === 1 ? roles[0] : undefined);
+    return [{ label: sealed, source: 'template_ref' }, { label: agreed, source: 'room_role' }, { label: participant, source: 'participant_key' }];
+}
 export function validateLayout(def) {
     need(Object.keys(def.rooms).length, 'rooms required');
     const empty = Object.keys(def.participants).length === 0;
@@ -59,7 +74,7 @@ export class RoomLayout {
         need(i.launch && i.cid && i.session, 'incomplete instance reference');
         await this.supervisor.verify(i);
     }
-    async create(definition, controller, bindings = {}, agentTemplates) {
+    async create(definition, controller, bindings = {}, agentTemplates, roleLabels) {
         validateLayout(definition);
         need(controller, 'controller required');
         this.checkOwnerRoles(definition);
@@ -90,7 +105,8 @@ export class RoomLayout {
                     participants[key] = { owned: !bindings[key], ...(bindings[key] ? { instance: bindings[key] } : {}) };
             }
             this.save({ version: 1, definition, controller, ...(this.owner ? { owner: ownerReference(this.owner) } : {}),
-                agent_templates: agentTemplates, participants, rooms: {}, order: [], closed: false });
+                agent_templates: agentTemplates, ...(roleLabels && Object.keys(roleLabels).length ? { role_labels: roleLabels } : {}),
+                participants, rooms: {}, order: [], closed: false });
         });
     }
     checkOwnerRoles(definition) {
@@ -150,9 +166,10 @@ export class RoomLayout {
                 need(template, `no factory for ${member}`);
                 if (this.supervisor.taskSupervised)
                     p.task_supervised = true;
+                const labels = participantLabels(s, member, template, p.room);
                 await this.mutation(s, `spawn:${resolvedKey}`, () => s.additional_members?.[member]
-                    ? this.supervisor.spawn(resolvedKey, template, s.agent_templates?.[template])
-                    : this.supervisor.spawn(resolvedKey, template), i => { p.instance = i; });
+                    ? this.supervisor.spawn(resolvedKey, template, s.agent_templates?.[template], labels)
+                    : this.supervisor.spawn(resolvedKey, template, undefined, labels), i => { p.instance = i; });
                 await this.verify(p.instance);
             }
         }

package/dist/rooms-tasks/member-naming.d.ts

@@ -0,0 +1,43 @@
+import type { MemberNameAllocation, MemberNaming, TaskRecord } from './types.js';
+export declare const AGENT_NAME_MAX = 64;
+/** Ordinal suffix headroom: `-999`. */
+export declare const MAX_ROLE_ORDINAL = 999;
+export type LabelSource = NonNullable<MemberNameAllocation['label_source']>;
+export interface LabelCandidate {
+    label: string | undefined;
+    source: LabelSource;
+}
+export declare class MemberNameError extends Error {
+    readonly code: 'role_ordinal_exhausted' | 'agent_name_taken' | 'invalid_label';
+    constructor(code: 'role_ordinal_exhausted' | 'agent_name_taken' | 'invalid_label', message: string);
+}
+/** PascalCase join of Latin alphanumeric words; diacritics folded, other scripts dropped. */
+export declare function labelStem(label: string): string;
+/** First candidate that survives normalization, else `Agent`. */
+export declare function chooseStem(key: string, candidates: readonly LabelCandidate[]): {
+    stem: string;
+    source: LabelSource;
+};
+export declare const bucketOf: (stem: string) => string;
+/** Own-property read: buckets such as `constructor` must never hit Object.prototype. */
+export declare const ownEntry: <T>(record: Record<string, T> | undefined, key: string) => T | undefined;
+export declare function formatMemberName(key: string, stem: string, ordinal: number): string;
+/**
+ * Pure allocation step: returns the existing allocation for `allocationKey`,
+ * or a new one plus the updated naming. The caller persists under the task
+ * lock and checks external name conflicts before launch.
+ */
+export declare function allocateName(naming: MemberNaming | undefined, key: string, allocationKey: string, candidates: readonly LabelCandidate[]): {
+    naming: MemberNaming;
+    allocation: MemberNameAllocation;
+    created: boolean;
+};
+/**
+ * Freeze every historical agent name and seed counters by the same label
+ * precedence as new names. Deduplicated by physical agent name; counters merge
+ * monotonically and existing allocations are never rewritten. Returns the
+ * input object unchanged when there is nothing to add.
+ */
+export declare function freezeLegacyMemberNaming(task: Pick<TaskRecord, 'task_id' | 'room_id' | 'layout' | 'execution_plan' | 'member_naming'> & {
+    key: string;
+}): MemberNaming | undefined;