@zq-silk/yui 2.19.0 → 2.20.0

package/dist/cli/commandCatalog.js

@@ -136,6 +136,7 @@ const agentChildren = [
     { name: "remove", discovery: { surface: "public", audiences: ["public", "operator"] }, summary: "Remove a configured Agent.", usage: "yui config agent remove <id>" }
 ];
 const roleProfileOptions = [
+    "--instance-code",
     "--description", "--responsibility", "--constraint",
     "--expected-output", "--system-prompt", "--skill"
 ];
@@ -144,6 +145,7 @@ const roleAgentOptions = [
     "--allowed-tool", "--disallowed-tool", "--search"
 ];
 const roleProfileClearOptions = [
+    "--clear-instance-code",
     "--clear-description", "--clear-responsibilities", "--clear-constraints",
     "--clear-expected-output", "--clear-system-prompt", "--clear-skills"
 ];

package/dist/commands/roleConfiguration.js

@@ -1,4 +1,5 @@
 import { usageError } from "../errors/cliError.js";
+import { validateInstanceCode } from "../role/instanceCode.js";
 import { parseEnabled } from "../role/availability.js";
 import { defaultRoleAgentConfig, resolveAgentAdapter } from "../executor/agentAdapter.js";
 const PROFILE_OPTIONS = [
@@ -66,6 +67,8 @@ export function roleOptionSpecs(input) {
         ...(input.includeWorkspace === true ? [["--workspace", "value"]] : []),
         ...(input.update ? [["--yes", "flag"]] : []),
         ...(input.update ? [["--enabled", "value"]] : []),
+        ["--instance-code", "value"],
+        ...(input.update ? [["--clear-instance-code", "flag"]] : []),
         ...PROFILE_OPTIONS,
         ...agentValueOptions,
         ...agentRepeatableOptions,
@@ -105,6 +108,7 @@ export function parseRoleOptions(args, specs, usage) {
 }
 export function roleProfileFrom(parsed) {
     return {
+        ...roleDisplayPatch(parsed),
         ...(parsed.has("--description") ? { description: requiredText(parsed.one("--description")) } : {}),
         responsibilities: parsed.many("--responsibility").map(requiredText),
         constraints: parsed.many("--constraint").map(requiredText),
@@ -125,6 +129,7 @@ export function roleProfilePatch(parsed) {
         ["--skill", "--clear-skills"]
     ]);
     return {
+        ...roleDisplayPatch(parsed),
         ...(parsed.has("--enabled") ? { enabled: parseEnabled(parsed.one("--enabled")) } : {}),
         ...(parsed.has("--description") ? { description: requiredText(parsed.one("--description")) } : {}),
         ...(parsed.has("--clear-description") ? { description: undefined } : {}),
@@ -144,6 +149,18 @@ export function roleProfilePatch(parsed) {
         ...(parsed.has("--clear-skills") ? { skills: [] } : {})
     };
 }
+function roleDisplayPatch(parsed) {
+    assertPairs(parsed, [["--instance-code", "--clear-instance-code"]]);
+    try {
+        return {
+            ...(parsed.has("--instance-code") ? { instanceCode: validateInstanceCode(parsed.one("--instance-code")) } : {}),
+            ...(parsed.has("--clear-instance-code") ? { instanceCode: undefined } : {})
+        };
+    }
+    catch (error) {
+        throw usageError(error instanceof Error ? error.message : String(error));
+    }
+}
 export function hasAgentConfigOptions(parsed) {
     return [...parsed.seen].some((option) => AGENT_CONFIG_OPTIONS.has(option));
 }

package/dist/controller/fileSchedulerStoreAdapter.js

@@ -2114,8 +2114,14 @@ export class FileSchedulerStoreAdapter {
                     && existing.nativeSessionId !== input.session.nativeSessionId
                     && existing.status === "active";
                 if (!defersConversationReplacement && (existing?.nativeSessionId !== input.session.nativeSessionId || existing.status !== "active")) {
+                    // Preparation reactivates the fixed native identity, not its name.
+                    // Preserve the stored title even for an ended Session; only the
+                    // naming receipt may advance it on resume.
+                    const { title, ...preparedSession } = input.session;
                     saveTaskSession(store, role, {
-                        ...input.session,
+                        ...preparedSession,
+                        ...(existing?.nativeSessionId !== input.session.nativeSessionId && title !== undefined
+                            ? { title } : {}),
                         nativeSessionId: input.session.nativeSessionId
                     }, "active", input.now);
                 }
@@ -2180,7 +2186,7 @@ export class FileSchedulerStoreAdapter {
     recordLaunchedRuntimeNativeSession(input, assertCurrent, now = new Date()) {
         return this.store.transaction((store) => {
             assertCurrent();
-            const session = input.owner.scope === "task"
+            let session = input.owner.scope === "task"
                 ? recordTaskRuntimeNativeSession(store, {
                     taskId: input.owner.taskId,
                     roleName: input.owner.roleName,
@@ -2196,6 +2202,20 @@ export class FileSchedulerStoreAdapter {
                     nativeSessionId: input.nativeSessionId,
                     effective: input.effective
                 }, now);
+            if (input.generatedTitle !== undefined && (session.title === undefined
+                || session.title === session.generatedTitle || session.title === input.generatedTitle)) {
+                const set = input.owner.scope === "task"
+                    ? store.getTaskRoleSessionSet(input.owner.taskId, input.owner.roleName)
+                    : store.getGlobalRoleSessionSet(input.owner.roleName);
+                const titled = recordRoleAgentSession(set, {
+                    ...session, title: input.generatedTitle, generatedTitle: input.generatedTitle
+                }, now);
+                if (titled.owner.scope === "task")
+                    store.saveTaskRoleSessionSet(titled);
+                else
+                    store.saveGlobalRoleSessionSet(titled);
+                session = titled.sessions[input.agentId];
+            }
             if (input.owner.scope === "global") {
                 let sessions = store.getGlobalRoleSessionSet(input.owner.roleName);
                 let binding = sessions.providerBinding;

package/dist/controller/runtimeLaunchCoordinator.js

@@ -69,6 +69,7 @@ export class RuntimeLaunchCoordinator {
             }
         }
         let preflightObserved = beforeHostStart === undefined;
+        let generatedTitle;
         const observePreflight = (preflight) => {
             if (preflightObserved || !sameOwner(preflight.owner, request.owner)
                 || preflight.runId !== request.runId
@@ -80,6 +81,7 @@ export class RuntimeLaunchCoordinator {
             }
             assertLaunchCurrent();
             preflightObserved = true;
+            generatedTitle = preflight.generatedTitle;
             beforeHostStart?.(preflight);
         };
         const shared = {
@@ -94,7 +96,9 @@ export class RuntimeLaunchCoordinator {
         };
         // Even without a startup-facts consumer, recheck after asynchronous Host
         // validation and immediately before creating the process.
-        const callback = beforeHostStart === undefined ? () => assertLaunchCurrent() : observePreflight;
+        const callback = beforeHostStart === undefined
+            ? (preflight) => { assertLaunchCurrent(); generatedTitle = preflight.generatedTitle; }
+            : observePreflight;
         if (request.mode === "resume" && !request.nativeSessionId) {
             throw new Error("Restoring a Session requires its native session id.");
         }
@@ -109,11 +113,18 @@ export class RuntimeLaunchCoordinator {
             throw new Error("Session host returned facts inconsistent with the requested launch.");
         }
         if (binding.nativeSessionId !== undefined) {
+            // A live Host may reuse its Provider without applying the new plan.
+            // Codex reports the actual naming effect; other adapters can only name
+            // at creation and must not overwrite native user names on resume.
+            const recordedTitle = request.adapterId === "codex"
+                ? binding.appliedGeneratedTitle
+                : request.mode === "new" ? generatedTitle : undefined;
             this.sessions.recordLaunchedRuntimeNativeSession({
                 owner: request.owner,
                 agentId: request.agentId,
                 adapterId: request.adapterId,
                 nativeSessionId: binding.nativeSessionId,
+                ...(recordedTitle === undefined ? {} : { generatedTitle: recordedTitle }),
                 effective
             }, assertLaunchCurrent, this.options.now?.() ?? new Date());
         }

package/dist/executor/agentExecutor.js

@@ -111,6 +111,8 @@ export function recordRoleAgentSession(set, input, now) {
         adapterId,
         nativeSessionId,
         ...optionalSessionText("title", input.title ?? continuing?.title),
+        ...((input.generatedTitle ?? continuing?.generatedTitle) === undefined ? {}
+            : { generatedTitle: input.generatedTitle ?? continuing?.generatedTitle }),
         ...optionalSessionText("preview", input.preview ?? continuing?.preview),
         policy: input.policy,
         effective: continuing?.effective ?? effective,
@@ -567,6 +569,11 @@ export function validateRoleAgentSession(session, expectedAgentId = session.agen
         throw new Error(`Role Agent session effective identity is inconsistent: ${agentId}.`);
     }
     requireText(session.nativeSessionId, "Native session id");
+    if (session.generatedTitle !== undefined
+        && (typeof session.generatedTitle !== "string" || session.generatedTitle.length > 80
+            || optionalSessionText("title", session.generatedTitle).title !== session.generatedTitle)) {
+        throw new Error("Role Agent generated title is invalid.");
+    }
     if (session.title !== undefined
         && optionalSessionText("title", session.title).title !== session.title) {
         throw new Error("Role Agent session title is invalid.");

package/dist/executor/fileRoleLaunchPlanner.js

@@ -17,7 +17,7 @@ import { managedRuntimeAdmission } from "../runtime/agentDriver.js";
 import { builtinAgentEndpointImplementation, validateAgentEndpointImplementation } from "../runtime/agentEndpointIdentity.js";
 import { builtinAgentDriverRegistry, builtinDriverIdForAdapter } from "../runtime/builtinAgentDrivers.js";
 import { assertProviderConversationReplaceable } from "../runtime/providerRuntimeIdentity.js";
-import { operatorSessionTitle, resolveTaskRoleSessionTitle } from "../runtime/sessionTitle.js";
+import { globalRoleSessionTitle, resolveTaskRoleSessionTitle } from "../runtime/sessionTitle.js";
 import { parseTaskRuntimeIsolationDescriptor, taskRuntimeIsolationEnvironment } from "../runtime/taskRuntimeIsolation.js";
 import { planningRuntimeCwd } from "../storage/homeLayout.js";
 import { resolveAgentAdapter } from "./agentAdapter.js";
@@ -220,7 +220,11 @@ export class FileRoleLaunchPlanner {
             // attempt was rejected, cancelled, or completed.
             assertProviderConversationReplaceable(sessionSet.providerBinding);
         }
-        return this.#compile(role, input, { scope: "task", taskId: task.id }, resolveTaskRoleSessionTitle(input.mode === "resume" ? existing?.title : undefined, task, role.name), input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, effective, {
+        return this.#compile(role, input, { scope: "task", taskId: task.id }, resolveTaskRoleSessionTitle(input.mode === "resume" ? existing?.title : undefined, task, role.name, {
+            executionAuthority: (input.mode === "resume" ? existing?.effective : effective)?.executionAuthority,
+            instanceCode: role.instanceCode,
+            generatedTitle: existing?.generatedTitle
+        }), input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, effective, {
             purpose
         });
     }
@@ -249,9 +253,12 @@ export class FileRoleLaunchPlanner {
         if (input.mode === "new" && sessionSet?.providerBinding != null) {
             assertProviderConversationReplaceable(sessionSet.providerBinding);
         }
-        return this.#compile(role, input, { scope: "global" }, input.mode === "new" && role.name === "operator"
-            ? operatorSessionTitle(this.#now(), this.store.getConfig().timeZone)
-            : undefined, input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, effective, { purpose: "execution" });
+        return this.#compile(role, input, { scope: "global" }, input.mode === "new"
+            ? globalRoleSessionTitle(role.name, this.#now(), this.store.getConfig().timeZone, role.instanceCode)
+            : existing?.generatedTitle !== undefined && existing.title === existing.generatedTitle
+                ? globalRoleSessionTitle(role.name, new Date(existing.createdAt), this.store.getConfig().timeZone, role.instanceCode)
+                    ?? `Yui ${role.name}`
+                : undefined, input.mode === "resume" && compatibleExisting ? existing.nativeSessionId : undefined, effective, { purpose: "execution" });
     }
     #compile(role, input, owner, sessionTitle, knownNativeSessionId, effective, sessionPolicy) {
         const launchRole = effectiveRoleForLaunch(role, effective);
@@ -385,7 +392,9 @@ export class FileRoleLaunchPlanner {
             agent,
             config: effectiveConfig,
             workspace: agentWorkspace,
-            ...(sessionTitle === undefined || postCreateOperatorTitle
+            // CLI --name has no ownership check on resume. Only the Codex native
+            // metadata path below may rename an existing conversation.
+            ...(sessionTitle === undefined || postCreateOperatorTitle || input.mode === "resume"
                 ? {}
                 : { sessionTitle }),
             ...sessionContext
@@ -510,6 +519,9 @@ export class FileRoleLaunchPlanner {
                 mode: "resume",
                 nativeSessionId: requireText(providerNativeSessionId, "Managed Provider restore native session id"),
                 ...(sessionTitle === undefined ? {} : { sessionTitle }),
+                ...(existingSession?.generatedTitle !== undefined
+                    && existingSession.title === existingSession.generatedTitle
+                    ? { previousSessionTitle: existingSession.generatedTitle } : {}),
                 ...(managedCompiled.codexThread === undefined
                     ? {}
                     : { codexThread: managedCompiled.codexThread }),
@@ -594,6 +606,10 @@ export class FileRoleLaunchPlanner {
             },
             launch: ordinaryConversationLaunch,
             session,
+            ...(sessionTitle !== undefined && (input.mode === "new"
+                || existingSession?.title === undefined
+                || existingSession.title === existingSession.generatedTitle)
+                ? { generatedTitle: sessionTitle } : {}),
             ...(sessionTitle === undefined ? {} : { sessionTitle })
         };
     }

package/dist/output/rolePresentation.js

@@ -54,6 +54,7 @@ export function renderRoleDetails(title, role, input) {
         ...(!isEnabled(role) ? [`  Availability     ${roleDisabledReason(role)}`] : []),
         `  Active Agent     ${role.activeAgentId}`,
         `  Workspace        ${role.workspace}`,
+        `  Instance code    ${role.instanceCode ?? "-"} (display only; next Session launch)`,
         ...("taskId" in role ? [
             `  Desired environment ${role.executionEnvironment === undefined
                 ? "managed workspace"

package/dist/role/instanceCode.js

@@ -0,0 +1,7 @@
+export function validateInstanceCode(value) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 24
+        || !/^[\p{L}\p{N}\p{M}_-]+$/u.test(value)) {
+        throw new Error("Instance code must be 1–24 UTF-16 units of Unicode letters, numbers, marks, '_' or '-'; omit '@'.");
+    }
+    return value;
+}

package/dist/role/role.js

@@ -1,4 +1,5 @@
 import { isDeepStrictEqual } from "node:util";
+import { validateInstanceCode } from "./instanceCode.js";
 import { assertRoleEnabled, validateEnabled } from "./availability.js";
 import { requireKnownFields } from "../domain/validation.js";
 import { jobScopeKey } from "../job/jobDefinition.js";
@@ -49,6 +50,7 @@ export function copyGlobalRoleToTaskRole(globalRole, taskId, now, name = globalR
     const timestamp = now.toISOString();
     return validateTaskRole({
         ...cloneProfile(globalRole),
+        ...(globalRole.instanceCode === undefined ? {} : { instanceCode: globalRole.instanceCode }),
         schemaVersion: 1,
         enabled: true,
         launchRevision: 1,
@@ -75,6 +77,8 @@ export function updateGlobalRole(role, patch, now) {
         updatedAt: now.toISOString()
     };
     clearProfileFields(updated, patch);
+    if (Object.hasOwn(patch, "instanceCode") && patch.instanceCode === undefined)
+        delete updated.instanceCode;
     updated.launchRevision = isDeepStrictEqual(desiredBefore, desiredLaunchProjection(updated))
         ? role.launchRevision
         : role.launchRevision + 1;
@@ -94,6 +98,8 @@ export function updateRole(role, patch, now) {
         updated.executionEnvironment = cloneJson(patch.executionEnvironment);
     }
     clearProfileFields(updated, patch);
+    if (Object.hasOwn(patch, "instanceCode") && patch.instanceCode === undefined)
+        delete updated.instanceCode;
     updated.launchRevision = isDeepStrictEqual(desiredBefore, desiredLaunchProjection(updated))
         ? role.launchRevision
         : role.launchRevision + 1;
@@ -222,6 +228,7 @@ function createRoleOwner(name, bindings, activeAgentId, workspace, now, profile,
     const timestamp = now.toISOString();
     return {
         ...cloneProfile(profile),
+        ...(profile.instanceCode === undefined ? {} : { instanceCode: validateInstanceCode(profile.instanceCode) }),
         enabled: true,
         launchRevision: 1,
         defaultAccess,
@@ -234,6 +241,8 @@ function createRoleOwner(name, bindings, activeAgentId, workspace, now, profile,
     };
 }
 function validateRoleOwner(role) {
+    if (role.instanceCode !== undefined)
+        validateInstanceCode(role.instanceCode);
     validateEnabled(role.enabled);
     if (role.schemaVersion !== 1) {
         throw new Error("Role schema version is invalid.");
@@ -303,6 +312,7 @@ function assertSessionOwnerMatchesRole(role, sessions) {
 }
 function cloneRolePatch(patch) {
     return {
+        ...(patch.instanceCode === undefined ? {} : { instanceCode: validateInstanceCode(patch.instanceCode) }),
         ...(patch.enabled === undefined ? {} : { enabled: patch.enabled }),
         ...(patch.name === undefined ? {} : { name: requireSafeIdentity(patch.name, "Role name") }),
         ...(patch.activeAgentId === undefined

package/dist/runtime/agentEndpoint.js

@@ -81,6 +81,7 @@ class BuiltinAgentEndpoint {
     driver;
     configuration;
     get nativeAccess() { return this.driver.nativeAccess; }
+    get appliedGeneratedTitle() { return this.driver.appliedGeneratedTitle; }
     get ownedProcessId() { return this.driver.ownedProcessId; }
     get nativeAccountHome() { return this.driver.nativeAccountHome; }
     capabilities;

package/dist/runtime/agentHost.js

@@ -120,7 +120,13 @@ export async function runAgentHost(input) {
     const recentSteerAttempts = new Map();
     await replayExitOutbox(input.home);
     const updateSnapshot = (next) => {
-        snapshot = validateSnapshot(next);
+        const { appliedGeneratedTitle: _oldTitle, ...rest } = next;
+        snapshot = validateSnapshot({
+            ...rest,
+            ...(session?.appliedGeneratedTitle === undefined ? {} : {
+                appliedGeneratedTitle: session.appliedGeneratedTitle
+            })
+        });
     };
     const authorityFields = () => ({
         ...(session === undefined ? {} : { endpointImplementation: session.configuration.implementation }),
@@ -374,6 +380,8 @@ export async function runAgentHost(input) {
                         && currentPayload.environment.YUI_ROLE === "operator")
                     ? {}
                     : { sessionTitle: previousControl.sessionTitle }),
+                ...(previousControl.previousSessionTitle === undefined
+                    ? {} : { previousSessionTitle: previousControl.previousSessionTitle }),
                 codexThread: disconnectedSession.configuration.threadOptions,
                 endpointImplementation: disconnectedSession.configuration.implementation,
                 ...(ownedTurn === undefined ? {} : { ownedTurn }),

package/dist/runtime/launchBroker.js

@@ -167,6 +167,9 @@ function validateProviderControl(control) {
             throw new Error("Agent Host Provider session title is invalid.");
         }
     }
+    if (control.previousSessionTitle !== undefined) {
+        text(control.previousSessionTitle, "previousSessionTitle");
+    }
     validateProviderAuthorityFence(control.authority);
 }
 function validateCodexThreadOptions(options) {

package/dist/runtime/runtimeBinding.js

@@ -15,6 +15,9 @@ export function createRuntimeBinding(input) {
         ...(input.nativeSessionId === undefined
             ? {}
             : { nativeSessionId: requireText(input.nativeSessionId, "Native session id") }),
+        ...(input.appliedGeneratedTitle === undefined ? {} : {
+            appliedGeneratedTitle: requireText(input.appliedGeneratedTitle, "Applied generated title")
+        }),
         ...(input.providerAuthority === undefined
             ? {}
             : { providerAuthority: validateProviderAuthorityFence(input.providerAuthority) })

package/dist/runtime/sessionTitle.js

@@ -1,29 +1,33 @@
 import { resolveTimeZone } from "../config/timeZone.js";
+import { validateInstanceCode } from "../role/instanceCode.js";
 const TITLE_SEPARATOR = " · ";
 export const MAX_SESSION_TITLE_LENGTH = 80;
 const TASK_TITLE_MAX_LENGTH = 20;
-export function taskRoleSessionTitle(task, roleName) {
-    const prefix = `Yui ${roleLabel(roleName)} ${normalizeSegment(task.id)}`;
+export function taskRoleSessionTitle(task, roleName, options = {}) {
+    const prefix = `Yui ${roleLabel(roleName)} ${normalizeSegment(task.id)}`
+        + (roleName === "leader" && options.executionAuthority === "planning" ? " Draft" : "")
+        + instanceSegment(options.instanceCode);
     const title = displayTitle(normalizeSegment(task.title), TASK_TITLE_MAX_LENGTH);
     const full = `${prefix}${TITLE_SEPARATOR}${title}`;
     if (full.length <= MAX_SESSION_TITLE_LENGTH)
         return full;
     if (prefix.length + TITLE_SEPARATOR.length + 1 > MAX_SESSION_TITLE_LENGTH) {
-        return truncate(prefix, MAX_SESSION_TITLE_LENGTH);
+        throw new Error("Session title identity exceeds the maximum length; shorten the Role name or instance code.");
     }
-    const titleLength = MAX_SESSION_TITLE_LENGTH - prefix.length - TITLE_SEPARATOR.length - 1;
+    const titleLength = MAX_SESSION_TITLE_LENGTH - prefix.length - TITLE_SEPARATOR.length;
     return `${prefix}${TITLE_SEPARATOR}${displayTitle(title, Math.max(titleLength, 1))}`;
 }
-export function resolveTaskRoleSessionTitle(existingTitle, task, roleName) {
+export function resolveTaskRoleSessionTitle(existingTitle, task, roleName, options = {}) {
     if (existingTitle !== undefined
         && existingTitle.length > 0
         && existingTitle.length <= MAX_SESSION_TITLE_LENGTH
-        && !/[\r\n\0]/u.test(existingTitle)) {
+        && !/[\r\n\0]/u.test(existingTitle)
+        && existingTitle !== options.generatedTitle) {
         return existingTitle;
     }
-    return taskRoleSessionTitle(task, roleName);
+    return taskRoleSessionTitle(task, roleName, options);
 }
-export function operatorSessionTitle(now, configuredTimeZone) {
+export function operatorSessionTitle(now, configuredTimeZone, instanceCode) {
     if (!(now instanceof Date) || !Number.isFinite(now.getTime())) {
         throw new TypeError("Operator session title date is invalid.");
     }
@@ -35,7 +39,23 @@ export function operatorSessionTitle(now, configuredTimeZone) {
     if (parts.month === undefined || parts.day === undefined) {
         throw new TypeError("Operator session title date is unavailable.");
     }
-    return `Yui${TITLE_SEPARATOR}Operator${TITLE_SEPARATOR}${parts.month}${parts.day}`;
+    const prefix = instanceCode === undefined
+        ? `Yui${TITLE_SEPARATOR}Operator`
+        : `Yui Operator${instanceSegment(instanceCode)}`;
+    return `${prefix}${TITLE_SEPARATOR}${parts.month}${parts.day}`;
+}
+export function globalRoleSessionTitle(roleName, now, configuredTimeZone, instanceCode) {
+    if (roleName === "operator")
+        return operatorSessionTitle(now, configuredTimeZone, instanceCode);
+    if (instanceCode === undefined)
+        return undefined;
+    const title = `Yui ${roleLabel(roleName)}${instanceSegment(instanceCode)}`;
+    if (title.length > MAX_SESSION_TITLE_LENGTH)
+        throw new Error("Session title identity exceeds the maximum length.");
+    return title;
+}
+function instanceSegment(value) {
+    return value === undefined ? "" : ` @${validateInstanceCode(value)}`;
 }
 function displayTitle(value, maxLength) {
     if (value.length <= maxLength)

package/dist/runtime/structuredProviderHost.js

@@ -384,6 +384,7 @@ class CodexStructuredProviderSession {
     onActivity;
     mirror;
     nativeAccountHome;
+    appliedGeneratedTitle;
     nativeAccess;
     #turnAttempts = new Map();
     adapterId = "codex";
@@ -445,12 +446,20 @@ class CodexStructuredProviderSession {
                 throw error;
             }
         }
-        if (control.sessionTitle !== undefined) {
+        const threadMetadata = nativeConfiguration.thread;
+        const nativeTitle = typeof threadMetadata === "object" && threadMetadata !== null
+            && !Array.isArray(threadMetadata) ? threadMetadata.name : undefined;
+        // A native rename belongs to the user. Missing metadata is not evidence
+        // that an old title is still ours; leave it alone on resume.
+        let appliedGeneratedTitle;
+        if (control.sessionTitle !== undefined && (control.mode === "new"
+            || (control.previousSessionTitle !== undefined && nativeTitle === control.previousSessionTitle))) {
             try {
                 await runtime.setConversationName({
                     conversationId,
                     name: control.sessionTitle
                 });
+                appliedGeneratedTitle = control.sessionTitle;
             }
             catch (error) {
                 onDiagnostic?.({
@@ -465,6 +474,7 @@ class CodexStructuredProviderSession {
         }
         const session = new CodexStructuredProviderSession(child, exit, processInstanceId, conversationId, runtime, onStarted, onTerminal, onGoal, onInput, onActivity, mirror, optionalId(initialized.codexHome));
         session.nativeAccess = createCodexNativeAccess(conversationId, initialized, channel, openingMessages, nativeConfiguration);
+        session.appliedGeneratedTitle = appliedGeneratedTitle;
         session.#activeTurnId = resumedActiveTurnId;
         const ownedTurn = control.kind === "restore" ? control.ownedTurn : undefined;
         session.#clientOwnedTurnId = ownedTurn?.turnId;

package/dist/runtime/tmuxAdapters.js

@@ -246,6 +246,7 @@ export class TmuxSessionHost {
             agentId: request.agentId,
             adapterId: request.adapterId,
             effective: request.effective,
+            ...(planned.generatedTitle === undefined ? {} : { generatedTitle: planned.generatedTitle }),
             ...(planned.launch.env.YUI_SESSION_TITLE === undefined
                 ? {}
                 : { sessionTitle: planned.launch.env.YUI_SESSION_TITLE }),
@@ -436,6 +437,9 @@ export class TmuxSessionHost {
                 roleName: request.owner.roleName
             }),
             hostCreated,
+            ...(providerSnapshot?.appliedGeneratedTitle === undefined ? {} : {
+                appliedGeneratedTitle: providerSnapshot.appliedGeneratedTitle
+            }),
             ...((providerSnapshot?.nativeSessionId ?? nativeSessionId) === undefined
                 ? {}
                 : { nativeSessionId: providerSnapshot?.nativeSessionId ?? nativeSessionId }),

package/dist/storage/sqliteSchema.js

@@ -276,6 +276,16 @@ const MINOR_UPGRADES = Object.freeze([{
         // No payload rewriting or historical revision invention. A newly opened
         // reader starts empty; zero is the initial token until the first mutation.
         sql: TASK_READ_REVISION_SCHEMA_SQL
+    }, {
+        fromVersion: "1.24",
+        toVersion: "1.25",
+        name: "role-instance-code-session-titles",
+        introducedIn: "next",
+        sourceChecksum: CURRENT_SCHEMA_CHECKSUM,
+        targetChecksum: CURRENT_SCHEMA_CHECKSUM,
+        // Optional Role presentation and generated-title provenance. Never infer
+        // ownership of historical titles, rewrite frozen profiles, or fill defaults.
+        sql: ""
     }]);
 export function storageMinorUpgradePlan(from) {
     if (from === CURRENT_STORAGE_VERSION)

package/dist/storage/storageVersions.js

@@ -1,4 +1,4 @@
-export const CURRENT_STORAGE_VERSION = "1.24";
+export const CURRENT_STORAGE_VERSION = "1.25";
 export const MIN_SUPPORTED_STORAGE_VERSION = "1.0";
 export const STORAGE_FORMAT = "yui-home";
 export function isStorageVersion(value) {

package/docs/release-workflow.md

@@ -51,6 +51,35 @@ merely to avoid a version decision. Package versions remain distinct from protoc
 and persistent-storage contracts: their compatibility checks and required migrations
 are unchanged, and the storage rules below do not authorize a package release.
 
+### 2.20.0 compatibility and migration notes
+
+This minor adds independent optional Role instance codes (`--instance-code` /
+`--clear-instance-code`) and a `Draft` marker for Leader Sessions with planning
+authority. Operator-only configuration does not propagate to Leader or other
+Roles. Task Role template copies remain independent; codes are presentation,
+not identity, authorization or launch-configuration drift. Full lowercase Task
+IDs remain unchanged. See [Role configuration](roles-and-configuration.md).
+
+New Sessions use the configured code. Normal Codex Host launches/resumes can refresh
+confirmed Yui-owned titles without forcing a stop/replacement. Historical untagged
+titles and recorded custom names are preserved. Codex resume naming requires
+the native name to match the previous generated title; missing metadata and
+user renames are left untouched. Title provenance advances only after a successful
+native naming receipt, not pre-start registration or live Host reuse. Other
+Providers receive generated names only on creation, never on resume. Provider
+naming remains best effort.
+
+Storage advances **1.24 → 1.25** through an additive, no-rewrite transition for
+optional Role code and Session title provenance. Older supported Homes follow
+the centralized contiguous chain; do not open an upgraded Home with older
+software. Controller/Host protocols remain v1. Publication does not authorize
+installing the release, migrating a production Home, restarting shared services,
+replacing Sessions or choosing codes for existing Roles.
+
+Release gates require exact-merge Core CI and the same runtime tarball's
+fresh-install matrix before npm `latest` publication. These deterministic
+checks do not establish real-model behavior.
+
 ### 2.19.0 compatibility and migration notes
 
 This minor adds message backlog and blocked-delivery monitoring with Operator

package/docs/release-workflow.zh-CN.md

@@ -36,6 +36,28 @@ Agent 选择一个预先声明的计划，设施从持久状态驱动该计划
 不能将不兼容冒称为兼容，也不为回避版本选择新增历史兼容机制。包版本与协议、
 持久存储契约仍然独立：兼容性检查和必要迁移要求不变，下文存储规则不授予发版权限。
 
+### 2.20.0 兼容性及迁移说明
+
+本 minor 增加按 Role 独立可选的实例码（`--instance-code` /
+`--clear-instance-code`），以及持有 planning 权限的 Leader Session 的 `Draft`
+标识。仅设置 Operator 不会传播到 Leader 或其他 Role；Task Role 模板副本保持
+独立。实例码仅供展示，不改变身份、权限、启动配置版本或完整小写 Task ID。
+详见 [Role 配置](roles-and-configuration.zh-CN.md)。
+
+新会话采用配置，正常 Codex Host 启动/恢复可刷新确认由 Yui 管理的标题，不强停或替换会话。
+旧的无来源标记标题和已记录的用户标题保留。Codex 恢复时仅在原生名字仍匹配上次
+生成标题时改名；原生信息缺失或用户已改名则跳过。标题来源仅在原生命名成功回执后
+推进，不因预启动登记或存活 Host 复用而变化。其他 Provider 仅在新建时传入生成名，
+恢复时不传入。Provider 命名仍为尽力能力。
+
+存储通过中央连续迁移从 **1.24 → 1.25**，只增加可选实例码和标题来源，
+不改写历史记录。较早的受支持 Home 沿既有迁移链升级，不可用旧程序打开升级后的
+Home。Controller/Host 协议仍为 v1。发布不授权安装升级、迁移生产 Home、
+重启共享服务、替换会话或为现有 Role 选择实例码。
+
+发布门禁要求准确合入 commit 的 Core CI 和同一 runtime tarball 的全平台
+fresh-install 矩阵通过后才向 npm `latest` 发布；这些确定性验证不证明真实模型行为。
+
 ### 2.19.0 兼容性及迁移说明
 
 本 minor 新增消息积压、投递阻塞监测及 Operator 告警（PR #492）。观测区分正常执行、

package/docs/roles-and-configuration.md

@@ -18,6 +18,55 @@ requiring a same-named global Role. A global Role is a creation template only
 when the requested Task Role does not exist. Availability, producer separation
 and the frozen review candidate still apply.
 
+## Optional instance codes and Session titles
+
+Each Role can independently set a display-only instance code. For example,
+configure only Operator, leaving Leader and all other Roles unset:
+
+```sh
+yui config role update operator --instance-code dev-bj
+yui config role show operator
+yui config role update operator --clear-instance-code
+yui task role update task-159 leader --instance-code dev-sg
+```
+
+`add` also accepts `--instance-code`. Codes accept 1–24 UTF-16 units of Unicode
+letters, numbers, combining marks, hyphen and underscore; omit `@`. Whitespace,
+controls, escapes and punctuation are rejected, not silently normalized.
+There is no Home-wide fallback. A Global Role's code is copied when that template
+creates a Task Role; later template changes do not rewrite the copy. Agent
+Profiles do not supply display codes. Use Task Role update/clear for an existing
+copy. Codes do not alter launch revisions, permissions, IDs or message routing.
+Choose recognizable values; codes are not globally unique identities. Use
+Session inspection and the actual Home/native identity when resolving ambiguity.
+
+Generated Task titles use `Yui Leader task-159 Draft @dev-sg · Task name`.
+`Draft` means the Leader Session has planning authority, including a retained
+planning Session after activation; delivery Sessions omit it. Other Role names
+and the full lowercase Task ID remain intact. Operator uses
+`Yui Operator @dev-bj · MMDD`; without a code its existing
+`Yui · Operator · MMDD` format remains. The date derives from Session creation
+and the configured timezone. Other Global Roles get a generated title when a
+code is configured. Descriptions are truncated first without splitting surrogate
+pairs; if the identity itself cannot fit the 80-unit title limit, launch fails
+with a bounded diagnostic instead of truncating the identity.
+
+Configuration does not rename, stop or recreate a live Session. New Sessions
+use it; a subsequent normal Host launch/resume can refresh confirmed Yui-owned titles,
+not historical records. Existing untagged titles and recorded user names stay
+untouched. Codex applies a resume rename only when its returned native name still
+matches the previous generated title; absent metadata or a user rename prevents
+the rename. Codex records only successfully applied names; live Host reuse,
+skipped naming and naming failures do not advance title provenance. Naming is
+best effort; unsupported Providers or failures do not invalidate the Session.
+Other Providers receive generated names only on creation, never on resume,
+to protect native user renames. No restart is performed to force a naming change.
+On the safe Codex resume path, clearing a custom Global Role's code restores
+`Yui role`; clearing Operator's code restores its unconfigured format.
+
+Storage 1.24 → 1.25 adds optional code/title provenance without rewriting
+historical payloads or inferring who named an old Session.
+
 ## Enable and disable
 
 Availability is configuration, separate from active Agent selection, Session

package/docs/roles-and-configuration.zh-CN.md

@@ -15,6 +15,44 @@ Task Role 是 Task 局部的；global Role 提供已配置的默认值和全局
 的 global Role。只有当请求的 Task Role 不存在时，global Role 才作为创建模板。
 可用性、producer 分离和冻结的审查候选仍然适用。
 
+## 可选实例码与会话标题
+
+每个 Role 独立配置仅用于展示的实例码。例如只设置 Operator，其他角色留空：
+
+```sh
+yui config role update operator --instance-code dev-bj
+yui config role show operator
+yui config role update operator --clear-instance-code
+yui task role update task-159 leader --instance-code dev-sg
+```
+
+`add` 也接受 `--instance-code`。允许 1–24 个 UTF-16 单位的 Unicode 字母、
+数字、组合标记、短横线和下划线，不输入 `@`。空白、控制字符、转义和其他标点
+直接拒绝，不静默清洗。没有 Home 级默认值；Global Role 作为模板创建 Task Role
+时复制其值，之后模板变化不回写。Agent Profile 不携带实例码；既有 Task Role
+通过自己的 update/clear 修改。实例码不改变启动版本、权限、内部 ID 或消息寻址，
+也不保证全局唯一；遇到歧义应查看实际 Home、Session 和原生身份。
+
+生成的 Task 标题为 `Yui Leader task-159 Draft @dev-sg · 任务名`。
+`Draft` 根据 Leader Session 的 planning 权限显示；Task 激活后保留的 planning
+会话仍显示 Draft，delivery 会话不显示。保留完整小写 Task ID。
+Operator 为 `Yui Operator @dev-bj · MMDD`；未配置保持
+`Yui · Operator · MMDD`，日期使用会话创建时间和配置时区。
+其他 Global Role 配置实例码后生成标题。80 单位总长度内优先截断任务名，
+不拆开代理对；身份部分无法容纳则明确报错，不静默截断。
+
+配置修改不会立即重命名、停止或重建活动会话。新会话采用新配置，后续正常
+Host 启动/恢复可刷新确认由 Yui 管理的标题，不改写历史记录。
+缺少来源标记的旧标题及已记录的用户标题保留。Codex 恢复时只有原生返回的
+名字仍等于上次生成标题才改名；原生信息缺失或用户已改名则跳过。
+Codex 只记录已成功应用的名称；复用存活 Host、命名失败或跳过不推进标题来源。
+Provider 命名为尽力能力；失败或不支持不会使会话失效。其他 Provider 仅在新建时
+传入生成名，恢复时不重新传入名称，以保护原生用户改名；不为改名主动重启。
+在可安全改名的 Codex 恢复路径，清除自定义 Global Role 实例码后恢复
+`Yui role`；Operator 恢复未配置格式。
+
+存储 1.24 → 1.25 增加可选实例码和生成标题来源，不回填历史记录或猜测标题所有权。
+
 ## 启用与停用
 
 启停是配置状态，与 Active Agent、Session 是否运行和 Task executionGate 分开：

package/docs/storage-baseline.md

@@ -2,7 +2,10 @@
 
 # Storage baseline 1.0
 
-Current storage is 1.24. The 1.23 → 1.24 transition adds transaction-maintained
+Current storage is 1.25. The 1.24 → 1.25 transition admits optional Role
+`instanceCode` and Session `generatedTitle` presentation fields without rewriting
+existing records. Untagged historical titles remain user-owned; no code or
+title provenance is inferred. The 1.23 → 1.24 transition adds transaction-maintained
 Task read-cache revisions for the scheduler's nine source tables. Inserts,
 updates and deletions invalidate only the affected Task; rollback also rolls
 back the token. These tokens are derived cache identities, never Task authority

package/docs/storage-baseline.zh-CN.md

@@ -2,7 +2,7 @@
 
 # 存储基线 1.0
 
-当前存储为 1.24。1.23 → 1.24 为调度器的九类来源表增加事务维护的 Task 读取缓存修订号。插入、更新和删除只使对应 Task 的缓存失效，回滚同时回滚修订号。该值仅是派生缓存标识，不是 Task 权限或 Home revision CAS 的替代。历史 payload 不变，旧 Task 在首次修改前使用隐含的零修订号。
+当前存储为 1.25。1.24 → 1.25 增加可选 Role `instanceCode` 和 Session `generatedTitle` 展示字段，不回填历史标题来源或实例码，不改写既有记录。1.23 → 1.24 为调度器的九类来源表增加事务维护的 Task 读取缓存修订号。插入、更新和删除只使对应 Task 的缓存失效，回滚同时回滚修订号。该值仅是派生缓存标识，不是 Task 权限或 Home revision CAS 的替代。历史 payload 不变，旧 Task 在首次修改前使用隐含的零修订号。
 同时增加两个局部索引，支持按精确运行观测身份查找，不再扫描或反序列化历史观测集合。
 
 1.22 → 1.23 新增全局 Shell Job、版本化脚本文件及每次运行的配置快照，不改写已有 Job、计划和历史记录。

package/docs/testing/verification-levels.md

@@ -53,12 +53,12 @@ is required.
 Both include `test/core` and `test/platform`. For an already built checkout,
 `npm run test:business` runs only `test/core` and `npm run test:platform` runs
 only `test/platform`; neither rebuilds. CI owns one explicit build per job.
-The stable suite owns current storage 1.24 and its declared 1.0 through 1.23 minor
+The stable suite owns current storage 1.25 and its declared 1.0 through 1.24 minor
 transition. It contains no undeclared historical format compatibility path.
 
 Current coverage includes:
 
-1. Fresh storage 1.24, exact schema/record validation, no initialization over
+1. Fresh storage 1.25, exact schema/record validation, no initialization over
    unknown data, and rejection of old integer formats without mutation.
 2. Exact-version staging, mismatched-target refusal, same-major contiguous
    minor preflight, explicit maintenance-owner identity across handover, and

package/docs/testing/verification-levels.zh-CN.md

@@ -39,7 +39,7 @@ Yui 是一个单用户本地产品。永久验证保护关键的 happy path 和
 两者均包含 `test/core` 和 `test/platform`。已构建的 checkout 可分别运行
 `npm run test:business` 与 `npm run test:platform`，它们不会再次构建。
 CI 每个作业只显式构建一次。
-稳定套件维护当前存储 1.24 和明确声明的 1.0 至 1.23 连续小版本迁移，
+稳定套件维护当前存储 1.25 和明确声明的 1.0 至 1.24 连续小版本迁移，
 不包含未声明的历史格式兼容路径。
 
 当前覆盖包括：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zq-silk/yui",
-  "version": "2.19.0",
+  "version": "2.20.0",
   "description": "Local control plane for long-running native agent CLI sessions backed by tmux.",
   "license": "MIT",
   "private": false,