@xingular/harness 1.1.1 → 1.2.0

package/dist/sdk/accounts/accounts.d.ts

@@ -3,8 +3,8 @@ import { type Bus } from "../core/bus.js";
 import type { RunEvent, RunRecord } from "../sessions/contracts.js";
 import * as choices from "./choices.js";
 import * as env from "./env.js";
-import { type SecretStore } from "./secrets.js";
-import type { Account, AccountsOverview } from "./store.js";
+import { type CredentialLockOptions, type SecretStore } from "./secrets.js";
+import type { Account, AccountsOverview, Limit } from "./store.js";
 export type IssueCategory = 'auth_expired' | 'rate_limited' | 'quota' | 'network' | 'unknown';
 /** Best-effort classification of a provider error message. */
 export declare function classifyMessage(message: string): IssueCategory | null;
@@ -35,11 +35,13 @@ export interface AccountsOptions {
     dir: string;
     secrets: SecretStore;
     bus: Bus;
+    credentialLock?: CredentialLockOptions;
 }
 export declare class Accounts {
     readonly dir: string;
     private readonly secrets;
     private readonly bus;
+    private readonly credentialLockOptions;
     private readonly runtimes;
     private readonly logins;
     private readonly latestLogins;
@@ -48,6 +50,11 @@ export declare class Accounts {
     /** The credentials this process wrote to, or found in, each account's auth.json when its first terminal began. */
     private readonly terminalSnapshots;
     private installationDeviceIdPromise;
+    /**
+     * Lets the limits service observe each account runtime's provider responses. The Harness sets
+     * it once; with none, a runtime behaves exactly as before.
+     */
+    observeModels: ((models: unknown, accountId: string) => void) | null;
     constructor(options: AccountsOptions);
     private changed;
     overview(): AccountsOverview;
@@ -60,13 +67,17 @@ export declare class Accounts {
     resolve(accountId?: string | null, poolId?: string | null): Account;
     context(account: Account): env.AccountContext;
     readCredential(accountId: string, provider: string): Promise<Credential | null>;
+    private credentialLock;
     /** Stores a provider's credential, or removes it when `credential` is `null`. */
     writeCredential(accountId: string, provider: string, credential: Credential | null): Promise<void>;
+    /** The entire refresh read/modify/write is coordinated across services and processes. */
+    modifyCredential(accountId: string, provider: string, change: (current: Credential | undefined) => Promise<Credential | undefined>): Promise<Credential | undefined>;
+    private persistCredential;
     listCredentials(accountId: string): Promise<{
         providerId: string;
         type: 'api_key' | 'oauth';
     }[]>;
-    /** Pi's `CredentialStore` for one account. Writes are serialized, so a refresh never races another. */
+    /** Pi and explicit account edits share the same cross-process credential lock. */
     private credentialStore;
     /** Pi's OAuth device ID belongs to this Harness installation, not to one isolated account. */
     installationDeviceId(): Promise<string>;
@@ -160,6 +171,19 @@ export declare class Accounts {
     private releaseLease;
     /** Tracks account health and limits from run events. `run` is the event's run record, when it is known. */
     onRunEvent(event: RunEvent, run: RunRecord | null): void;
+    /**
+     * Records what a provider reported about its limits. An endpoint reading replaces that provider's
+     * limits; a header reading merges by id. Windows whose reset has passed are dropped. No credential
+     * is stored here.
+     */
+    applyLimits(accountId: string, readouts: readonly {
+        provider: string;
+        limits: Limit[];
+        source: 'headers' | 'provider' | 'estimate' | 'unavailable';
+        reason: string | null;
+        observedAt: string;
+        plan?: string | null;
+    }[]): AccountsOverview;
     private applyStatus;
 }
 export {};

package/dist/sdk/accounts/accounts.js

@@ -10,7 +10,7 @@ import { atomicWrite, now, readJson, safeId } from "../core/fs.js";
 import { loadPi } from "../pi/runtime.js";
 import * as choices from "./choices.js";
 import * as env from "./env.js";
-import { secretKey } from "./secrets.js";
+import { secretKey, withCredentialLock } from "./secrets.js";
 import * as store from "./store.js";
 /** Best-effort classification of a provider error message. */
 export function classifyMessage(message) {
@@ -64,6 +64,7 @@ export class Accounts {
     dir;
     secrets;
     bus;
+    credentialLockOptions;
     runtimes = new Map();
     logins = new Map();
     latestLogins = new Map();
@@ -72,10 +73,16 @@ export class Accounts {
     /** The credentials this process wrote to, or found in, each account's auth.json when its first terminal began. */
     terminalSnapshots = new Map();
     installationDeviceIdPromise = null;
+    /**
+     * Lets the limits service observe each account runtime's provider responses. The Harness sets
+     * it once; with none, a runtime behaves exactly as before.
+     */
+    observeModels = null;
     constructor(options) {
         this.dir = options.dir;
         this.secrets = options.secrets;
         this.bus = options.bus;
+        this.credentialLockOptions = options.credentialLock ?? {};
     }
     changed(payload = {}) {
         this.bus.emit({ type: 'accounts.changed', ...payload });
@@ -116,18 +123,40 @@ export class Accounts {
             return null;
         }
     }
+    credentialLock(key, work) {
+        return withCredentialLock(join(this.dir, '.credential-locks'), key, work, this.credentialLockOptions);
+    }
     /** Stores a provider's credential, or removes it when `credential` is `null`. */
     async writeCredential(accountId, provider, credential) {
         this.find(accountId);
         const name = validProvider(provider);
-        if (credential === null)
-            await this.secrets.delete(secretKey(accountId, `pi-auth/${name}`));
-        else
-            await this.secrets.set(secretKey(accountId, `pi-auth/${name}`), JSON.stringify(credential));
-        store.updateState(this.dir, accountId, (state) => {
-            state.piProviders = state.piProviders.filter((existing) => existing !== name);
-            if (credential !== null)
-                state.piProviders = [...state.piProviders, name].sort();
+        await this.credentialLock(`provider/${accountId}/${name}`, () => this.persistCredential(accountId, name, credential));
+    }
+    /** The entire refresh read/modify/write is coordinated across services and processes. */
+    async modifyCredential(accountId, provider, change) {
+        this.find(accountId);
+        const name = validProvider(provider);
+        return this.credentialLock(`provider/${accountId}/${name}`, async () => {
+            const current = (await this.readCredential(accountId, name)) ?? undefined;
+            const updated = await change(current);
+            if (updated !== undefined)
+                await this.persistCredential(accountId, name, updated);
+            return updated ?? current;
+        });
+    }
+    async persistCredential(accountId, name, credential) {
+        // Different providers still share the account's provider index. Keep its short commit serialized.
+        await this.credentialLock(`account/${accountId}`, async () => {
+            this.find(accountId);
+            if (credential === null)
+                await this.secrets.delete(secretKey(accountId, `pi-auth/${name}`));
+            else
+                await this.secrets.set(secretKey(accountId, `pi-auth/${name}`), JSON.stringify(credential));
+            store.updateState(this.dir, accountId, (state) => {
+                state.piProviders = state.piProviders.filter((existing) => existing !== name);
+                if (credential !== null)
+                    state.piProviders = [...state.piProviders, name].sort();
+            });
         });
     }
     async listCredentials(accountId) {
@@ -140,25 +169,13 @@ export class Accounts {
         }
         return listed;
     }
-    /** Pi's `CredentialStore` for one account. Writes are serialized, so a refresh never races another. */
+    /** Pi and explicit account edits share the same cross-process credential lock. */
     credentialStore(accountId) {
-        let chain = Promise.resolve();
-        const serialize = (work) => {
-            const next = chain.then(work);
-            chain = next.catch(() => undefined);
-            return next;
-        };
         return {
             read: async (providerId) => (await this.readCredential(accountId, providerId)) ?? undefined,
             list: () => this.listCredentials(accountId),
-            modify: (providerId, change) => serialize(async () => {
-                const current = (await this.readCredential(accountId, providerId)) ?? undefined;
-                const updated = await change(current);
-                if (updated !== undefined)
-                    await this.writeCredential(accountId, providerId, updated);
-                return updated ?? current;
-            }),
-            delete: (providerId) => serialize(() => this.writeCredential(accountId, providerId, null))
+            modify: (providerId, change) => this.modifyCredential(accountId, providerId, change),
+            delete: (providerId) => this.writeCredential(accountId, providerId, null)
         };
     }
     /** Pi's OAuth device ID belongs to this Harness installation, not to one isolated account. */
@@ -187,6 +204,14 @@ export class Accounts {
             const configDir = 'configDir' in account ? account.configDir : env.ensureHome(this.dir, account);
             runtime = loadPi()
                 .then(({ ModelRuntime }) => ModelRuntime.create({ credentials: this.credentialStore(id), modelsPath: join(configDir, 'models.json') }))
+                .then((created) => {
+                // Reading provider responses never changes what a request does; a broken observer is ignored.
+                try {
+                    this.observeModels?.(created, id);
+                }
+                catch { /* observation is best effort */ }
+                return created;
+            })
                 .catch((error) => {
                 this.runtimes.delete(id);
                 throw error;
@@ -690,6 +715,35 @@ export class Accounts {
                 this.changed({ accountId, health: state.health, previous });
         }
     }
+    /**
+     * Records what a provider reported about its limits. An endpoint reading replaces that provider's
+     * limits; a header reading merges by id. Windows whose reset has passed are dropped. No credential
+     * is stored here.
+     */
+    applyLimits(accountId, readouts) {
+        this.find(accountId);
+        const expired = (limit) => {
+            const time = limit.resetsAt ? Date.parse(limit.resetsAt) : Number.NaN;
+            return !Number.isNaN(time) && time <= Date.now();
+        };
+        store.updateState(this.dir, accountId, (state) => {
+            for (const readout of readouts) {
+                // An endpoint read is the provider's whole answer; a header read only adds what it saw.
+                const kept = new Map((readout.source === 'provider' ? [] : state.limits.filter((limit) => limit.provider === readout.provider && !expired(limit)))
+                    .map((limit) => [limit.id, limit]));
+                for (const limit of readout.limits)
+                    kept.set(limit.id, limit);
+                state.limits = [...state.limits.filter((limit) => limit.provider !== readout.provider), ...kept.values()];
+                const entry = { provider: readout.provider, source: readout.source, reason: readout.reason, observedAt: readout.observedAt };
+                state.providerLimits = [...state.providerLimits.filter((existing) => existing.provider !== readout.provider), entry];
+                if (readout.plan)
+                    state.plan = readout.plan;
+            }
+            state.limits.sort((left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0));
+        });
+        this.changed({ accountId });
+        return this.overview();
+    }
     applyStatus(event) {
         const payload = event.payload;
         if (typeof payload.accountId !== 'string')

package/dist/sdk/accounts/secrets.d.ts

@@ -3,6 +3,18 @@ export interface SecretStore {
     set(key: string, value: string): Promise<void>;
     delete(key: string): Promise<void>;
 }
+export interface CredentialLockOptions {
+    /** Acquisition only; an acquired callback is never unlocked while still running. */
+    timeoutMs?: number;
+    pollMs?: number;
+}
+/**
+ * Cross-process Lamport bakery lock. Unique participant directories make dead-pid reclamation
+ * safe: a stale cleanup can never unlink a successor's lock. No age-based stealing of live refreshes.
+ * The directory contains only hashed keys, pids, random IDs and tickets, never credential contents.
+ * All processes sharing a backend must use the same coordination directory on a local filesystem.
+ */
+export declare function withCredentialLock<T>(dir: string, key: string, work: () => Promise<T>, options?: CredentialLockOptions): Promise<T>;
 /** `<account id>/<secret name>`: the key an account's secret is stored under. */
 export declare const secretKey: (accountId: string, name: string) => string;
 /** Secrets held only for the life of the process. For tests and throwaway runs. */

package/dist/sdk/accounts/secrets.js

@@ -1,8 +1,115 @@
 // Where credentials live. The harness never writes a secret to its own files: it asks the
 // store the embedding application provides (a Keychain, an encrypted vault), by key.
-import { chmodSync, mkdirSync } from 'node:fs';
-import { dirname } from 'node:path';
-import { atomicWrite, readJsonOr } from "../core/fs.js";
+import { chmodSync, closeSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { readJsonOr } from "../core/fs.js";
+/** Exclusive temporary files are private before the first byte is written, not just after rename. */
+function privateWrite(path, value) {
+    const temporary = join(dirname(path), `.credential-${randomUUID()}.tmp`);
+    try {
+        const fd = openSync(temporary, 'wx', 0o600);
+        try {
+            writeFileSync(fd, value);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+        renameSync(temporary, path);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+/**
+ * Cross-process Lamport bakery lock. Unique participant directories make dead-pid reclamation
+ * safe: a stale cleanup can never unlink a successor's lock. No age-based stealing of live refreshes.
+ * The directory contains only hashed keys, pids, random IDs and tickets, never credential contents.
+ * All processes sharing a backend must use the same coordination directory on a local filesystem.
+ */
+export async function withCredentialLock(dir, key, work, options = {}) {
+    const timeout = options.timeoutMs ?? 30_000;
+    const poll = options.pollMs ?? 20;
+    if (!Number.isFinite(timeout) || timeout < 0 || timeout > 300_000 || !Number.isFinite(poll) || poll < 1 || poll > 1000) {
+        throw new Error('Invalid credential lock wait bounds.');
+    }
+    const started = performance.now();
+    const folder = join(dir, createHash('sha256').update(key).digest('hex'));
+    mkdirSync(folder, { recursive: true, mode: 0o700 });
+    if (!lstatSync(dir).isDirectory() || !lstatSync(folder).isDirectory())
+        throw new Error('Invalid credential lock directory.');
+    chmodSync(dir, 0o700);
+    chmodSync(folder, 0o700);
+    const id = `${process.pid}-${randomUUID()}`;
+    const own = join(folder, id);
+    mkdirSync(own, { mode: 0o700 });
+    const participants = () => {
+        const entries = [];
+        for (const name of readdirSync(folder)) {
+            if (!/^\d+-[0-9a-f-]{36}$/.test(name))
+                throw new Error('Invalid credential lock metadata.');
+            const pid = Number(name.slice(0, name.indexOf('-')));
+            if (!Number.isSafeInteger(pid) || pid <= 0)
+                throw new Error('Invalid credential lock metadata.');
+            let alive = true;
+            try {
+                process.kill(pid, 0);
+            }
+            catch (error) {
+                if (error.code === 'ESRCH')
+                    alive = false;
+            }
+            const participant = join(folder, name);
+            if (!alive) {
+                rmSync(participant, { recursive: true, force: true });
+                continue;
+            }
+            try {
+                // The absent ticket is the bakery algorithm's choosing flag.
+                const text = readFileSync(join(participant, 'ticket'), 'utf8');
+                const ticket = Number(text);
+                if (!Number.isSafeInteger(ticket) || ticket <= 0)
+                    throw new Error('Invalid credential lock metadata.');
+                entries.push({ id: name, ticket });
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+                if (lstatExists(participant))
+                    entries.push({ id: name, ticket: null });
+            }
+        }
+        return entries;
+    };
+    try {
+        const ticket = Math.max(0, ...participants().map(entry => entry.ticket ?? 0)) + 1;
+        privateWrite(join(own, 'ticket'), String(ticket));
+        for (;;) {
+            const blocked = participants().some(entry => entry.id !== id && (entry.ticket === null || entry.ticket < ticket || (entry.ticket === ticket && entry.id < id)));
+            if (!blocked)
+                return await work();
+            if (performance.now() - started >= timeout)
+                throw new Error('Timed out waiting for credential modification; no credentials were changed.');
+            await new Promise(resolve => setTimeout(resolve, Math.min(poll, Math.max(1, timeout - (performance.now() - started)))));
+        }
+    }
+    finally {
+        rmSync(own, { recursive: true, force: true });
+    }
+}
+function lstatExists(path) {
+    try {
+        lstatSync(path);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
 /** `<account id>/<secret name>`: the key an account's secret is stored under. */
 export const secretKey = (accountId, name) => `${accountId}/${name}`;
 /** Secrets held only for the life of the process. For tests and throwaway runs. */
@@ -23,18 +130,18 @@ export function fileSecretStore(path) {
     const read = () => readJsonOr(path, {});
     const write = (values) => {
         mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-        atomicWrite(path, `${JSON.stringify(values, null, 2)}\n`);
+        privateWrite(path, `${JSON.stringify(values, null, 2)}\n`);
         chmodSync(path, 0o600);
     };
     return {
         get: async (key) => read()[key] ?? null,
-        set: async (key, value) => write({ ...read(), [key]: value }),
-        delete: async (key) => {
+        set: (key, value) => withCredentialLock(`${path}.locks`, 'file', async () => write({ ...read(), [key]: value })),
+        delete: (key) => withCredentialLock(`${path}.locks`, 'file', async () => {
             const values = read();
             if (key in values) {
                 delete values[key];
                 write(values);
             }
-        }
+        })
     };
 }

package/dist/sdk/accounts/store.d.ts

@@ -25,10 +25,33 @@ export interface Limit {
     id: string;
     label: string;
     usedPercent?: number | null;
+    /** The same window from the other side: quota left. Additive for surfaces that read limits as remaining. */
+    remainingPercent?: number | null;
     resetsAt?: string | null;
     windowMinutes?: number | null;
-    /** `allowed`, `warning`, or `rejected` when the provider reports it. */
+    /** `allowed`, `warning`, `rejected`, or `configured` when the provider reports it. */
     status?: string | null;
+    /** Which provider the reading belongs to. Older records may omit it. */
+    provider?: string | null;
+    /** What kind of ceiling this is. */
+    kind?: 'window' | 'rate' | 'credit' | 'configured' | 'error';
+    /** The unit of `used`, `limit` and `remaining`. */
+    unit?: 'percent' | 'requests' | 'tokens' | 'usd' | 'currency' | 'count';
+    used?: number | null;
+    limit?: number | null;
+    remaining?: number | null;
+    /** How the reading was obtained. */
+    source?: 'headers' | 'provider' | 'estimate' | 'error';
+    observedAt?: string | null;
+    /** A short provider note, such as a balance currency. */
+    detail?: string | null;
+}
+/** The last readout for one provider of one account, including when nothing could be read. */
+export interface ProviderLimitState {
+    provider: string;
+    source: 'headers' | 'provider' | 'estimate' | 'unavailable';
+    reason: string | null;
+    observedAt: string;
 }
 export interface Issue {
     /** `auth_expired`, `rate_limited`, `quota`, `network`, or `unknown`. */
@@ -45,6 +68,8 @@ export interface AccountState {
     plan: string | null;
     identity: string | null;
     limits: Limit[];
+    /** What the last limit readout found for each provider, including an unavailable one. */
+    providerLimits: ProviderLimitState[];
     lastError: Issue | null;
     lastCheckedAt: string | null;
     cliVersion: string | null;

package/dist/sdk/accounts/store.js

@@ -18,7 +18,7 @@ import { appendLine, newId, now, readJsonOr, safeId, writeJson } from "../core/f
 import { charCount, compareText, lines, takeChars } from "../core/text.js";
 /** The only provider the harness runs. Records of other providers are kept in the file and ignored. */
 export const PROVIDER = 'pi';
-export const emptyState = () => ({ health: 'unknown', signedIn: null, authMethod: null, plan: null, identity: null, limits: [], lastError: null, lastCheckedAt: null, cliVersion: null, capabilities: [], piProviders: [] });
+export const emptyState = () => ({ health: 'unknown', signedIn: null, authMethod: null, plan: null, identity: null, limits: [], providerLimits: [], lastError: null, lastCheckedAt: null, cliVersion: null, capabilities: [], piProviders: [] });
 // ---- Files ------------------------------------------------------------------------------
 const registryPath = (dir) => join(dir, 'accounts.json');
 const statePath = (dir, accountId) => join(dir, safeId(accountId), 'state.json');

package/dist/sdk/agents/builtin.js

@@ -1,3 +1,4 @@
+import { PLAN_RESEARCH_PLUGINS } from "./planResearch.js";
 const RECALL = ['history_search', 'history_read', 'trajectory_search', 'trajectory_read', 'wiki_search', 'wiki_read', 'wiki_list', 'skill_load'];
 const PROGRESS = ['checklist_write', 'session_name'];
 const WEB = ['web_search', 'web_fetch'];
@@ -29,6 +30,19 @@ export const BUILTIN_PROFILES = [
             '- Return conclusions, not file dumps: what you found, where, and how sure you are.'
         ].join('\n'),
         tools: ['read', 'grep', 'find', 'ls', ...PROGRESS, ...RECALL, ...WEB],
-        plugins: null, variant: null, model: null, effort: null
+        plugins: [...PLAN_RESEARCH_PLUGINS], variant: null, model: null, effort: null
+    },
+    {
+        name: 'researcher',
+        description: 'Researches code, history and public sources without changing anything.',
+        color: 'purple',
+        instructions: [
+            'You investigate the bounded research question in your brief and return concise, evidence-backed findings to the parent.',
+            '- Use read-only repository and public-web sources. Never modify files, run commands, call connected apps, or ask the user.',
+            '- Prefer primary sources. Cite repository claims as path:line and external claims with source URLs.',
+            '- Separate observed facts from inference, state uncertainty, and return only findings relevant to the brief; do not implement.'
+        ].join('\n'),
+        tools: ['read', 'grep', 'find', 'ls', ...PROGRESS, ...RECALL, ...WEB],
+        plugins: [...PLAN_RESEARCH_PLUGINS], variant: null, model: null, effort: null
     }
 ];

package/dist/sdk/agents/planResearch.d.ts

@@ -0,0 +1,5 @@
+import type { AgentProfile } from "./profiles.js";
+export declare const PLAN_RESEARCH_TOOLS: ReadonlySet<string>;
+export declare const PLAN_RESEARCH_PLUGINS: readonly string[];
+export declare const PLAN_RESEARCH_EVIDENCE_TOOLS: ReadonlySet<string>;
+export declare function planResearchProfile(profile: Pick<AgentProfile, 'tools' | 'plugins'> | null | undefined): boolean;

package/dist/sdk/agents/planResearch.js

@@ -0,0 +1,19 @@
+export const PLAN_RESEARCH_TOOLS = new Set([
+    'read', 'grep', 'find', 'ls', 'checklist_write', 'session_name',
+    'history_search', 'history_read', 'trajectory_search', 'trajectory_read',
+    'wiki_entrypoint', 'wiki_search', 'wiki_read', 'wiki_list', 'memory_facts', 'skill_load',
+    'web_search', 'web_fetch'
+]);
+export const PLAN_RESEARCH_PLUGINS = ['history', 'variant', 'web', 'wiki'];
+export const PLAN_RESEARCH_EVIDENCE_TOOLS = new Set([
+    'read', 'grep', 'find', 'ls', 'history_search', 'trajectory_search', 'wiki_search', 'web_search', 'web_fetch'
+]);
+export function planResearchProfile(profile) {
+    return Boolean(profile
+        && Array.isArray(profile.tools)
+        && profile.tools.length > 0
+        && profile.tools.some(name => PLAN_RESEARCH_EVIDENCE_TOOLS.has(name))
+        && profile.tools.every(name => PLAN_RESEARCH_TOOLS.has(name))
+        && Array.isArray(profile.plugins)
+        && profile.plugins.every(name => PLAN_RESEARCH_PLUGINS.includes(name)));
+}

package/dist/sdk/agents/profiles.d.ts

@@ -71,10 +71,11 @@ export declare function removeProfile(root: string, cwd: string | null | undefin
 /** Where the profile list sits among the prompt sections: the slot a variant's subagents used. */
 export declare const PROFILE_SECTION_ORDER = 64;
 /** The prompt section that lists the profiles a run can start subagents from. */
-export declare function profileSection(root: string, cwd: string | null | undefined, variantDir?: string | null): {
+export declare function profileSection(root: string, cwd: string | null | undefined, variantDir?: string | null, planResearchOnly?: boolean): {
     id: string;
     title: string;
     body: string;
     budget: number;
     order: number;
+    dynamic: true;
 };

package/dist/sdk/agents/profiles.js

@@ -10,6 +10,7 @@ import { parse, serialize } from "../core/frontmatter.js";
 import { atomicWrite } from "../core/fs.js";
 import { subagentOf } from "../variant/materialise.js";
 import { BUILTIN_PROFILES } from "./builtin.js";
+import { planResearchProfile } from "./planResearch.js";
 export const PROFILE_NAME = /^[a-z0-9][a-z0-9_-]*$/;
 export const PROFILE_COLORS = ['blue', 'green', 'yellow', 'red', 'magenta', 'cyan', 'orange', 'purple'];
 /** Nearest folder above `cwd` that holds `.git`, or `cwd` itself. */
@@ -206,16 +207,20 @@ export function removeProfile(root, cwd, input) {
 /** Where the profile list sits among the prompt sections: the slot a variant's subagents used. */
 export const PROFILE_SECTION_ORDER = 64;
 /** The prompt section that lists the profiles a run can start subagents from. */
-export function profileSection(root, cwd, variantDir) {
+export function profileSection(root, cwd, variantDir, planResearchOnly = false) {
     const { profiles } = listProfiles(root, cwd, variantDir);
+    const listed = planResearchOnly ? profiles.filter(planResearchProfile) : profiles;
     return {
         id: 'subagents',
         title: 'Subagents',
         body: [
-            'Start one with spawn_subagent and agent set to a profile name, or omit agent for a copy of yourself. Each works in its own context with a complete brief from you, keeps its own checklist the user can follow, and returns text. A profile can only narrow your tools.',
-            ...profiles.map((profile) => `- ${profile.name} — ${profile.description}`)
+            planResearchOnly
+                ? 'Plan mode may start only a named profile listed here, for read-only research. Do not omit agent or use a profile not listed.'
+                : 'Delegate when it meaningfully reduces work: choose a substantial, bounded task that can proceed independently, such as unfamiliar cross-file research likely to take several searches or a self-contained implementation. Do a known-file lookup, one or two simple tool calls, a tiny edit or tightly coupled work yourself. Prefer a named profile: explorer for repository research, researcher for public-source research, and worker for a defined change it can own end to end; omit agent only when no profile fits. Each child starts without this conversation, so give it the goal, relevant context or paths, non-goals, expected result and acceptance or verification; use its own checklist for multi-step work. Prefer context-heavy research with concise evidence-backed findings. Parallelize only independent tasks and never assign overlapping edits. Return without waiting only when useful independent work remains; otherwise wait. You own integration, verification and the user-facing report. A profile can only narrow your tools.',
+            ...(listed.length ? listed.map((profile) => `- ${profile.name} — ${profile.description}`) : ['- No eligible read-only research profiles are configured.'])
         ].join('\n'),
         budget: 6_000,
-        order: PROFILE_SECTION_ORDER
+        order: PROFILE_SECTION_ORDER,
+        dynamic: true
     };
 }