@ours.network/fleet 2.2.6 → 2.3.0

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

@@ -0,0 +1,186 @@
+/**
+ * Role-scoped agent names for task members.
+ *
+ *   <KEY>-<Stem>       first member of a stem (no `-1`)
+ *   <KEY>-<Stem>-<n>   later members, n >= 2
+ *
+ * The stem comes from the explicitly selected named Role when one exists,
+ * otherwise from a stable room label, participant key or slot. It is
+ * PascalCase Latin alphanumerics, truncated with ordinal headroom so the full
+ * name fits the 64-character Fleet role-name budget. The counter bucket is the
+ * case-folded truncated stem, chosen before numbering, so labels that collapse
+ * to the same stem share one counter and can never produce the same name.
+ *
+ * Allocations are durable on the task record and keyed by a stable allocation
+ * key: provisioning, recovery and restart reuse them; additions and
+ * replacements use new keys and consume the next ordinal. Names that existed
+ * before mission keys are frozen exactly as launched.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { stateRoot } from '../paths.js';
+export const AGENT_NAME_MAX = 64;
+/** Ordinal suffix headroom: `-999`. */
+export const MAX_ROLE_ORDINAL = 999;
+const SUFFIX_HEADROOM = 1 + String(MAX_ROLE_ORDINAL).length;
+export class MemberNameError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'MemberNameError';
+    }
+}
+/** PascalCase join of Latin alphanumeric words; diacritics folded, other scripts dropped. */
+export function labelStem(label) {
+    const words = label.normalize('NFKD').replace(/\p{M}/gu, '').split(/[^A-Za-z0-9]+/).filter(Boolean);
+    const joined = words.map(word => word[0].toUpperCase() + word.slice(1)).join('');
+    // Fleet role names must start with an alphanumeric; a leading digit is allowed.
+    return joined;
+}
+/** First candidate that survives normalization, else `Agent`. */
+export function chooseStem(key, candidates) {
+    const budget = AGENT_NAME_MAX - key.length - 1 - SUFFIX_HEADROOM;
+    if (budget < 1)
+        throw new MemberNameError('invalid_label', `mission key ${key} leaves no room for a role name`);
+    for (const candidate of candidates) {
+        if (!candidate.label)
+            continue;
+        const stem = labelStem(candidate.label).slice(0, budget);
+        if (stem)
+            return { stem, source: candidate.source };
+    }
+    return { stem: 'Agent'.slice(0, budget), source: 'fallback' };
+}
+export const bucketOf = (stem) => stem.toLowerCase();
+/** Own-property read: buckets such as `constructor` must never hit Object.prototype. */
+export const ownEntry = (record, key) => record && Object.hasOwn(record, key) ? record[key] : undefined;
+export function formatMemberName(key, stem, ordinal) {
+    return ordinal === 1 ? `${key}-${stem}` : `${key}-${stem}-${ordinal}`;
+}
+/**
+ * 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 function allocateName(naming, key, allocationKey, candidates) {
+    const current = naming
+        ? { version: 2, counters: { ...naming.counters }, allocations: { ...naming.allocations } }
+        : { version: 2, counters: {}, allocations: {} };
+    const existing = ownEntry(current.allocations, allocationKey);
+    if (existing)
+        return { naming: naming ?? current, allocation: existing, created: false };
+    const { stem, source } = chooseStem(key, candidates);
+    const bucket = bucketOf(stem);
+    const ordinal = (ownEntry(current.counters, bucket) ?? 0) + 1;
+    if (ordinal > MAX_ROLE_ORDINAL)
+        throw new MemberNameError('role_ordinal_exhausted', `mission ${key} has used every ${stem} ordinal`);
+    const allocation = {
+        name: formatMemberName(key, stem, ordinal), bucket, ordinal, label_source: source,
+    };
+    current.counters[bucket] = ordinal;
+    current.allocations[allocationKey] = allocation;
+    return { naming: current, allocation, created: true };
+}
+// ── Frozen historical names (one-time migration) ─────────────────────────
+const LEGACY_TEMPLATE_NAME = /^[0-9a-z]{8}-([A-Za-z][A-Za-z0-9_-]*)-([1-9][0-9]*)$/;
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+/** Every physical agent a historical task already launched or planned, from all durable sources. */
+function legacyMembers(task) {
+    const id8 = task.task_id.slice(0, 8);
+    const members = [];
+    const snapshot = (task.execution_plan?.snapshot.members ?? []);
+    const bySlot = new Map(snapshot.map(member => [member.slot, member]));
+    const candidatesFor = (slot, role) => {
+        const sealed = bySlot.get(slot);
+        return [
+            { label: sealed?.role_preset?.id, source: 'role_override' },
+            { label: sealed?.role_label, source: 'template_ref' },
+            { label: role ?? sealed?.role, source: 'room_role' },
+            { label: slot, source: 'slot' },
+        ];
+    };
+    for (const member of snapshot)
+        for (let i = 1; i <= member.count; i++)
+            members.push({ allocationKey: `initial:${member.slot}:${i}`, name: `${id8}-${member.slot}-${i}`,
+                candidates: candidatesFor(member.slot, member.role) });
+    const additions = join(stateRoot(), 'member-additions', task.task_id);
+    if (existsSync(additions))
+        for (const file of readdirSync(additions).filter(name => name.endsWith('.json')).sort()) {
+            const receipt = readJson(join(additions, file));
+            if (!receipt?.roleId || !receipt.requestId)
+                continue;
+            const slot = LEGACY_TEMPLATE_NAME.exec(receipt.roleId)?.[1] ?? receipt.roleId;
+            members.push({ allocationKey: `add:${receipt.requestId}`, name: receipt.roleId, candidates: candidatesFor(slot) });
+        }
+    if (task.room_id) {
+        const room = readJson(join(stateRoot(), 'rooms', `${task.room_id}.json`));
+        for (const seat of room?.member_seats ?? []) {
+            const match = LEGACY_TEMPLATE_NAME.exec(seat.role_name);
+            const slot = seat.slot ?? match?.[1] ?? seat.role_name;
+            members.push({ allocationKey: match ? `initial:${match[1]}:${match[2]}` : `seat:${seat.role_name}`,
+                name: seat.role_name, candidates: candidatesFor(slot, seat.cowork_role) });
+        }
+    }
+    if (task.layout) {
+        const run = readJson(join(stateRoot(), 'layouts', `${task.layout.run_id}.json`));
+        for (const [instanceKey, participant] of Object.entries(run?.participants ?? {})) {
+            const agent = participant.instance?.agent;
+            if (!agent || participant.owned === false)
+                continue;
+            const key = participant.participant ?? instanceKey;
+            const roles = Object.entries(run?.definition?.rooms ?? {})
+                .filter(([room, spec]) => spec.members.includes(key) && (!participant.room || participant.room === room))
+                .map(([, spec]) => spec.roles?.[key] ?? key);
+            const added = run?.additional_members?.[key]?.role;
+            const agreed = added ?? (new Set(roles).size === 1 ? roles[0] : undefined);
+            members.push({ allocationKey: `layout:${task.layout.run_id}:${instanceKey}`, name: agent, candidates: [
+                    { label: agreed, source: 'room_role' }, { label: key, source: 'participant_key' }
+                ] });
+        }
+    }
+    return members;
+}
+/**
+ * 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 function freezeLegacyMemberNaming(task) {
+    const legacy = legacyMembers(task);
+    if (!legacy.length)
+        return task.member_naming;
+    const naming = task.member_naming
+        ? { version: 2, counters: { ...task.member_naming.counters }, allocations: { ...task.member_naming.allocations } }
+        : { version: 2, counters: {}, allocations: {} };
+    const known = new Set(Object.values(naming.allocations).map(allocation => allocation.name));
+    const seeded = {};
+    let changed = !task.member_naming;
+    for (const member of legacy) {
+        if (known.has(member.name))
+            continue;
+        if (ownEntry(naming.allocations, member.allocationKey))
+            continue;
+        known.add(member.name);
+        const { stem } = chooseStem(task.key, member.candidates);
+        const bucket = bucketOf(stem);
+        seeded[bucket] = (ownEntry(seeded, bucket) ?? 0) + 1;
+        naming.allocations[member.allocationKey] = { name: member.name, bucket, frozen: true };
+        changed = true;
+    }
+    for (const [bucket, count] of Object.entries(seeded)) {
+        const frozenInBucket = Object.values(naming.allocations).filter(a => a.frozen && a.bucket === bucket).length;
+        naming.counters[bucket] = Math.max(ownEntry(naming.counters, bucket) ?? 0, frozenInBucket, count);
+    }
+    return changed ? naming : task.member_naming;
+}

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

@@ -190,6 +190,7 @@ export function prepareExecutionPlan(template, cfg, overrides = {}) {
             loop_source: input.loops !== undefined ? 'cli' : base.loops !== undefined ? 'agent-template' : 'omitted',
             agent_template_hash: hash,
             ...(input.role ? { role_preset: { id: input.role, hash: createHash('sha256').update(canonicalJson(rolePreset)).digest('hex') } } : {}),
+            ...(cfg.agentTemplateRoleRefs?.[source] ? { role_label: cfg.agentTemplateRoleRefs[source] } : {}),
             ...(input.brain ? { brain_preset: { id: input.brain, hash: createHash('sha256').update(canonicalJson(brainPreset)).digest('hex') } } : {}),
             agent_projection: redactLaunchDefinition(definition) };
     });

package/dist/rooms-tasks/mission-keys.d.ts

@@ -0,0 +1,83 @@
+export declare const DEFAULT_MISSION_PREFIX = "MSN";
+/** Never accepted for a custom list; ROOM/LAYOUT case-fold onto legacy agent names. */
+export declare const RESERVED_MISSION_PREFIXES: readonly string[];
+export declare const MISSION_PREFIX_MAX = 6;
+/** Accepted reference form; canonical task IDs never contain '-'. */
+export declare const MISSION_KEY_RE: RegExp;
+export type MissionKeyErrorCode = 'invalid_prefix' | 'duplicate_prefix' | 'prefix_reserved' | 'default_prefix_frozen' | 'task_deleted' | 'idempotency_conflict' | 'key_space_exhausted' | 'invalid_state';
+export declare class MissionKeyError extends Error {
+    readonly code: MissionKeyErrorCode;
+    constructor(code: MissionKeyErrorCode, message: string);
+}
+export interface PrefixRecord {
+    list_id: string;
+    last_issued: number;
+    /** active: the list's current prefix; retired: an earlier prefix of the same list; tombstoned: its list was deleted. */
+    state: 'active' | 'retired' | 'tombstoned';
+}
+export interface MissionKeyRegistry {
+    version: 1;
+    default_prefix: string;
+    prefixes: Record<string, PrefixRecord>;
+    /** Set only after every historical row, receipt and ledger entry is durable. */
+    keys_migrated?: true;
+}
+export interface CreationReceipt {
+    version: 1;
+    task_id: string;
+    /** Absent only on a tombstone seeded for a row that never had a key. */
+    mission_key?: string;
+    list_id: string;
+    /** sha256 of the canonical original creation input; absent on receipts seeded for legacy rows. */
+    fingerprint?: string;
+    /** Complete original creation input, so a resumed create never uses retry input. */
+    input?: Record<string, unknown>;
+    creation_plan?: string;
+    state: 'reserved' | 'created' | 'deleted';
+}
+export interface KeyLedgerEntry {
+    version: 1;
+    key: string;
+    task_id: string;
+    state: 'live' | 'deleted';
+}
+/** Innermost cross-process lock for registry, receipts and ledger. Re-entrant within a process. */
+export declare function withMissionKeysLock<T>(fn: () => T): T;
+/** Trim and uppercase ASCII letters; every other deviation is an explicit error. */
+export declare function normalizeMissionPrefix(input: unknown): string;
+/**
+ * Deterministic convenience suggestion; never authoritative and never a
+ * tombstoned, retired, reserved or active prefix.
+ */
+export declare function suggestMissionPrefix(name: string, taken: ReadonlySet<string>): string;
+export declare function readMissionKeyRegistry(): MissionKeyRegistry | undefined;
+export declare function writeMissionKeyRegistry(registry: MissionKeyRegistry): void;
+/**
+ * Create the registry on first use. A configured default prefix may change the
+ * default list's prefix only until it has issued its first key.
+ */
+export declare function ensureMissionKeyRegistry(configuredDefault?: string): MissionKeyRegistry;
+/** Every prefix a custom list may not take: reserved names, the default, and any ever-issued prefix. */
+export declare function unavailablePrefixes(registry: MissionKeyRegistry): Set<string>;
+export declare function activePrefixFor(registry: MissionKeyRegistry, listId: string): string | undefined;
+/**
+ * Claim `prefix` as the active prefix of `listId`. `explicit` is false for a
+ * server suggestion, which never adopts a tombstone. Caller holds the lock and
+ * writes the registry.
+ */
+export declare function claimPrefix(registry: MissionKeyRegistry, listId: string, prefix: string, explicit: boolean): void;
+/** Deleting a list keeps its prefixes and high-water marks as tombstones. */
+export declare function tombstoneListPrefixes(registry: MissionKeyRegistry, listId: string): void;
+/** Raise a prefix's high-water mark; the caller persists the registry before publishing the key. */
+export declare function issueNextKey(registry: MissionKeyRegistry, listId: string): string;
+/** Monotonically account for an already-issued key. */
+export declare function observeIssuedKey(registry: MissionKeyRegistry, key: string, listId: string): void;
+export declare const readCreationReceipt: (idempotencyKey: string) => CreationReceipt | undefined;
+export declare function writeCreationReceipt(idempotencyKey: string, receipt: CreationReceipt): void;
+export declare function readKeyLedger(key: string): KeyLedgerEntry | undefined;
+/** Create or confirm the ledger entry; a key never moves to another task. */
+export declare function ensureKeyLedger(key: string, taskId: string, state?: KeyLedgerEntry['state']): void;
+export declare function canonicalFingerprint(input: Record<string, unknown>): string;
+/** Parse a user reference; returns the normalized key, or undefined for non-key input. */
+export declare function parseMissionKeyRef(ref: string): string | undefined;
+export declare const missionKeysExist: () => boolean;

