mixdog 0.9.2 → 0.9.4

package/src/runtime/agent/orchestrator/session/loop/compact-debug.mjs

@@ -0,0 +1,28 @@
+// Compaction debug/diagnostic helpers extracted from loop.mjs.
+import { estimateMessagesTokens } from '../context-utils.mjs';
+
+export function estimateMessagesTokensSafe(messages) {
+    try { return estimateMessagesTokens(messages); }
+    catch { return null; }
+}
+
+export function compactDebugEnabled() {
+    return String(process.env.MIXDOG_COMPACT_DEBUG || '').trim() === '1';
+}
+
+export function compactDiagnosticError(err) {
+    if (!err) return null;
+    const text = String(err?.message || err);
+    return text.length > 500 ? `${text.slice(0, 499)}…` : text;
+}
+
+export function compactByteLength(text) {
+    try { return Buffer.byteLength(String(text || ''), 'utf8'); }
+    catch { return String(text || '').length; }
+}
+
+export function compactDebugLog(scope, details = {}) {
+    if (!compactDebugEnabled()) return;
+    try { process.stderr.write(`[compact] ${scope} ${JSON.stringify(details)}\n`); }
+    catch { /* best-effort diagnostics only */ }
+}

package/src/runtime/agent/orchestrator/session/loop/compact-policy.mjs

