@yeaft/webchat-agent 1.0.605 → 1.0.607

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yeaft/webchat-agent",
-  "version": "1.0.605",
+  "version": "1.0.607",
   "description": "Remote worker agent for Yeaft Web Code Agent — connects the native Yeaft engine, CLI providers, and workbench tools",
   "main": "index.js",
   "type": "module",

package/yeaft/person/bridge.js

@@ -73,6 +73,9 @@ export function createPersonBridge({
         IMAGE_MODEL: 'No permitted selected model supports image input',
         MODEL_SELECTION: 'Choose models from this Agent configured catalog',
         NOT_OPEN: 'Open the digital person first',
+        NOT_FOUND: 'Digital person task or child not found',
+        TASK_SCOPE_DENIED: 'Digital person task access denied',
+        TASK_CONTROL_UNAVAILABLE: 'Task control could not be confirmed; refresh before retrying',
         STALE: 'Digital person state changed; refresh and try again',
         IDEMPOTENCY_CONFLICT: 'This message identifier already belongs to a different request',
         STORAGE_MISMATCH: 'The configured storage differs from the existing Person authority; do not switch without a verified migration',

package/yeaft/person/contracts.js

@@ -20,6 +20,9 @@ const ERRORS = {
   ATTACHMENT_LIMIT: 'Attachments exceed the limit: 4 files, 5 MiB each, 10 MiB total; text plus extracted content must fit 24 KiB.',
   IMAGE_MODEL: 'The selected model does not permit image input.',
   CLOSED: 'The digital person service is closed.',
+  NOT_FOUND: 'Digital person task or child not found.',
+  TASK_SCOPE_DENIED: 'Digital person task access denied.',
+  TASK_CONTROL_UNAVAILABLE: 'Task control could not be confirmed; refresh before retrying.',
 };
 export class PersonError extends Error {
   constructor(code) { super(ERRORS[code] || ERRORS.INVALID_REQUEST); this.name = 'PersonError'; this.code = code in ERRORS ? code : 'INVALID_REQUEST'; }
@@ -58,6 +61,26 @@ export function page(payload = {}) {
   }
   return { cursor, limit };
 }
+/** Task APIs are explicit owner actions, not cognitive admissions. Logs are raw
+ * owner-scoped output; list/control responses never include native runtime/log/result.
+ * Lists cap each collection at 100, preferring live records then recent history.
+ * Log offsets count raw UTF-8 bytes; an omitted offset starts at the beginning.
+ */
+export const PERSON_TASK_LIMITS = Object.freeze({ records: 100, logBytes: 16384, maxLogBytes: 65536 });
+export function personTaskRequest(op, payload = {}) {
+  if (op === 'tasks') { object(payload, []); return {}; }
+  const idKey = op === 'agent_close' ? 'agentId' : 'taskId';
+  object(payload, op === 'task_log' ? ['taskId', 'offset', 'maxBytes'] : [idKey], [idKey]);
+  // Native TaskStore normalizes punctuation. Reject aliases instead of letting
+  // two browser IDs resolve to the same persisted task.
+  if (typeof payload[idKey] !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$/.test(payload[idKey])) fail('INVALID_REQUEST');
+  if (op !== 'task_log') return { [idKey]: payload[idKey] };
+  const offset = payload.offset === undefined ? 0 : payload.offset;
+  const maxBytes = payload.maxBytes === undefined ? PERSON_TASK_LIMITS.logBytes : payload.maxBytes;
+  if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > PERSON_TASK_LIMITS.maxLogBytes) fail('INVALID_REQUEST');
+  return { taskId: payload.taskId, offset, maxBytes };
+}
+
 const kinds = ['claim', 'question', 'method', 'self-model', 'scenario', 'interest'];
 const epistemics = ['reported', 'hypothesis', 'imagined', 'uncertain'];
 const activities = ['think', 'recall', 'reorganize', 'associate', 'rethink', 'imagine', 'respond', 'rest'];
@@ -130,4 +153,4 @@ Use the actual numeric baseStateVersion. New concept IDs use simple stable ident
 budget.remainingCalls includes this call. Reserve the final call for a proposal with next:null; An active Recall followed by a final proposal needs two calls total; search (with a returned contract), capability use and final proposal need three. Do not search or inspect an already active capability merely to follow stages. If evidence remains insufficient at the final call, record the uncertainty or rest instead of inventing a result. No additional call is granted after the budget ends.
 capabilities.active contains complete current contracts in foundation, familiar (actual execution observations), and discovered layers. Use any active capability directly; availability is not permission or a duty. Familiarity does not prove truth/usefulness; evaluate results in decision.selfCheck, ignore unhelpful habits, or rest. If no active ability fits, search or view a known catalog ID. Search prepares returned contracts; omitted contracts require view. Only rendered current contracts execute. No separate selector model or hidden cognition is involved.
 Capability.create tests pure JSON transformations in restricted QuickJS and publishes only passing versions to this Person's private catalog. Tests do not prove correctness/usefulness; publication is durable even if this episode fails. Follow its complete active contract. Script.* cannot access host tools, files, shell, network or credentials, grant permissions, install packages or run automatically. Search before duplicating existing capabilities; avoid embedding private data or one-off constants.
-Think is intrinsic: recall, reorganize, associate, reconsider, imagine or rest. You are the same enduring Person, not a task coordinator. Preserve uncertainty and self-check. Finish in one call or choose the next permitted model/effort and one capability with a brief reason. Intermediate proposals are NOT accepted state; only next:null commits the complete desired state/concept changes. Dream is idle imagination, not a user message or mandatory useful work; reply may be null.`;
+Think is intrinsic: recall, reorganize, associate, reconsider, imagine or rest. Own ongoing authorized work using task/child context, not only latest user text. Episode end is not task completion/cancellation; evidence never enables timers, autonomy or model re-entry. You remain one Person, not a task coordinator. Only next:null commits; intermediate proposals do not. Dream is idle imagination, not a user message or mandatory useful work; reply may be null.`;

package/yeaft/person/inspection.js

@@ -18,7 +18,7 @@ export function personName(value) {
   return text(value.trim(), 160);
 }
 const pick = (value, keys) => value == null ? null : Object.fromEntries(keys.filter(key => Object.hasOwn(value, key)).map(key => [key, value[key]]));
-export const settingsView = value => pick(value, ['autonomyEnabled', 'modelCandidates']);
+export const settingsView = value => pick(value, ['autonomyEnabled', 'modelCandidates', 'defaultModel']);
 export function messageView(value) {
   const result = pick(value, ['id', 'schemaVersion', 'revision', 'seq', 'episodeId', 'clientMessageId', 'role', 'text', 'createdAt']);
   if (result && Array.isArray(value.attachments)) result.attachments = value.attachments.slice(0, 4)

package/yeaft/person/provider.js

@@ -14,6 +14,29 @@ export function validateModelCandidates(refs) {
       new Set(refs).size !== refs.length) fail('MODEL_SELECTION');
 }
 
+export function validateDefaultModel(ref) {
+  if (ref !== null) validateModelCandidates([ref]);
+}
+
+/** Resolve router ownership before allowlisting or bounding the Person catalog. */
+export function resolveAgentDefaultModel(config) {
+  const models = config.availableModels || [], requested = config.primaryModel || config.model;
+  const model = models.find(m => (m.ref || m.id) === requested) || models.find(m => m.id === requested);
+  return model?.ref || (model?.id?.includes('/') ? model.id : null);
+}
+
+/** Shared validation for settings, status and runtime; never broaden an explicit subset. */
+export function selectPersonModels({ availableModels, modelCandidates = [], defaultModel = null }) {
+  validateModelCandidates(modelCandidates);
+  validateDefaultModel(defaultModel);
+  if (modelCandidates.some(ref => !availableModels.some(model => model.id === ref))) fail('MODEL_SELECTION');
+  const catalog = modelCandidates.length ? availableModels.filter(model => modelCandidates.includes(model.id))
+    : availableModels.slice(0, MODEL_LIMITS.candidates);
+  if (defaultModel !== null && !catalog.some(model => model.id === defaultModel)) fail('MODEL_SELECTION');
+  if (!catalog.length) fail('MODEL_UNAVAILABLE');
+  return { catalog, defaultSelection: { model: defaultModel ?? catalog[0].id, effort: null } };
+}
+
 // Bounds apply to the actual wire protocol, not a vision flag or compressed file size.
 // OpenAI tile models (including 2833 base tokens for gpt-4o-mini) have a fixed
 // cost only at explicit low detail. Known patch models below fit <=6144 patches
@@ -38,17 +61,13 @@ function imageInputBudget(modelId, protocol) {
 }
 
 /** Only configured native API models; no Session initialization or implicit credential fallback. */
-export async function createPersonProvider({ yeaftDir, config: suppliedConfig, adapter: suppliedAdapter, allowedModels, effortEnabled = process.env.YEAFT_THINKING_V1 === '1', modelCandidates = [] }) {
+export async function createPersonProvider({ yeaftDir, config: suppliedConfig, adapter: suppliedAdapter, allowedModels, effortEnabled = process.env.YEAFT_THINKING_V1 === '1', modelCandidates = [], defaultModel = null }) {
   const config = structuredClone(suppliedConfig || loadConfig({ dir: yeaftDir }));
   if (!config.providers?.length && !suppliedAdapter) fail('MODEL_UNAVAILABLE');
   const models = config.availableModels || [];
-  const requestedDefault = config.primaryModel || config.model;
-  // Match router ownership: exact qualified ref first; bare IDs use the first
-  // configured provider. Resolve before allowlisting, sorting or truncating.
-  const defaultModel = models.find(m => (m.ref || m.id) === requestedDefault)
-    || models.find(m => m.id === requestedDefault);
-  const defaultRef = defaultModel?.ref || defaultModel?.id;
+  const agentDefaultModel = resolveAgentDefaultModel(config);
   validateModelCandidates(modelCandidates);
+  validateDefaultModel(defaultModel);
   const available = models.filter(m => !allowedModels || allowedModels.includes(m.ref || m.id));
   const routingProviders = (config.providers || []).map(normalizeKnownProviderForRuntime);
   const safeModels = available.map(m => {
@@ -76,19 +95,16 @@ export async function createPersonProvider({ yeaftDir, config: suppliedConfig, a
     return { id: m.ref || m.id, efforts, maxOutput, supportsImages: imageBudget !== null, imageBudget,
       contextWindow: Math.floor(resolveContextWindow(m.id, { ...config, modelInfo: m })) };
   }).filter(m => typeof m.id === 'string' && m.id.length <= 256 && m.contextWindow > m.maxOutput + 1024 && m.maxOutput >= 256);
-  safeModels.sort((a, b) => Number(b.id === defaultRef) - Number(a.id === defaultRef));
+  safeModels.sort((a, b) => Number(b.id === agentDefaultModel) - Number(a.id === agentDefaultModel));
   const seen = new Set();
   const uniqueModels = safeModels.filter(model => !seen.has(model.id) && seen.add(model.id));
   const availableModels = uniqueModels.slice(0, MODEL_LIMITS.available);
   // A UI catalog must not be the bounded episode choice set: model 9+ remains selectable.
   // Explicit lists are validated, never silently truncated or broadened on stale config.
-  if (modelCandidates.some(ref => !availableModels.some(model => model.id === ref))) fail('MODEL_SELECTION');
-  const catalog = modelCandidates.length ? availableModels.filter(model => modelCandidates.includes(model.id))
-    : availableModels.slice(0, MODEL_LIMITS.candidates);
-  if (!catalog.length) fail('MODEL_UNAVAILABLE');
+  const { catalog, defaultSelection } = selectPersonModels({ availableModels, modelCandidates, defaultModel });
   const adapter = suppliedAdapter || await createLLMAdapter(config);
   return { adapter, catalog, availableModels, availableModelsTruncated: uniqueModels.length > MODEL_LIMITS.available,
-    catalogRevision: digest(catalog), defaultSelection: { model: catalog[0].id, effort: null }, effortEnabled };
+    catalogRevision: digest(catalog), defaultSelection, agentDefaultModel, effortEnabled };
 }
 
 export function abortable(promise, signal) {

package/yeaft/person/repository.js

@@ -109,7 +109,7 @@ export class MongoPersonRepository {
         if (!p) {
           p = this.doc(scope, {
             name, soul: 'A continuous, curious and honest digital person. Preserve uncertainty, reconsider your judgments, distinguish imagination from experience, and respect permissions. You may disagree without acting without authority.',
-            soulRevision: 1, createdAt: new Date(), settings: { autonomyEnabled: false },
+            soulRevision: 1, createdAt: new Date(), settings: { autonomyEnabled: false, defaultModel: null },
             epoch: 0, writeSerial: 0, inputWatermark: 0, controlVersion: 0, stateVersion: 0,
             traceSeq: 0, messageSeq: 0, activeEpisodeId: null, leaseOwner: null, leaseUntil: new Date(0),
           });
@@ -198,7 +198,7 @@ export class MongoPersonRepository {
         messageId = randomUUID();
         await this.collections.messages.insertOne(this.doc(scope, { id: messageId, revision: 1, seq: p.messageSeq, episodeId: id, role: 'user', text, attachments, createdAt: new Date(), clientMessageId }), { session });
       }
-      const episode = this.doc(scope, { id, clientMessageId, requestHash, kind, text, messageId, attachments, modelCandidates: [...(p.settings.modelCandidates ?? [])], status: 'running', workerId, epoch: p.epoch,
+      const episode = this.doc(scope, { id, clientMessageId, requestHash, kind, text, messageId, attachments, modelCandidates: [...(p.settings.modelCandidates ?? [])], defaultModel: p.settings.defaultModel ?? null, status: 'running', workerId, epoch: p.epoch,
         baseStateVersion: p.stateVersion, inputWatermark: p.inputWatermark, controlVersion: p.controlVersion, budget, createdAt: new Date() });
       await this.collections.episodes.insertOne(episode, { session });
       await this.trace(session, p, id, 'accepted', { trigger: { kind, text, messageId, attachments }, baseStateVersion: p.stateVersion, budget });
@@ -455,12 +455,13 @@ export class MongoPersonRepository {
       return { cancelled: true, episodeId: p.activeEpisodeId };
     });
   }
-  async settings(ownerId, settings) {
+  async settings(ownerId, settings, expectedControlVersion) {
     return this.transaction(async session => {
       const scope = this.scope(ownerId);
       const p = await this.collections.persons.findOne(scope, { session });
       if (!p) fail('NOT_OPEN');
       if (p.activeEpisodeId) fail('BUSY'); // No implicit background API or deferred control effects.
+      if (expectedControlVersion !== undefined && p.controlVersion !== expectedControlVersion) fail('STALE');
       const { name, ...patch } = settings;
       if (Object.hasOwn(settings, 'name')) p.name = personName(name);
       // A partial update must preserve durable fields omitted from the public view.

package/yeaft/person/runtime.js

@@ -201,7 +201,7 @@ export class PersonRuntime {
     }, Math.max(100, Math.floor(this.repository.leaseMs / 3)));
     heartbeat.unref?.();
     try {
-      const provider = await abortable(this.getProvider(episode.modelCandidates ?? []), signal);
+      const provider = await abortable(this.getProvider(episode.modelCandidates ?? [], episode.defaultModel ?? null), signal);
       const snapshot = await abortable(this.repository.context(episode), signal);
       const attachments = episode.attachments?.length ? await abortable(this.repository.episodeAttachments(episode), signal) : [];
       // Bind recovered evidence using the repository's authoritative Person ID,
@@ -209,7 +209,7 @@ export class PersonRuntime {
       await this.tasks()?.context({ episode, parentToolRegistry: this.parentToolRegistry });
       signal.throwIfAborted();
       let selection = { ...provider.defaultSelection, reason: 'configured-default', origin: 'bootstrap' };
-      if (snapshot.state.lastSelection) {
+      if (episode.defaultModel == null && snapshot.state.lastSelection) {
         try { validateSelection(snapshot.state.lastSelection, provider.catalog); selection = { ...snapshot.state.lastSelection, reason: 'last-accepted-choice', origin: 'persisted' }; }
         catch { await this.repository.append(episode, 'selection_rejected', { requested: snapshot.state.lastSelection, code: 'MODEL_SELECTION', fallback: 'configured-default' }); }
       }

package/yeaft/person/service.js

@@ -6,8 +6,8 @@ import { PersonRuntime } from './runtime.js';
 import { allowedNativeToolIds } from './native-tools.js';
 import { loadConfig } from '../config.js';
 import { validateFiles } from './attachments.js';
-import { createPersonProvider, validateModelCandidates } from './provider.js';
-import { fail, identifier, LIMITS, object, page, safeError, text } from './contracts.js';
+import { createPersonProvider, resolveAgentDefaultModel, selectPersonModels, validateDefaultModel, validateModelCandidates } from './provider.js';
+import { fail, identifier, LIMITS, object, page, personTaskRequest, safeError, text } from './contracts.js';
 import { inspectRequest, personName, searchRequest } from './inspection.js';
 
 /**
@@ -46,7 +46,7 @@ export function createPersonService(options = {}) {
   if (memory) repository.recall = (ownerId, args = {}, { signal } = {}) => args.query?.trim()
     ? memory.recall(ownerId, args, { signal }) : literalRecall(ownerId, args);
   // Config/adapter are loaded per explicit episode, not a permanent stale cache.
-  const getProvider = (modelCandidates = []) => createPersonProvider({ yeaftDir, config, adapter, allowedModels, modelCandidates, effortEnabled: options.effortEnabled });
+  const getProvider = (modelCandidates = [], defaultModel = null) => createPersonProvider({ yeaftDir, config, adapter, allowedModels, modelCandidates, defaultModel, effortEnabled: options.effortEnabled });
   const runtime = new PersonRuntime({ repository, getProvider, budget: { calls, timeoutMs }, workDir, yeaftDir, config, namespace });
   let closed = false;
   const requests = new Set();
@@ -56,23 +56,32 @@ export function createPersonService(options = {}) {
     if (typeof op !== 'string') fail('INVALID_REQUEST');
     if (op === 'status') {
       object(payload, []);
-      if (!configured) return { renameSupported: true, configured: false, storage, reason: 'Digital person storage configuration is missing.', storageReady: false, modelReady: false };
+      let agentDefaultModel = null;
+      try { agentDefaultModel = resolveAgentDefaultModel(config ?? loadConfig({ dir: yeaftDir })); } catch { /* Invalid/missing native config. */ }
+      const status = { renameSupported: true, defaultModelSupported: true, configured, storage, modelReady: false,
+        defaultModel: null, agentDefaultModel, modelCandidates: [], effectiveModelCandidates: [], effectiveDefaultModel: null };
+      if (!configured) return { ...status, reason: 'Digital person storage configuration is missing.', storageReady: false };
       try { await repository.init(); }
-      catch (error) { return { renameSupported: true, configured: true, storage, reason: safeError(error).message, storageReady: false, modelReady: false }; }
-      let modelCandidates = [];
-      try { modelCandidates = (await repository.getPerson(ownerId)).settings.modelCandidates ?? []; }
-      catch (error) { if (error.code !== 'NOT_OPEN') throw error; }
+      catch (error) { return { ...status, reason: safeError(error).message, storageReady: false }; }
+      try {
+        const settings = (await repository.getPerson(ownerId)).settings;
+        status.modelCandidates = settings.modelCandidates ?? [];
+        status.defaultModel = settings.defaultModel ?? null;
+      } catch (error) { if (error.code !== 'NOT_OPEN') throw error; }
       try {
         const provider = await getProvider();
-        let modelReady = true;
         try {
-          validateModelCandidates(modelCandidates);
-          if (modelCandidates.some(ref => !provider.availableModels.some(model => model.id === ref))) modelReady = false;
-        } catch { modelReady = false; }
-        return { renameSupported: true, configured: true, storage, reason: modelReady ? null : 'Saved model candidates are unavailable; choose models or reset to Agent defaults.',
-          storageReady: true, modelReady, models: provider.availableModels, availableModels: provider.availableModels,
-          availableModelsTruncated: provider.availableModelsTruncated, modelCandidates, autonomySupported: false };
-      } catch { return { renameSupported: true, configured: true, storage, reason: 'No permitted native model is configured for digital person.', storageReady: true, modelReady: false, models: [], availableModels: [], modelCandidates }; }
+          const selected = selectPersonModels({ availableModels: provider.availableModels,
+            modelCandidates: status.modelCandidates, defaultModel: status.defaultModel });
+          status.modelReady = true;
+          status.effectiveModelCandidates = selected.catalog.map(model => model.id);
+          status.effectiveDefaultModel = selected.defaultSelection.model;
+        } catch { /* Stale settings remain visible, but do not grant fallback candidates. */ }
+        return { ...status, agentDefaultModel: provider.agentDefaultModel,
+          reason: status.modelReady ? null : 'Saved model settings are unavailable; choose models or reset to Agent defaults.',
+          storageReady: true, models: provider.availableModels, availableModels: provider.availableModels,
+          availableModelsTruncated: provider.availableModelsTruncated, autonomySupported: false };
+      } catch { return { ...status, reason: 'No permitted native model is configured for digital person.', storageReady: true, models: [], availableModels: [] }; }
     }
     if (!configured) fail('NOT_CONFIGURED');
     switch (op) {
@@ -81,6 +90,16 @@ export function createPersonService(options = {}) {
         if (payload.name != null) text(payload.name, 160);
         return repository.open(ownerId, payload.name);
       }
+      case 'tasks':
+      case 'task_log':
+      case 'task_cancel':
+      case 'agent_close': {
+        const args = personTaskRequest(op, payload);
+        const person = await repository.getPerson(ownerId);
+        const host = runtime.tasks();
+        if (!host) fail('UNSUPPORTED');
+        return host.request({ ownerId, personId: person.personId, namespace, op, payload: args });
+      }
       case 'snapshot': object(payload, []); return repository.snapshot(ownerId);
       case 'receipt': {
         object(payload, ['clientMessageId', 'requestHash'], ['clientMessageId']);
@@ -133,21 +152,30 @@ export function createPersonService(options = {}) {
         } finally { release(); }
       }
       case 'settings': {
-        object(payload, ['name', 'autonomyEnabled', 'modelCandidates'], []);
+        object(payload, ['name', 'autonomyEnabled', 'modelCandidates', 'defaultModel'], []);
         const patch = { ...payload };
         if (Object.hasOwn(patch, 'name')) patch.name = personName(patch.name);
         if (Object.hasOwn(payload, 'autonomyEnabled') && typeof payload.autonomyEnabled !== 'boolean') fail('INVALID_REQUEST');
-        if (Object.hasOwn(payload, 'modelCandidates')) {
-          const refs = payload.modelCandidates;
-          validateModelCandidates(refs);
-          if (refs.length) {
+        if (Object.hasOwn(payload, 'modelCandidates')) validateModelCandidates(payload.modelCandidates);
+        if (Object.hasOwn(payload, 'defaultModel')) validateDefaultModel(payload.defaultModel);
+        // Timer-driven autonomy is deliberately not claimed or silently enabled.
+        if (payload.autonomyEnabled === true) fail('UNSUPPORTED');
+        let expectedControlVersion;
+        if (Object.hasOwn(payload, 'modelCandidates') || Object.hasOwn(payload, 'defaultModel')) {
+          const prior = await repository.getPerson(ownerId);
+          if (prior.activeEpisodeId) fail('BUSY');
+          const merged = { modelCandidates: [], defaultModel: null, ...prior.settings, ...patch };
+          validateModelCandidates(merged.modelCandidates);
+          validateDefaultModel(merged.defaultModel);
+          // An automatic reset must also work when no model is currently available.
+          if (merged.modelCandidates.length || merged.defaultModel !== null) {
             const provider = await getProvider();
-            if (refs.some(ref => !provider.availableModels.some(model => model.id === ref))) fail('MODEL_SELECTION');
+            selectPersonModels({ availableModels: provider.availableModels, modelCandidates: merged.modelCandidates, defaultModel: merged.defaultModel });
           }
+          // Fence the merge base across concurrent services; retry from fresh settings.
+          expectedControlVersion = prior.controlVersion;
         }
-        // Timer-driven autonomy is deliberately not claimed or silently enabled.
-        if (payload.autonomyEnabled === true) fail('UNSUPPORTED');
-        return repository.settings(ownerId, patch);
+        return repository.settings(ownerId, patch, expectedControlVersion);
       }
       default: fail('INVALID_REQUEST');
     }

package/yeaft/person/sqlite-repository.js

@@ -103,7 +103,7 @@ export class SqlitePersonRepository {
   async commit(episode, proposal, selection, callId, reportedSources = new Map()) { return this.request('commit', [episode, proposal, selection, callId, reportedSources]); }
   async finish(episode, status, code) { return this.request('finish', [episode, status, code]); }
   async cancel(ownerId, episodeId) { return this.request('cancel', [ownerId, episodeId]); }
-  async settings(ownerId, settings) { return this.request('settings', [ownerId, settings]); }
+  async settings(ownerId, settings, expectedControlVersion) { return this.request('settings', [ownerId, settings, expectedControlVersion]); }
   async list(ownerId, collection, options, filter) { return this.request('list', [ownerId, collection, options, filter]); }
   async snapshot(ownerId) { return this.request('snapshot', [ownerId]); }
   async inspect(ownerId, options, nativeToolIds) { return this.request('inspect', [ownerId, options, nativeToolIds]); }

package/yeaft/person/sqlite-store.js

@@ -151,7 +151,7 @@ export class SqlitePersonStore {
     if (!p) {
       p = this.doc(scope, {
         name, soul: 'A continuous, curious and honest digital person. Preserve uncertainty, reconsider your judgments, distinguish imagination from experience, and respect permissions. You may disagree without acting without authority.',
-        soulRevision: 1, createdAt: this.now, settings: { autonomyEnabled: false },
+        soulRevision: 1, createdAt: this.now, settings: { autonomyEnabled: false, defaultModel: null },
         epoch: 0, writeSerial: 0, inputWatermark: 0, controlVersion: 0, stateVersion: 0,
         traceSeq: 0, messageSeq: 0, activeEpisodeId: null, leaseOwner: null, leaseUntil: new Date(0),
       });
@@ -223,7 +223,7 @@ export class SqlitePersonStore {
       const message = this.doc(scope, { id: messageId, revision: 1, seq: p.messageSeq, episodeId: id, role: 'user', text: input, attachments, createdAt: this.now, clientMessageId });
       this.put('messages', message, true); this.journal(scope, 'messages', message);
     }
-    const episode = this.doc(scope, { id, clientMessageId, requestHash, kind, text: input, messageId, attachments, modelCandidates: [...(p.settings.modelCandidates ?? [])], status: 'running', workerId, epoch: p.epoch,
+    const episode = this.doc(scope, { id, clientMessageId, requestHash, kind, text: input, messageId, attachments, modelCandidates: [...(p.settings.modelCandidates ?? [])], defaultModel: p.settings.defaultModel ?? null, status: 'running', workerId, epoch: p.epoch,
       baseStateVersion: p.stateVersion, inputWatermark: p.inputWatermark, controlVersion: p.controlVersion, budget, createdAt: this.now });
     this.put('episodes', episode, true);
     this.trace(ownerId, id, 'accepted', { trigger: { kind, text: input, messageId, attachments }, baseStateVersion: p.stateVersion, budget });
@@ -419,9 +419,10 @@ export class SqlitePersonStore {
     this.trace(ownerId, id, 'cancelled', { code: 'CANCELLED' });
     return { cancelled: true, episodeId: id };
   }
-  settings(ownerId, settings) {
+  settings(ownerId, settings, expectedControlVersion) {
     const p = this.getPerson(ownerId);
     if (p.activeEpisodeId) fail('BUSY');
+    if (expectedControlVersion !== undefined && p.controlVersion !== expectedControlVersion) fail('STALE');
     const { name, ...patch } = settings;
     if (Object.hasOwn(settings, 'name')) p.name = personName(name);
     // A partial update must preserve durable fields omitted from the public view.

package/yeaft/person/task-host.js

@@ -10,9 +10,10 @@ import { agentBelongsToScope, getAgentRegistry } from '../tools/agent.js';
 import closeAgent from '../tools/close-agent.js';
 import { consumeNotificationForAgent } from '../sub-agent/notifications.js';
 import { isTerminalAgentStatus } from '../sub-agent/status.js';
+import { describeAgentOutcome } from '../sub-agent/outcome.js';
 import { NullTrace } from '../debug-trace.js';
 import { loadConfig } from '../config.js';
-import { digest } from './contracts.js';
+import { digest, fail, PERSON_TASK_LIMITS, personTaskRequest } from './contracts.js';
 
 // Deliberately not the full Session registry: no transcript search, routing,
 // interactive UI, MCP, Work Center, or nested orchestration authority.
@@ -56,6 +57,38 @@ function privatePath(root, path) {
   return path;
 }
 
+// Human-authored summaries can contain incidental credentials/paths. Do not
+// expose native command fallbacks; redact common sensitive forms before capping.
+function summary(value, maxBytes = 512) {
+  const clean = String(value ?? '')
+    .replace(/https?:\/\/\S+|mongodb(?:\+srv)?:\/\/\S+/gi, '[url]')
+    .replace(/(?:bearer\s+|(?:api[_-]?key|password|secret|token)\s*[:=]\s*)\S+/gi, '[redacted]')
+    .replace(/\b(?:sk-[\w-]+|gh[pousr]_[\w]+|github_pat_[\w]+)\b/g, '[redacted]')
+    .replace(/(?:\/[\w.@~+-]+)+(?:\/[^\s]*)?|(?:~|\.\.?|[A-Za-z]:)[\\/][^\s]+/g, '[path]')
+    .replace(/[\u0000-\u001f\u007f]/g, ' ');
+  let out = '';
+  for (const char of clean) { if (Buffer.byteLength(out + char) > maxBytes) break; out += char; }
+  return out;
+}
+function projectedTask(task) {
+  const commandFallback = task.kind === 'shell' && task.runtime?.command?.startsWith(task.title);
+  return { id: task.id, title: commandFallback ? 'Shell task' : summary(task.title), kind: task.kind, status: task.status,
+    createdAt: task.createdAt ?? null, updatedAt: task.updatedAt ?? null,
+    sourceEpisodeId: task.source?.episodeId ?? null, agentId: task.runtime?.subAgentId ?? null,
+    recoveryStatus: task.status === 'orphaned' ? 'orphaned' : null };
+}
+function projectedAgent(agent, executionPending) {
+  const usage = Object.fromEntries(['tokens', 'turns', 'startedAt'].map(key => [key,
+    Number.isFinite(agent.usage?.[key]) && agent.usage[key] >= 0 ? agent.usage[key] : 0]));
+  // Only the helper's fixed outcome vocabulary crosses this boundary, never the
+  // native result, budget reason, final report, or partial output.
+  const { status, complete, reason, truncated } = describeAgentOutcome(agent);
+  return { id: agent.id, name: summary(agent.name, 160), status: agent.status,
+    outcome: { status, complete, reason, truncated }, executionPending,
+    mission: summary(agent.mission ?? agent.task, 1024), usage, createdAt: agent.createdAt ?? null,
+    sourceEpisodeId: agent.personEpisodeId ?? null, recoveryStatus: agent.recoveryStatus === 'orphaned' ? 'orphaned' : null };
+}
+
 function atomicJSON(path, value) {
   const temporary = `${path}.${randomUUID()}.tmp`;
   writeFileSync(temporary, `${JSON.stringify(value)}\n`, { mode: 0o600 });
@@ -87,6 +120,7 @@ class ScopedPersonTaskHost {
   #options;
   #agentEpisodes = new Map();
   #instrumentedAgents = new WeakSet();
+  #observedDrivers = new WeakMap();
 
   constructor(options = {}) {
     this.scope = Object.freeze(identity(options));
@@ -177,13 +211,20 @@ class ScopedPersonTaskHost {
     });
   }
 
+  #executionPending(agent) {
+    const live = getAgentRegistry().get(agent.id);
+    return Boolean(live && agentBelongsToScope(live, this.agentScope)
+      && (live.__driverStarted || [...this.#calls].some(call => call.childId === agent.id)));
+  }
+
   #persistAgents() {
     for (const agent of getAgentRegistry().values()) {
       if (!agentBelongsToScope(agent, this.agentScope)) continue;
       const fields = ['id', 'name', 'task', 'mission', 'persona', 'budget', 'allowTools', 'status', 'result', 'lastResult',
         'partial_output', 'error', 'outputFile', 'taskId', 'usage', 'createdAt', 'liveness', 'diagnostics', 'finalReport',
-        'parentSessionId', 'parentVpId', 'parentThreadId', 'recoveryStatus', 'personEpisodeId'];
-      this.#agents.set(agent.id, Object.fromEntries(fields.filter(key => agent[key] !== undefined).map(key => [key, clone(agent[key])])));
+        'finalizationRequested', 'parentSessionId', 'parentVpId', 'parentThreadId', 'recoveryStatus', 'personEpisodeId'];
+      this.#agents.set(agent.id, { ...Object.fromEntries(fields.filter(key => agent[key] !== undefined).map(key => [key, clone(agent[key])])),
+        executionPending: this.#executionPending(agent) });
     }
     atomicJSON(join(this.dataRoot, 'agents.json'), { scope: this.scope, agents: [...this.#agents.values()] });
   }
@@ -195,13 +236,14 @@ class ScopedPersonTaskHost {
     if (digest(saved.scope) !== digest(this.scope)) throw denied();
     for (const record of saved.agents ?? []) {
       if (!agentBelongsToScope(record, this.agentScope)) throw denied();
-      if (!isTerminalAgentStatus(record.status)) {
-        // Native Agent status has no orphaned state; make it terminal failed,
-        // retain the precise recovery fact, and let TaskManager orphan its task.
-        record.status = 'failed';
+      if (!isTerminalAgentStatus(record.status) || record.executionPending === true) {
+        // A terminal driver can still have detached tool effects. Preserve its
+        // outcome, but never claim recovered control of those effects.
+        if (!isTerminalAgentStatus(record.status)) record.status = 'failed';
         record.recoveryStatus = 'orphaned';
-        record.error = 'Agent restarted while child was running; child control was lost.';
+        record.error = 'Agent restarted while child execution was pending; child control was lost.';
       }
+      record.executionPending = false; // Only current live handles prove pending execution.
       const existing = getAgentRegistry().get(record.id);
       if (existing && !agentBelongsToScope(existing, this.agentScope)) throw denied();
       if (existing?.__driverStarted) throw Object.assign(new Error('Child driver is still live'), { code: 'TASK_HOST_BUSY' });
@@ -332,8 +374,13 @@ class ScopedPersonTaskHost {
       return output;
     }).catch(error => { this.#archiveToolResult(job, null, error); throw error; });
     this.#calls.add(job);
+    if (job.childId) this.#persistAgents();
     try { return await job.promise; }
-    finally { this.#calls.delete(job); caller.signal?.removeEventListener('abort', abort); }
+    finally {
+      this.#calls.delete(job);
+      caller.signal?.removeEventListener('abort', abort);
+      if (job.childId) this.#persistAgents();
+    }
   }
 
   #archiveToolResult(job, output, error) {
@@ -348,6 +395,12 @@ class ScopedPersonTaskHost {
     if (!agent || !agentBelongsToScope(agent, this.agentScope)) return;
     agent.personEpisodeId = deps.episodeId;
     this.#agentEpisodes.set(agent.id, deps.episodeId);
+    if (agent.driverPromise && this.#observedDrivers.get(agent) !== agent.driverPromise) {
+      this.#observedDrivers.set(agent, agent.driverPromise);
+      // Terminal events precede driver cleanup. Persist after cleanup too so a
+      // cleanly completed child is not falsely recovered as orphaned.
+      agent.driverPromise.then(() => this.#persistAgents(), () => this.#persistAgents()).catch(() => {});
+    }
     const registry = agent.subEngine?.toolRegistry;
     if (!registry || this.#instrumentedAgents.has(agent)) return;
     this.#instrumentedAgents.add(agent);
@@ -380,6 +433,62 @@ class ScopedPersonTaskHost {
     return this.evidence();
   }
 
+  #ownedTask(taskId) {
+    privatePath(this.yeaftDir, this.#manager.store.taskPath(this.sessionId, taskId));
+    const task = this.taskManager.getTask(this.sessionId, taskId);
+    if (!task || task.id !== taskId || task.sessionId !== this.sessionId) fail('NOT_FOUND');
+    return task;
+  }
+
+  /** Owner-facing inspection/control: never attach a provider, schedule cognition
+   * or cancel unrelated work. Native snapshots remain private to evidence(). */
+  async request({ ownerId, personId, namespace = this.scope.namespace, op, payload = {} } = {}) {
+    if (ownerId !== this.scope.ownerId || personId !== this.scope.personId || namespace !== this.scope.namespace) throw denied();
+    this.#assertOpen();
+    const args = personTaskRequest(op, payload);
+    switch (op) {
+      case 'tasks': {
+        this.#persistAgents();
+        const tasks = jsonFiles(this.#manager.store.sessionDir(this.sessionId))
+          .filter(task => task.sessionId === this.sessionId && task.ownerVpId === this.parentVpId && ['shell', 'sub_agent'].includes(task.kind));
+        const agents = [...this.#agents.values()].filter(agent => agentBelongsToScope(agent, this.agentScope));
+        const recent = (items, settled) => items.sort((a, b) => Number(settled(a)) - Number(settled(b))
+          || String(b.updatedAt ?? b.createdAt ?? '').localeCompare(String(a.updatedAt ?? a.createdAt ?? ''))).slice(0, PERSON_TASK_LIMITS.records);
+        // A terminal driver with actual tools still running is active work, not
+        // disposable history: keep its cleanup control ahead of settled records.
+        return { tasks: recent(tasks, task => isTerminalTaskStatus(task.status)).map(projectedTask),
+          agents: recent(agents, agent => isTerminalAgentStatus(agent.status) && !agent.executionPending).map(agent => projectedAgent(agent, agent.executionPending)),
+          truncated: tasks.length > PERSON_TASK_LIMITS.records || agents.length > PERSON_TASK_LIMITS.records };
+      }
+      case 'task_log': {
+        const task = this.#ownedTask(args.taskId);
+        this.#privateLog(task.log?.path || this.#manager.store.logPath(this.sessionId, args.taskId));
+        const log = this.taskManager.readTaskLog(this.sessionId, args.taskId, { offset: args.offset, maxBytes: args.maxBytes, tail: false });
+        return { taskId: args.taskId, text: log.text, nextOffset: log.nextOffset, totalBytes: log.bytes, truncated: log.truncated === true, status: task.status };
+      }
+      case 'task_cancel': {
+        const task = this.#ownedTask(args.taskId);
+        if (task.kind !== 'shell') fail('INVALID_REQUEST');
+        // Orphaned is terminal metadata, not proof that external effects stopped.
+        if (task.status === 'orphaned') fail('TASK_CONTROL_UNAVAILABLE');
+        const result = this.taskManager.cancelTask(this.sessionId, args.taskId);
+        if (!result.ok) fail('TASK_CONTROL_UNAVAILABLE');
+        return { task: projectedTask(await this.#joinShell(args.taskId)), pending: false };
+      }
+      case 'agent_close': {
+        const agent = getAgentRegistry().get(args.agentId);
+        if (!agent || !agentBelongsToScope(agent, this.agentScope)) fail('NOT_FOUND');
+        if (agent.recoveryStatus === 'orphaned') fail('TASK_CONTROL_UNAVAILABLE');
+        const result = JSON.parse(await closeAgent.execute({ agent_id: agent.id }, { sessionId: this.sessionId,
+          parentEngineDeps: this.agentScope, taskManager: this.taskManager }));
+        if (!result.success) fail('TASK_CONTROL_UNAVAILABLE');
+        await this.#joinAgent(agent);
+        return { agent: projectedAgent(agent, this.#executionPending(agent)), pending: false };
+      }
+      default: fail('INVALID_REQUEST');
+    }
+  }
+
   /** Convenience for non-Registry embedding; returns the untruncated native output. */
   async execute(id, args, ctx = {}, options) {
     const attached = await this.attach(ctx, options);
@@ -508,6 +617,12 @@ export class PersonTaskHost {
 
   snapshot(ownerId) { return this.#host(ownerId).snapshot(ownerId); }
 
+  request(input = {}) {
+    if (typeof input.ownerId !== 'string' || !input.ownerId || typeof input.personId !== 'string' || !input.personId
+        || input.namespace !== this.#options.namespace) throw denied();
+    return this.#host(input.ownerId, input.personId).request(input);
+  }
+
   cancel(input = {}) {
     if (this.#bound) return this.#bound.cancel(input);
     if (!input || typeof input.ownerId !== 'string' || !input.ownerId) throw denied();