package/dist/rooms-tasks/mission-keys.js

@@ -0,0 +1,250 @@
+/**
+ * Human mission keys (`MSN-1`) and the durable state that issues them.
+ *
+ * The canonical task ID stays the storage, lock and authorization identity.
+ * A key is an immutable alias issued once from a per-prefix high-water mark;
+ * numbers are never derived from current rows and never reissued.
+ *
+ * Durable files under `<state>/mission-keys/`, all written by atomic replace
+ * while holding the synchronous mission-keys lock (innermost lock: callers may
+ * already hold `task-lists.lock` and/or one task lock, never the reverse):
+ *   registry.json            prefixes, owners, high-water marks
+ *   receipts/<sha256>.json   create idempotency receipts, never removed
+ *   keys/<KEY>.json          key ledger: key → canonical task ID, never removed
+ *
+ * Single ordering invariant for every issued key:
+ *   high-water mark → receipt → ledger → keyed task row.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFileAtomically, withSynchronousFileLock } from '../atomic-file.js';
+import { stateRoot } from '../paths.js';
+export const DEFAULT_MISSION_PREFIX = 'MSN';
+/** Never accepted for a custom list; ROOM/LAYOUT case-fold onto legacy agent names. */
+export const RESERVED_MISSION_PREFIXES = ['MSN', 'ROOM', 'LAYOUT', 'TASK'];
+export const MISSION_PREFIX_MAX = 6;
+const PREFIX_RE = /^[A-Z][A-Z0-9]{0,5}$/;
+/** Accepted reference form; canonical task IDs never contain '-'. */
+export const MISSION_KEY_RE = /^([A-Za-z][A-Za-z0-9]{0,5})-([1-9][0-9]{0,8})$/;
+const MAX_MISSION_NUMBER = 999_999_999;
+export class MissionKeyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'MissionKeyError';
+    }
+}
+const root = () => join(stateRoot(), 'mission-keys');
+const registryPath = () => join(root(), 'registry.json');
+const lockPath = () => join(root(), 'lock');
+const receiptPath = (idempotencyKey) => join(root(), 'receipts', `${createHash('sha256').update(idempotencyKey).digest('hex')}.json`);
+const ledgerPath = (key) => join(root(), 'keys', `${key}.json`);
+let lockDepth = 0;
+/** Innermost cross-process lock for registry, receipts and ledger. Re-entrant within a process. */
+export function withMissionKeysLock(fn) {
+    if (lockDepth > 0)
+        return fn();
+    return withSynchronousFileLock(lockPath(), () => {
+        lockDepth++;
+        try {
+            return fn();
+        }
+        finally {
+            lockDepth--;
+        }
+    });
+}
+const assertLocked = () => {
+    if (lockDepth === 0)
+        throw new MissionKeyError('invalid_state', 'mission-keys lock is not held');
+};
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+const writeJson = (path, value) => replaceFileAtomically(path, JSON.stringify(value, null, 2) + '\n', 0o600, {}, { durable: true });
+// ── Prefix rules ─────────────────────────────────────────────────────────
+/** Trim and uppercase ASCII letters; every other deviation is an explicit error. */
+export function normalizeMissionPrefix(input) {
+    if (typeof input !== 'string')
+        throw new MissionKeyError('invalid_prefix', 'prefix must be a string');
+    const value = input.trim().replace(/[a-z]/g, c => c.toUpperCase());
+    if (!PREFIX_RE.test(value))
+        throw new MissionKeyError('invalid_prefix', `prefix must be 1-${MISSION_PREFIX_MAX} Latin letters or digits starting with a letter, e.g. OPS`);
+    return value;
+}
+/** Latin words of a list name; diacritics are folded, other scripts are dropped. */
+function latinWords(name) {
+    return name.normalize('NFKD').replace(/\p{M}/gu, '').toUpperCase()
+        .split(/[^A-Z0-9]+/).filter(Boolean);
+}
+/**
+ * Deterministic convenience suggestion; never authoritative and never a
+ * tombstoned, retired, reserved or active prefix.
+ */
+export function suggestMissionPrefix(name, taken) {
+    const words = latinWords(name).filter(word => /^[A-Z]/.test(word));
+    let base = words.length > 1
+        ? words.map(word => word[0]).join('').slice(0, MISSION_PREFIX_MAX)
+        : words.length === 1 ? words[0].slice(0, 4) : '';
+    if (!PREFIX_RE.test(base))
+        base = 'L';
+    const free = (candidate) => !taken.has(candidate) && !RESERVED_MISSION_PREFIXES.includes(candidate);
+    if (base !== 'L' && free(base))
+        return base;
+    for (let n = base === 'L' ? 1 : 2; n < 1_000_000; n++) {
+        const suffix = String(n);
+        const candidate = base.slice(0, MISSION_PREFIX_MAX - suffix.length) + suffix;
+        if (PREFIX_RE.test(candidate) && free(candidate))
+            return candidate;
+    }
+    throw new MissionKeyError('key_space_exhausted', 'no free prefix suggestion');
+}
+// ── Registry ─────────────────────────────────────────────────────────────
+export function readMissionKeyRegistry() {
+    const value = readJson(registryPath());
+    if (value && (value.version !== 1 || typeof value.default_prefix !== 'string' || typeof value.prefixes !== 'object'))
+        throw new MissionKeyError('invalid_state', 'invalid mission key registry');
+    return value;
+}
+export function writeMissionKeyRegistry(registry) {
+    assertLocked();
+    writeJson(registryPath(), registry);
+}
+/**
+ * Create the registry on first use. A configured default prefix may change the
+ * default list's prefix only until it has issued its first key.
+ */
+export function ensureMissionKeyRegistry(configuredDefault) {
+    return withMissionKeysLock(() => {
+        const desired = configuredDefault === undefined ? undefined : normalizeMissionPrefix(configuredDefault);
+        let registry = readMissionKeyRegistry();
+        if (!registry) {
+            const prefix = desired ?? DEFAULT_MISSION_PREFIX;
+            registry = { version: 1, default_prefix: prefix,
+                prefixes: { [prefix]: { list_id: 'default', last_issued: 0, state: 'active' } } };
+            writeMissionKeyRegistry(registry);
+            return registry;
+        }
+        if (desired === undefined || desired === registry.default_prefix)
+            return registry;
+        const current = registry.prefixes[registry.default_prefix];
+        if (current && current.last_issued > 0)
+            throw new MissionKeyError('default_prefix_frozen', `default list prefix is ${registry.default_prefix}; tasks.default_prefix=${desired} can only change before the first mission key`);
+        if (registry.prefixes[desired])
+            throw new MissionKeyError('prefix_reserved', `prefix ${desired} is already used by another list`);
+        delete registry.prefixes[registry.default_prefix];
+        registry.default_prefix = desired;
+        registry.prefixes[desired] = { list_id: 'default', last_issued: 0, state: 'active' };
+        writeMissionKeyRegistry(registry);
+        return registry;
+    });
+}
+/** Every prefix a custom list may not take: reserved names, the default, and any ever-issued prefix. */
+export function unavailablePrefixes(registry) {
+    return new Set([...RESERVED_MISSION_PREFIXES, registry.default_prefix, ...Object.keys(registry.prefixes)]);
+}
+export function activePrefixFor(registry, listId) {
+    return Object.entries(registry.prefixes).find(([, record]) => record.list_id === listId && record.state === 'active')?.[0];
+}
+/**
+ * Claim `prefix` as the active prefix of `listId`. `explicit` is false for a
+ * server suggestion, which never adopts a tombstone. Caller holds the lock and
+ * writes the registry.
+ */
+export function claimPrefix(registry, listId, prefix, explicit) {
+    assertLocked();
+    if (listId !== 'default' && (RESERVED_MISSION_PREFIXES.includes(prefix) || prefix === registry.default_prefix))
+        throw new MissionKeyError('prefix_reserved', `prefix ${prefix} is reserved`);
+    const existing = registry.prefixes[prefix];
+    if (existing) {
+        const ownRetired = existing.list_id === listId && existing.state !== 'tombstoned';
+        const reclaim = existing.state === 'tombstoned' && explicit;
+        if (existing.list_id === listId && existing.state === 'active')
+            return;
+        if (!ownRetired && !reclaim)
+            throw new MissionKeyError(existing.state === 'active' ? 'duplicate_prefix' : 'prefix_reserved', existing.state === 'active'
+                ? `prefix ${prefix} is already used by another list`
+                : `prefix ${prefix} was used by an earlier list and is reserved`);
+    }
+    for (const record of Object.values(registry.prefixes))
+        if (record.list_id === listId && record.state === 'active')
+            record.state = 'retired';
+    registry.prefixes[prefix] = { list_id: listId, last_issued: existing?.last_issued ?? 0, state: 'active' };
+}
+/** Deleting a list keeps its prefixes and high-water marks as tombstones. */
+export function tombstoneListPrefixes(registry, listId) {
+    assertLocked();
+    for (const record of Object.values(registry.prefixes))
+        if (record.list_id === listId)
+            record.state = 'tombstoned';
+}
+/** Raise a prefix's high-water mark; the caller persists the registry before publishing the key. */
+export function issueNextKey(registry, listId) {
+    assertLocked();
+    const prefix = activePrefixFor(registry, listId);
+    if (!prefix)
+        throw new MissionKeyError('invalid_state', `list ${listId} has no active prefix`);
+    const record = registry.prefixes[prefix];
+    if (record.last_issued >= MAX_MISSION_NUMBER)
+        throw new MissionKeyError('key_space_exhausted', `prefix ${prefix} has issued its last key`);
+    record.last_issued += 1;
+    return `${prefix}-${record.last_issued}`;
+}
+/** Monotonically account for an already-issued key. */
+export function observeIssuedKey(registry, key, listId) {
+    const match = MISSION_KEY_RE.exec(key);
+    if (!match)
+        return;
+    const prefix = match[1].toUpperCase(), n = Number(match[2]);
+    const record = registry.prefixes[prefix]
+        ?? (registry.prefixes[prefix] = { list_id: listId, last_issued: 0, state: 'tombstoned' });
+    record.last_issued = Math.max(record.last_issued, n);
+}
+// ── Receipts and ledger ──────────────────────────────────────────────────
+export const readCreationReceipt = (idempotencyKey) => readJson(receiptPath(idempotencyKey));
+export function writeCreationReceipt(idempotencyKey, receipt) {
+    assertLocked();
+    const previous = readCreationReceipt(idempotencyKey);
+    // A deletion tombstone is terminal: nothing may revive the receipt.
+    if (previous?.state === 'deleted' && receipt.state !== 'deleted')
+        throw new MissionKeyError('task_deleted', `mission ${previous.mission_key} was deleted`);
+    writeJson(receiptPath(idempotencyKey), receipt);
+}
+export function readKeyLedger(key) {
+    if (!/^[A-Z][A-Z0-9]{0,5}-[1-9][0-9]*$/.test(key))
+        return undefined;
+    return readJson(ledgerPath(key));
+}
+/** Create or confirm the ledger entry; a key never moves to another task. */
+export function ensureKeyLedger(key, taskId, state = 'live') {
+    assertLocked();
+    const previous = readKeyLedger(key);
+    if (previous && previous.task_id !== taskId)
+        throw new MissionKeyError('invalid_state', `mission key ${key} already belongs to another task`);
+    if (previous && (previous.state === state || previous.state === 'deleted'))
+        return;
+    writeJson(ledgerPath(key), { version: 1, key, task_id: taskId, state });
+}
+export function canonicalFingerprint(input) {
+    const sorted = (value) => Array.isArray(value) ? value.map(sorted)
+        : value && typeof value === 'object'
+            ? Object.fromEntries(Object.keys(value).sort().filter(key => value[key] !== undefined)
+                .map(key => [key, sorted(value[key])]))
+            : value;
+    return createHash('sha256').update(JSON.stringify(sorted(input))).digest('hex');
+}
+/** Parse a user reference; returns the normalized key, or undefined for non-key input. */
+export function parseMissionKeyRef(ref) {
+    const match = MISSION_KEY_RE.exec(ref);
+    return match ? `${match[1].toUpperCase()}-${match[2]}` : undefined;
+}
+export const missionKeysExist = () => existsSync(registryPath());

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