@@ -0,0 +1,274 @@
+// Compaction policy resolution, pressure/target budgeting, telemetry
+// persistence, and event emission — extracted from loop.mjs.
+// runRecallFastTrackCompact stays in the loop (it drives the recall pipeline
+// against live session state).
+import {
+    estimateRequestReserveTokens,
+    resolveCompactBufferRatio,
+    resolveCompactBufferTokens,
+} from '../context-utils.mjs';
+import {
+    compactTypeIsRecallFastTrack,
+    compactTypeIsSemantic,
+    normalizeCompactType,
+    DEFAULT_COMPACT_TYPE,
+    DEFAULT_COMPACTION_KEEP_TOKENS,
+    CONTEXT_SHARE_RATIO,
+} from '../compact.mjs';
+import { positiveTokenInt, envFlag, envTokenInt } from './env.mjs';
+import { isAgentOwner } from '../../agent-owner.mjs';
+
+const COMPACT_SAFETY_PERCENT = 1.00;
+// Unified context-share rule (compact/constants.mjs CONTEXT_SHARE_RATIO): the
+// post-compaction target is 5% of the boundary/context window — the same 5%
+// the recall-fasttrack injection cap uses (loop.mjs recallTokenCap). One
+// number governs every "share of model context" budget.
+const COMPACT_TARGET_RATIO = CONTEXT_SHARE_RATIO;
+const COMPACT_TARGET_MIN_TOKENS = 4_000;
+const COMPACT_TARGET_MAX_TOKENS = 16_000;
+
+function resolveSemanticCompactSetting(sessionRef, cfg = {}) {
+    if (process.env.MIXDOG_AGENT_COMPACT_SEMANTIC !== undefined) return envFlag('MIXDOG_AGENT_COMPACT_SEMANTIC', true);
+    if (cfg.semantic === false || cfg.semantic === 'false' || cfg.semantic === 'off') return false;
+    if (cfg.semantic === true || cfg.semantic === 'true' || cfg.semantic === 'on') return true;
+    // The compact type is already explicit (`semantic` by default). Honor it
+    // directly instead of substituting another compaction path.
+    return true;
+}
+
+function resolveCompactTypeSetting(sessionRef, cfg = {}) {
+    // Agent-owned sessions are ALWAYS semantic. recall-fasttrack rebuilds
+    // context from Memory recall, which is scoped to the user's main-session
+    // history — an agent's tool-loop history is not in the recall pool, so a
+    // fasttrack compact would inject unrelated main-session memories and drop
+    // the agent's own working context. Env/config overrides do not apply.
+    if (isAgentOwner(sessionRef)) return DEFAULT_COMPACT_TYPE;
+    const configured = process.env.MIXDOG_AGENT_COMPACT_TYPE
+        ?? process.env.MIXDOG_COMPACT_TYPE
+        ?? cfg.type
+        ?? cfg.compactType
+        ?? cfg.compact_type;
+    return normalizeCompactType(configured, DEFAULT_COMPACT_TYPE);
+}
+
+function resolveCompactTargetRatio(cfg = {}) {
+    const raw = cfg.targetPercent
+        ?? cfg.targetPct
+        ?? cfg.targetRatio
+        ?? cfg.targetFraction
+        ?? process.env.MIXDOG_AGENT_COMPACT_TARGET_PERCENT
+        ?? process.env.MIXDOG_COMPACT_TARGET_PERCENT
+        ?? COMPACT_TARGET_RATIO;
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0) return COMPACT_TARGET_RATIO;
+    return n > 1 ? n / 100 : n;
+}
+function resolveCompactTargetTokens(boundaryTokens, cfg = {}) {
+    const boundary = positiveTokenInt(boundaryTokens);
+    if (!boundary) return null;
+    const explicit = positiveTokenInt(cfg.targetTokens ?? cfg.target)
+        || envTokenInt('MIXDOG_AGENT_COMPACT_TARGET_TOKENS')
+        || envTokenInt('MIXDOG_COMPACT_TARGET_TOKENS');
+    if (explicit) return Math.max(1, Math.min(boundary, explicit));
+    const minTarget = Math.min(boundary, positiveTokenInt(cfg.targetMinTokens ?? cfg.minTargetTokens)
+        || envTokenInt('MIXDOG_AGENT_COMPACT_TARGET_MIN_TOKENS')
+        || envTokenInt('MIXDOG_COMPACT_TARGET_MIN_TOKENS')
+        || COMPACT_TARGET_MIN_TOKENS);
+    const maxTarget = Math.min(boundary, positiveTokenInt(cfg.targetMaxTokens ?? cfg.maxTargetTokens)
+        || envTokenInt('MIXDOG_AGENT_COMPACT_TARGET_MAX_TOKENS')
+        || envTokenInt('MIXDOG_COMPACT_TARGET_MAX_TOKENS')
+        || COMPACT_TARGET_MAX_TOKENS);
+    const byRatio = Math.max(1, Math.floor(boundary * resolveCompactTargetRatio(cfg)));
+    return Math.max(1, Math.min(boundary, maxTarget, Math.max(minTarget, byRatio)));
+}
+function resolveCompactKeepTokens(cfg = {}) {
+    return positiveTokenInt(cfg.keepTokens ?? cfg.keep?.tokens ?? cfg.preserveRecentTokens)
+        || envTokenInt('MIXDOG_AGENT_COMPACT_KEEP_TOKENS')
+        || DEFAULT_COMPACTION_KEEP_TOKENS;
+}
+export function resolveWorkerCompactPolicy(sessionRef, tools) {
+    if (!sessionRef) return null;
+    const cfg = sessionRef.compaction || {};
+    const auto = cfg.auto !== false && envFlag('MIXDOG_AGENT_COMPACT_AUTO', true);
+    if (!auto) return { auto: false };
+    const contextWindow = positiveTokenInt(sessionRef.contextWindow ?? cfg.contextWindow);
+    const explicitBoundary = positiveTokenInt(sessionRef.compactBoundaryTokens ?? cfg.boundaryTokens);
+    const autoLimit = positiveTokenInt(sessionRef.autoCompactTokenLimit ?? cfg.autoCompactTokenLimit);
+    const boundaryTokens = explicitBoundary && contextWindow
+        ? Math.min(explicitBoundary, contextWindow)
+        : (explicitBoundary || contextWindow || autoLimit);
+    if (!boundaryTokens) return null;
+    const compactBoundaryTokens = Math.max(1, Math.floor(boundaryTokens * COMPACT_SAFETY_PERCENT));
+    // Only an explicit auto-compact limit STRICTLY BELOW the boundary acts as
+    // the trigger. A persisted value == boundary (legacy derived full-window
+    // autoCompactTokenLimit) would set autoTriggerTokens == boundary and
+    // collapse/override the default trigger, so it is ignored in favor of the
+    // default boundary trigger.
+    const autoTriggerTokens = autoLimit && autoLimit < compactBoundaryTokens ? Math.max(1, autoLimit) : null;
+    // Sanitized explicit limit: only a sub-boundary value is a real auto-compact
+    // limit. Anything >= boundary is a legacy derived full-window artifact and
+    // is reported as null so rememberCompactTelemetry does not re-persist it
+    // back onto the session and re-collapse the buffer on the next turn.
+    const explicitAutoCompactTokenLimit = autoTriggerTokens;
+    const bufferTokens = autoTriggerTokens
+        ? Math.max(0, compactBoundaryTokens - autoTriggerTokens)
+        : resolveCompactBufferTokens(compactBoundaryTokens, cfg);
+    const bufferRatio = compactBoundaryTokens ? (bufferTokens / compactBoundaryTokens) : resolveCompactBufferRatio(cfg);
+    const triggerTokens = autoTriggerTokens || Math.max(1, compactBoundaryTokens - bufferTokens);
+    const configuredReserve = positiveTokenInt(cfg.reservedTokens)
+        || envTokenInt('MIXDOG_AGENT_COMPACT_RESERVED_TOKENS')
+        || 0;
+    const requestReserve = estimateRequestReserveTokens(tools);
+    const keepTokens = resolveCompactKeepTokens(cfg);
+    const compactType = resolveCompactTypeSetting(sessionRef, cfg);
+    return {
+        auto: true,
+        type: compactType,
+        compactType,
+        prune: cfg.prune === true || envFlag('MIXDOG_AGENT_COMPACT_PRUNE', false),
+        boundaryTokens: compactBoundaryTokens,
+        triggerTokens,
+        bufferTokens,
+        bufferRatio,
+        contextWindow,
+        rawContextWindow: positiveTokenInt(sessionRef.rawContextWindow ?? cfg.rawContextWindow) || contextWindow,
+        effectiveContextWindowPercent: Number.isFinite(Number(sessionRef.effectiveContextWindowPercent ?? cfg.effectiveContextWindowPercent))
+            ? Number(sessionRef.effectiveContextWindowPercent ?? cfg.effectiveContextWindowPercent)
+            : null,
+        autoCompactTokenLimit: explicitAutoCompactTokenLimit,
+        semantic: compactTypeIsSemantic(compactType) && resolveSemanticCompactSetting(sessionRef, cfg),
+        recallFastTrack: compactTypeIsRecallFastTrack(compactType),
+        semanticTimeoutMs: positiveTokenInt(cfg.timeoutMs) || envTokenInt('MIXDOG_AGENT_COMPACT_TIMEOUT_MS') || 30_000,
+        tailTurns: positiveTokenInt(cfg.tailTurns) || envTokenInt('MIXDOG_AGENT_COMPACT_TAIL_TURNS') || 2,
+        keepTokens,
+        preserveRecentTokens: positiveTokenInt(cfg.preserveRecentTokens) || envTokenInt('MIXDOG_AGENT_COMPACT_PRESERVE_RECENT_TOKENS') || keepTokens,
+        reserveTokens: requestReserve + configuredReserve,
+        requestReserveTokens: requestReserve,
+        configuredReserveTokens: configuredReserve,
+    };
+}
+/** Transcript + request reserve only (never provider lastContextTokens). */
+function compactPressureTokens(messageTokensEst, policy) {
+    if (messageTokensEst === null) return 0;
+    return Math.max(0, messageTokensEst + (policy?.reserveTokens || 0));
+}
+
+/** Telemetry pressure when a reactive overflow retry forces the next compact. */
+export function compactionTelemetryPressureTokens(messageTokensEst, policy, { reactivePending = false } = {}) {
+    const base = compactPressureTokens(messageTokensEst, policy);
+    if (!reactivePending) return base;
+    const floor = positiveTokenInt(policy?.triggerTokens) || positiveTokenInt(policy?.boundaryTokens) || 0;
+    return floor ? Math.max(base, floor) : base;
+}
+export function compactTargetBudget(policy) {
+    const boundary = positiveTokenInt(policy?.boundaryTokens);
+    if (!boundary) return null;
+    const reserve = Math.max(0, Number(policy?.reserveTokens) || 0);
+    const targetEffective = resolveCompactTargetTokens(boundary, policy) || boundary;
+    return Math.max(1, Math.min(boundary, targetEffective + reserve));
+}
+export function shouldCompactForSession(messageTokensEst, policy, { forceReactive = false } = {}) {
+    if (!policy?.auto || !policy.boundaryTokens) return false;
+    if (forceReactive) return true;
+    if (messageTokensEst === null) return true;
+    return compactPressureTokens(messageTokensEst, policy) >= (policy.triggerTokens || policy.boundaryTokens);
+}
+export function countPrunedToolOutputs(before, after) {
+    if (!Array.isArray(before) || !Array.isArray(after)) return 0;
+    let count = 0;
+    const n = Math.min(before.length, after.length);
+    for (let i = 0; i < n; i += 1) {
+        if (before[i]?.role !== 'tool' || after[i]?.role !== 'tool') continue;
+        if (before[i]?.content !== after[i]?.content && after[i]?.compactedKind === 'tool_output_prune') count += 1;
+    }
+    return count;
+}
+export function rememberCompactTelemetry(sessionRef, policy, meta = {}) {
+    if (!sessionRef || !policy) return;
+    const prev = sessionRef.compaction && typeof sessionRef.compaction === 'object'
+        ? sessionRef.compaction
+        : {};
+    const changed = meta.compactChanged === true || meta.pruneCount > 0;
+    sessionRef.compaction = {
+        ...prev,
+        auto: policy.auto !== false,
+        prune: policy.prune === true,
+        reservedTokens: policy.configuredReserveTokens || prev.reservedTokens || null,
+        requestReserveTokens: policy.requestReserveTokens || 0,
+        reserveTokens: policy.reserveTokens || 0,
+        boundaryTokens: policy.boundaryTokens || null,
+        triggerTokens: policy.triggerTokens || null,
+        bufferTokens: policy.bufferTokens || 0,
+        bufferRatio: policy.bufferRatio ?? prev.bufferRatio ?? null,
+        contextWindow: policy.contextWindow || null,
+        rawContextWindow: policy.rawContextWindow || null,
+        effectiveContextWindowPercent: policy.effectiveContextWindowPercent ?? null,
+        autoCompactTokenLimit: policy.autoCompactTokenLimit || null,
+        type: policy.compactType || policy.type || DEFAULT_COMPACT_TYPE,
+        compactType: policy.compactType || policy.type || DEFAULT_COMPACT_TYPE,
+        semantic: policy.semantic === true ? 'auto' : false,
+        recallFastTrack: policy.recallFastTrack === true,
+        semanticModel: policy.semanticModel || null,
+        semanticTimeoutMs: policy.semanticTimeoutMs || null,
+        tailTurns: policy.tailTurns || null,
+        keepTokens: policy.keepTokens || null,
+        preserveRecentTokens: policy.preserveRecentTokens || null,
+        lastCheckedAt: Date.now(),
+        lastBeforeTokens: meta.beforeTokens ?? null,
+        lastAfterTokens: meta.afterTokens ?? null,
+        lastPressureTokens: meta.pressureTokens ?? null,
+        currentEstimatedTokens: meta.pressureTokens ?? prev.currentEstimatedTokens ?? null,
+        lastApiRequestTokens: positiveTokenInt(sessionRef?.lastContextTokens) || prev.lastApiRequestTokens || null,
+        lastStage: meta.stage || prev.lastStage || null,
+        lastChanged: changed,
+        lastTrigger: meta.trigger || prev.lastTrigger || null,
+        lastSemantic: meta.semanticCompact === true,
+        lastSemanticError: Object.hasOwn(meta, 'semanticError')
+            ? (meta.semanticError ?? null)
+            : (prev.lastSemanticError ?? null),
+        lastRecallFastTrack: meta.recallFastTrack === true,
+        lastRecallFastTrackError: Object.hasOwn(meta, 'recallFastTrackError')
+            ? (meta.recallFastTrackError ?? null)
+            : (prev.lastRecallFastTrackError ?? null),
+        lastError: Object.hasOwn(meta, 'compactError') || Object.hasOwn(meta, 'lastError')
+            ? (meta.compactError ?? meta.lastError ?? null)
+            : (prev.lastError ?? null),
+        lastPruneCount: meta.pruneCount || 0,
+        lastDurationMs: meta.durationMs != null && Number.isFinite(Number(meta.durationMs))
+            ? Math.max(0, Math.round(Number(meta.durationMs)))
+            : null,
+        compactCount: (prev.compactCount || 0) + (changed ? 1 : 0),
+    };
+    if (changed) {
+        const changedAt = Date.now();
+        sessionRef.compaction.lastChangedAt = changedAt;
+        sessionRef.compaction.lastCompactAt = changedAt;
+        sessionRef.lastContextTokensStaleAfterCompact = true;
+    }
+    sessionRef.contextWindow = policy.contextWindow || sessionRef.contextWindow;
+    sessionRef.rawContextWindow = policy.rawContextWindow || sessionRef.rawContextWindow;
+    sessionRef.compactBoundaryTokens = policy.boundaryTokens || sessionRef.compactBoundaryTokens || null;
+    // Persist only the sanitized (sub-boundary) explicit limit. policy.autoCompactTokenLimit
+    // is already null for legacy derived full-window values, so a stale
+    // boundary-sized autoCompactTokenLimit on the session is cleared here rather
+    // than carried forward to re-collapse the buffer next turn.
+    {
+        const _boundary = positiveTokenInt(sessionRef.compactBoundaryTokens);
+        const _prevLimit = positiveTokenInt(sessionRef.autoCompactTokenLimit);
+        const _keepPrev = _prevLimit && (!_boundary || _prevLimit < _boundary) ? _prevLimit : null;
+        sessionRef.autoCompactTokenLimit = policy.autoCompactTokenLimit || _keepPrev || null;
+    }
+    if (policy.effectiveContextWindowPercent !== null) {
+        sessionRef.effectiveContextWindowPercent = policy.effectiveContextWindowPercent;
+    }
+}
+
+export function emitCompactEvent(opts, event = {}) {
+    if (!opts || typeof opts.onCompactEvent !== 'function') return;
+    try { opts.onCompactEvent({ ts: Date.now(), ...event }); }
+    catch { /* best-effort UI/log hook */ }
+}
+
+export function compactEventType(policy, fallback = DEFAULT_COMPACT_TYPE) {
+    return policy?.compactType || policy?.type || fallback;
+}