@@ -15,6 +15,8 @@ export interface ProvisionMembersInput {
     startupWait?: Partial<StartupWaitPolicy>;
     /** Append only the supplied new slots to an already active room. */
     append?: boolean;
+    /** Durable name allocation key for an appended member (`add:<requestId>`). */
+    allocationKey?: string;
 }
 export interface StartupWaitPolicy {
     timeoutMs: number;
@@ -23,6 +25,8 @@ export interface StartupWaitPolicy {
     now(): number;
     sleep(ms: number): Promise<void>;
 }
+/** A new name must not collide with any local agent state or a permanent identity. */
+export declare function assertMemberNameAvailable(name: string): void;
 export declare function provisionMembers(input: ProvisionMembersInput): Promise<RoomOrchestrationRecord>;
 /** Reconcile proven, admitted launches without any spawn, archive, invite or recovery path. */
 export declare function reconcileExistingTaskMembers(input: {

package/dist/rooms-tasks/provision.js

@@ -19,7 +19,9 @@ import { SessionControlError } from '../session/types.js';
 import { closeManagedRoom, roomCloseLockPath, CLOSE_LOCK_STALE_MS } from './close.js';
 import { withFileLock } from '../atomic-file.js';
 import { TASK_OPERATION_LOCK_STALE_MS, taskOperationLockPath } from './terminal.js';
-import { TaskStateError, taskDeletionState } from './task-state.js';
+import { TaskStateError, allocateTaskMemberNames, taskDeletionState } from './task-state.js';
+import { MemberNameError } from './member-naming.js';
+import { assertMemberNotPermanent } from './member-ownership.js';
 import { buildRoomMemberTask, sha256Text } from './member-startup.js';
 import { agentDir } from '../paths.js';
 import { readProvenance } from '../creation.js';
@@ -92,11 +94,43 @@ function expandMembers(template, prefix) {
                 launchDefinitionId: slot.launch_definition_id ?? slot.agent_template,
                 agentTemplateHash: slot.agent_template_hash,
                 loopSource: slot.loop_source ?? 'omitted',
+                ordinal: i,
+                candidates: [
+                    { label: slot.role_preset?.id, source: 'role_override' },
+                    { label: slot.role_label, source: 'template_ref' },
+                    { label: slot.role, source: 'room_role' },
+                    { label: slot.slot, source: 'slot' },
+                ],
             });
         }
     }
     return result;
 }