package/src/runtime/agent/orchestrator/session/loop/completion-guards.mjs

@@ -0,0 +1,61 @@
+// Completion-first loop guards: escalation ladder (level-2 steering),
+// cross-turn identical read-only call dedup, and worker soft-cap wrap-up.
+// Pure string/signature helpers extracted from loop.mjs so the loop body only
+// wires state + messages. No provider/manager coupling.
+
+// Deterministic, key-sorted stringify for cross-turn call signatures. Mirrors
+// _canonicalArgs but exposed by name for the dedup signature contract.
+export function stableStringify(value) {
+    if (value == null || typeof value !== 'object') {
+        try { return JSON.stringify(value); } catch { return String(value); }
+    }
+    if (Array.isArray(value)) {
+        try { return `[${value.map(stableStringify).join(',')}]`; } catch { return String(value); }
+    }
+    try {
+        const keys = Object.keys(value).sort();
+        return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(',')}}`;
+    } catch { return String(value); }
+}
+
+export function crossTurnSignature(name, args) {
+    return `${name}:${stableStringify(args)}`;
+}
+
+// Tool names that are non-eager (no readOnlyHint) but are NOT edits/progress —
+// they must not reset the escalation ladder's "zero edit" condition. Skill /
+// recall / agent / task / cwd / tool_search are exploration/meta plumbing.
+const NON_PROGRESS_TOOLS = new Set(['Skill', 'recall', 'agent', 'task', 'cwd', 'tool_search']);
+
+// True when a successfully-executed tool represents real edit/progress. A tool
+// counts as progress only if its def lacks readOnlyHint (not eager) AND it is
+// not in the meta/non-progress set. apply_patch and shell/bash always count.
+export function isEditProgressTool(name, isEager) {
+    if (isEager) return false;
+    const bare = name && name.startsWith('mcp__') ? name.split('__').pop() : name;
+    if (bare === 'apply_patch' || bare === 'shell' || bare === 'bash' || bare === 'bash_session') return true;
+    return !NON_PROGRESS_TOOLS.has(bare);
+}
+
+// Step 1 — level-2 escalation steering. N = cumulative level-1 fires.
+// `readOnlyRole` swaps the edit-oriented directive for a report-oriented one:
+// read-permission sessions (reviewer-style) cannot apply_patch, so telling
+// them to edit is self-contradictory and pushes premature termination.
+export function level2SteerMessage(n, readOnlyRole = false) {
+    if (readOnlyRole) {
+        return `<system-reminder>\nYou have received this batching reminder ${n} times. Converge now: report your findings from what you have already read, or state exactly what information is missing for a verdict. A partial report with named gaps is a valid, successful completion — continued exploration is not.\n</system-reminder>`;
+    }
+    return `<system-reminder>\nYou have received this batching reminder ${n} times without making any edit. Stop exploring now: either apply_patch with what you already know, or return a blocked report stating exactly what is missing. A blocked report is a valid, successful completion — continued exploration is not.\n</system-reminder>`;
+}
+
+// Step 2 — cross-turn dedup stub. `stuck` appends the escalation tail at the
+// 5th+ dedup stub in the session.
+export function crossTurnDedupStub(name, firstIteration, stuck) {
+    let s = `[cross-turn-dedup] identical read-only \`${name}\` call already executed in iteration ${firstIteration}; its result is unchanged and already in context. Use it, or change path/offset/pattern for new information.`;
+    if (stuck) s += ` Repeated identical calls indicate you are stuck — apply what you know or return blocked.`;
+    return s;
+}
+
+// Step 3 — worker soft-cap wrap-up assistant-visible directive + refusal stub.
+export const SOFT_CAP_WRAPUP_MESSAGE = `MAXIMUM EXPLORATION BUDGET REACHED. Tools are now disabled. Respond with text only: summarize work completed so far, list remaining/incomplete items, and state what is blocking or what should be done next. This overrides all other instructions.`;
+export const SOFT_CAP_REFUSAL_STUB = `Tools are disabled: exploration budget reached. Provide your final text summary.`;

package/src/runtime/agent/orchestrator/session/loop/context-overflow.mjs

@@ -0,0 +1,38 @@
+// Agent context-overflow error, extracted from loop.mjs. Raised when the latest
+// turn cannot fit the target context budget even after compaction.
+
+export class AgentContextOverflowError extends Error {
+    constructor({ stage, sessionId, provider, model, contextWindow, budgetTokens, reserveTokens, messageTokensEst }, cause) {
+        const target = [provider, model].filter(Boolean).join('/') || 'target model';
+        const causeMsg = cause && cause.message ? `: ${cause.message}` : '';
+        super(
+            `agent context overflow (${target}, stage=${stage || 'compact'}): ` +
+            `latest turn cannot fit target context budget=${budgetTokens ?? 'unknown'} ` +
+            `reserve=${reserveTokens ?? 'unknown'} contextWindow=${contextWindow ?? 'unknown'} ` +
+            `messageTokensEst=${messageTokensEst ?? 'unknown'}${causeMsg}`,
+        );
+        this.name = 'AgentContextOverflowError';
+        this.code = 'AGENT_CONTEXT_OVERFLOW';
+        this.sessionId = sessionId || null;
+        this.provider = provider || null;
+        this.model = model || null;
+        this.contextWindow = contextWindow ?? null;
+        this.budgetTokens = budgetTokens ?? null;
+        this.reserveTokens = reserveTokens ?? null;
+        this.messageTokensEst = messageTokensEst ?? null;
+        if (cause) this.cause = cause;
+    }
+}
+
+export function agentContextOverflowError({ stage, sessionId, sessionRef, model, budgetTokens, reserveTokens, messageTokensEst }, cause) {
+    return new AgentContextOverflowError({
+        stage,
+        sessionId,
+        provider: sessionRef?.provider || null,
+        model: sessionRef?.model || model || null,
+        contextWindow: sessionRef?.contextWindow ?? null,
+        budgetTokens,
+        reserveTokens,
+        messageTokensEst,
+    }, cause);
+}