+/** A new name must not collide with any local agent state or a permanent identity. */
+export function assertMemberNameAvailable(name) {
+    const taken = () => new MemberNameError('agent_name_taken', `agent name ${name} is already used on this host or ours daemon, possibly by another Fleet; give this Fleet's lists distinct prefixes`);
+    if (existsSync(agentDir(name)) || existsSync(agentDir(name, true)))
+        throw taken();
+    try {
+        assertMemberNotPermanent(name);
+    }
+    catch {
+        throw taken();
+    }
+}
+/**
+ * Members of a keyed task take their durable role-scoped names; unkeyed tasks
+ * and non-task rooms keep the legacy `prefix-slot-i` derivation.
+ */
+function nameMembers(input, members) {
+    if (!input.taskId)
+        return members;
+    const names = allocateTaskMemberNames(input.taskId, members.map(member => ({
+        allocationKey: input.append && input.allocationKey ? input.allocationKey : `initial:${member.slot}:${member.ordinal}`,
+        candidates: member.candidates,
+    })), assertMemberNameAvailable);
+    return names ? members.map((member, index) => ({ ...member, name: names[index] })) : members;
+}
 function settingsFor(member, cfg, sealed) {
     const definition = sealed
         ? sealed[member.launchDefinitionId]
@@ -406,7 +440,7 @@ export async function provisionMembers(input) {
             if (!task || !['active', 'review'].includes(task.state) || room?.state !== 'active'
                 || room.task_id !== task.task_id || room.room_identity_cid !== task.room_identity_cid)
                 throw new Error('Adding an agent requires the exact active task room');
-            const names = expandMembers(input.template, shortId(task.task_id)).map(m => m.name);
+            const names = nameMembers(input, expandMembers(input.template, shortId(task.task_id))).map(m => m.name);
             if (room.member_seats.some(seat => names.includes(seat.role_name)))
                 throw new Error('Member slot is already recorded; inspect its existing launch');
             if (room.member_seats.some(seat => seat.seat_state !== 'active'))
@@ -426,7 +460,7 @@ async function provisionMembersUnlocked(input) {
     if (taskId && taskDeletionState(taskId) !== 'none')
         throw new Error(`task ${taskId} is pending deletion; refusing to provision members`);
     const prefix = taskId ? shortId(taskId) : `room-${shortId(roomId)}`;
-    const members = expandMembers(template, prefix);
+    const members = nameMembers(input, expandMembers(template, prefix));
     // Resolve every Agent before persisting launch intent or touching Cowork membership.
     const sealed = template.launch_snapshot_hash
         ? readLaunchSnapshot(template.launch_snapshot_hash) : undefined;

package/dist/rooms-tasks/task-lists.d.ts

@@ -11,9 +11,25 @@ export declare const withTaskListsLock: <T>(fn: () => T | Promise<T>) => Promise
 export declare function normalizeTaskListName(input: string): string;
 export declare function readTaskLists(): TaskListRecord[];
 export declare function resolveTaskList(name: string, lists?: TaskListRecord[]): TaskListRecord;
-/** Caller must hold withTaskListsLock. */
-export declare function createTaskListLocked(name: string): TaskListRecord;
+/**
+ * Server suggestion for a new list's prefix; convenience only, validated again
+ * on create.
+ */
+export declare function suggestTaskListPrefix(name: string): string;
+/**
+ * Caller must hold withTaskListsLock. The prefix registry is written before
+ * the list row, so a crash leaves at worst an orphan reservation that only an
+ * explicit reclaim can reuse; a key is never reissued.
+ */
+export declare function createTaskListLocked(name: string, prefix?: string): TaskListRecord;
+/**
+ * Caller must hold withTaskListsLock. Issued keys keep their old prefix; the
+ * previous prefix stays reserved to this list.
+ */
+export declare function setTaskListPrefixLocked(listName: string, prefix: string): TaskListRecord;
 /** Caller must hold withTaskListsLock. */
 export declare function renameTaskListLocked(currentName: string, nextName: string): TaskListRecord;
 /** Caller must hold withTaskListsLock. */
 export declare function deleteTaskListRecordLocked(listId: string): void;
+/** Caller holds withTaskListsLock; persists prefixes assigned by migration. */
+export declare function writeTaskListPrefixesLocked(prefixes: Map<string, string>): TaskListRecord[];