package/src/runtime/agent/orchestrator/session/loop/env.mjs

@@ -0,0 +1,14 @@
+// Env-var / token parsing helpers extracted from loop.mjs.
+
+export function positiveTokenInt(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : null;
+}
+export function envFlag(name, fallback = false) {
+    const v = process.env[name];
+    if (v === undefined) return fallback;
+    return !['0', 'false', 'off', 'no'].includes(String(v).trim().toLowerCase());
+}
+export function envTokenInt(name) {
+    return positiveTokenInt(process.env[name]);
+}

package/src/runtime/agent/orchestrator/session/loop/hidden-agents.mjs

@@ -0,0 +1,21 @@
+// Hidden (sub-agent) role registry, extracted from loop.mjs.
+// Source of truth: defaults/agents.json — read once and cached. HIDDEN_AGENT_NAMES
+// is built eagerly so it stays in sync with the declarative registry (no
+// hardcoded duplicate).
+import { readFileSync as _readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { dirname, resolve as resolvePath } from 'path';
+
+const _AGENTS_JSON = resolvePath(dirname(fileURLToPath(import.meta.url)), '../../../../../defaults/agents.json');
+let _hiddenAgentsCache = null;
+function _getHiddenAgents() {
+    if (_hiddenAgentsCache) return _hiddenAgentsCache;
+    try {
+        _hiddenAgentsCache = JSON.parse(_readFileSync(_AGENTS_JSON, 'utf8'));
+    } catch { _hiddenAgentsCache = { agents: [] }; }
+    return _hiddenAgentsCache;
+}
+
+export const HIDDEN_AGENT_NAMES = new Set(
+    (_getHiddenAgents().agents || []).map((r) => r && r.agent).filter((n) => typeof n === 'string' && n.length > 0)
+);

package/src/runtime/agent/orchestrator/session/loop/pre-dispatch-deny.mjs

@@ -0,0 +1,47 @@
+// Shared pre-dispatch deny — single source of truth for the remaining
+// control-plane / role scoping rejects. Called by BOTH the eager dispatch
+// path (startEagerTool) and the serial dispatch path (executeTool body).
+// Returns null when the call is allowed to proceed; otherwise returns the
+// Error string the serial path would emit. The eager caller ignores the
+// message body and just treats non-null as "do not start eager".
+//
+// This is NOT a permission gate — runtime permission enforcement was removed
+// (every tool call is trusted). What remains is architectural scoping:
+// agent workers are sandboxed to code/research tools. They must never reach
+// owner/host control surfaces: session management, the ENTIRE channels module
+// (Discord messaging, schedules, webhook/config, channel-bridge toggle,
+// command injection), or host input injection. Explicit name list (no imports)
+// keeps this hot-path gate dependency-free; add new owner/channel tools here.
+import { isAgentOwner } from '../../agent-owner.mjs';
+
+const WORKER_DENIED_TOOLS = new Set([
+    // session control-plane — unified into the single `agent` tool
+    // (type=spawn|send|close|list). Denying the one name blocks all worker
+    // session control.
+    'agent',
+    // channels module (owner/Discord-facing)
+    'reply', 'fetch',
+    // host input injection
+    'inject_input',
+]);
+
+function _preDispatchDeny(call, toolKind, sessionRef) {
+    const name = call?.name;
+    if (typeof name !== 'string' || !name) return null;
+    const _agentOwned = sessionRef?.scope?.startsWith?.('agent:')
+        || isAgentOwner(sessionRef);
+    const _controlPlaneTool = WORKER_DENIED_TOOLS.has(name);
+    if (_agentOwned && _controlPlaneTool) {
+        return `Error: control-plane tool "${name}" is Lead-only and not available to agent workers.`;
+    }
+    const noToolAgent = sessionRef?.agent === 'cycle1-agent' || sessionRef?.agent === 'cycle2-agent';
+    if (noToolAgent) {
+        return `Error: tool "${name}" is not available in agent "${sessionRef.agent}". Re-emit the answer as pipe-separated text per the agent's output format (first character a digit, NO tool_use blocks, NO JSON, NO prose, NO apology).`;
+    }
+    return null;
+}
+
+/** Exported for smoke tests — same runtime deny as the agent loop. */
+export function preDispatchDenyForSession(sessionRef, call, toolKind = 'builtin') {
+    return _preDispatchDeny(call, toolKind, sessionRef);
+}