dsh-ptc-plus 0.5.0 → 0.5.2

package/index.js

@@ -20,12 +20,14 @@ import { createCordisToolsOwner } from './internal/cordis-tools-owner.js'
 import { createEditTransportOwner, EDIT_RUN_CODE } from './internal/edit-transport-owner.js'
 import { createRuntimeBridgeOwner, RUN_CODE } from './internal/runtime-bridge-owner.js'
 import { resolveConfig, watchVolatileConfig } from './internal/runtime-config.js'
+import { configureRetention } from './internal/projection-retention.js'
 import {
   CONFIG_FIELDS,
   SETTINGS_NAMESPACE,
 } from './internal/config-spec.js'
 import { configFieldSchema, installSettingsSectionCompat } from './internal/settings-compat.js'
 import { installExecutionSeam } from './internal/execution-seam-compat.js'
+import { createDeferredRuntime, defersToOfficialRepl } from './internal/official-repl-priority.js'
 import { valueLimitsFromConfig } from './internal/value-wire-schema.js'
 import { createReplMemoryProjection } from './internal/repl-memory-projection.js'
 import { createUserBindingDraftProjection } from './internal/user-binding-draft-projection.js'
@@ -34,6 +36,7 @@ import { createHostRpc } from './internal/host-rpc.js'
 import { RPC_CONTRACTS } from './internal/rpc-contract.js'
 import { createReplObservationInterest } from './internal/repl-observation-interest.js'
 import { guidancePolicies } from './internal/binding-update-policy.js'
+import { PROMPT_SLOT_IDS, resolvePromptTextConfig } from './internal/prompt-text.js'
 import * as dshSettings from '@deepseek-ai/dsh-settings'
 
 const INSTALL_CLEANUP = Symbol('ptc-plus install cleanup')
@@ -58,7 +61,7 @@ export const Config = Schema.object(Object.fromEntries(
  */
 export const inject = ['tools', 'systemPrompt', 'agents']
 
-function replGuidance({ bindingPolicy, rewritesEnabled, languageSemantics, durableReplay, cordisToolsEnabled }) {
+function replGuidance({ bindingPolicy, rewritesEnabled, languageSemantics, durableReplay, cordisToolsEnabled }, promptText) {
   const looseTopLevelRedeclarations = bindingPolicy.variableRedeclarations
   const looseTopLevelFunctionClassRedeclarations = bindingPolicy.functionClassRedeclarations
   const autoRewriteImports = rewritesEnabled.autoRewriteImports
@@ -91,18 +94,22 @@ function replGuidance({ bindingPolicy, rewritesEnabled, languageSemantics, durab
   const cordisRecovery = cordisToolsEnabled
     ? 'Keep large Cordis plugin source in a binding before the tool call so it can be reused after an error. A Cordis parse or validation failure can follow external effects; repeat the call only when its retry rules and current results establish that it is safe.'
     : ''
-  return `\`run_code\` continues one persistent PTC REPL. Use Node.js modules in the cell; use external processes when their environment is needed. Ordinary top-level bindings remain available to later cells, so reuse them instead of resending setup code. Choose the smallest cell that answers the request and return only the value the next step needs.
-
-After an execution error, earlier statements may have taken effect. Inspect relevant values in a short cell, then continue from them; repeat external operations only when their retry rules and current results establish safety. \`edit_run_code\` edits and reruns a complete cell.
-
-## Cell conventions
-Use \`return\` for an explicit result and \`console\` for logs. Return supported values directly, including undefined, NaN, infinities, -0 and BigInt; JSON.stringify loses distinctions or rejects BigInt. Do not mix BigInt with Number arithmetic; use a BigInt literal or convert explicitly. Keep functions, Date, Map and other unsupported values in bindings; return needed data or type observations. Native \`tools.*\` arguments must satisfy their own JSON schemas; PTC value transport does not widen those contracts. Keep large inspection results in bindings or reduce them to targeted excerpts: \`tools.read\` is bounded inspection, not a lossless whole-file reader. Relative filesystem, path and default child-process operations use the current working directory at the time they run; a successful in-cell \`tools.working_directory({ cd })\` applies to the rest of that cell, while cell imports and \`import.meta\` keep the directory the cell started in, and \`process.chdir\` is unavailable. ${cellConventions}
-
-## Available capabilities
-Use \`capabilities.tree()\`, \`capabilities.find()\`, and \`capabilities.inspect()\` for unfamiliar program APIs; Reserve \`code.run\` for isolated execution of source held as data.
-Program API references expire when their cell ends. Reusable helpers must read the current namespace when called, for example \`async function readNow(args) { return tools.read(args) }\`, instead of retaining an earlier \`tools\` object or method. Completed-cell callbacks cannot call program APIs.
-
-Native tool availability depends on the current DSH profile and execution world; inspect executables, shells, and paths instead of assuming Windows, WSL, POSIX, or a particular shell. ${recovery}${cordisToolsEnabled ? ` ${cordisRecovery}` : ''}`
+  // Each paragraph is an editable asset; a derived policy sentence is appended to
+  // the paragraph that owns it, so rewriting prose can never contradict the
+  // configuration that produced it. Omitting a paragraph keeps its derived clause.
+  const prose = id => (promptText.omitted(id) ? '' : promptText.text(id))
+  const withDerived = (id, derived) => {
+    const base = prose(id)
+    return base === '' ? derived : `${base} ${derived}`
+  }
+  const paragraphs = [
+    prose(PROMPT_SLOT_IDS.guidanceOpening),
+    prose(PROMPT_SLOT_IDS.guidanceErrorRecovery),
+    withDerived(PROMPT_SLOT_IDS.guidanceCellConventions, cellConventions),
+    prose(PROMPT_SLOT_IDS.guidanceCapabilities),
+    withDerived(PROMPT_SLOT_IDS.guidanceExecutionWorld, `${recovery}${cordisToolsEnabled ? ` ${cordisRecovery}` : ''}`),
+  ]
+  return paragraphs.filter(paragraph => paragraph.trim().length > 0).join('\n\n')
 }
 
 /** Register the session-bound REPL runtime. */
@@ -344,6 +351,7 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
       maxWallMs: activeConfig.maxWallMs,
       maxOutputBytes: activeConfig.maxOutputBytes,
       maxOldGenerationSizeMb: activeConfig.maxOldGenerationSizeMb,
+      workerReclaimMs: activeConfig.workerReclaimMs,
       valueLimits: valueLimitsFromConfig(activeConfig),
     })
     capabilityEnvironment = createCapabilityEnvironment({ ctx, config: activeConfig,
@@ -374,6 +382,7 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
       presentationGeneration,
       sessionId,
       toolSchemasForAgent,
+      promptText: resolvePromptTextConfig(activeConfig),
     })
     directSurface = createDirectSurfaceOwner({
       sessionLogView: sessionLog.project,
@@ -393,7 +402,7 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
       order: 98,
       text: context => {
         if (ctx.tools.get(RUN_CODE, context?.scope) === undefined) return ''
-        return replGuidance(guidancePolicies(activeConfig))
+        return replGuidance(guidancePolicies(activeConfig), resolvePromptTextConfig(activeConfig))
       },
     }))
     disposers.push(ctx.on('system-prompt/assemble', async (assembly, context, next) => {
@@ -415,8 +424,6 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
         editTransport.ensureInstalled(agent)
       }
     }
-    disposers.push(ctx.on('agent/pre-step', (payload, next) => userBindings.preStep(payload, next)))
-    disposers.push(ctx.on('session/event', (session, event) => userBindings.committedEvent(session, event)))
     disposers.push(ctx.on('tools/post-execute', (exec, result, next) => capabilityEnvironment.postExecute(exec, result, next), { prepend: true }))
     disposers.push(ctx.on('tools/ptc-dispatch-log', (dispatch, next) => capabilityEnvironment.dispatchLog(dispatch, next), { prepend: true }))
     disposers.push(ctx.on('agent/status', payload => { if (payload?.agent) capabilityEnvironment.status(payload.agent, payload.status) }))
@@ -471,7 +478,14 @@ function installPtCRuntime(ctx, resolvedConfig, seam, toolSchemasForAgent, toolS
                 return { kind: 'error', text: receipt('unavailable') }
               }
               await capabilityEnvironment.refresh(agent, undefined, signal, commandId)
-              return { kind: 'success', text: receipt(capabilityEnvironment.describe(agent).publication === 'pending' ? 'pending' : 'recorded') }
+              // A refresh always republishes the saved configuration; when that
+              // configuration has capability management or context off, report
+              // the off state instead of claiming an updated environment.
+              const described = capabilityEnvironment.describe(agent)
+              const state = described.effective?.enabled !== true
+                ? described.sourceSettings?.contextEnabled === false ? 'paused' : 'off'
+                : described.publication === 'pending' ? 'pending' : 'recorded'
+              return { kind: 'success', text: receipt(state) }
             }
             return { kind: 'success', text: JSON.stringify(capabilityEnvironment.describe(agent), null, 2) }
           } }), 'ptc-plus capability command')
@@ -618,8 +632,11 @@ export const apply = (ctx, config = {}) => {
   // Configuration is validated before the plugin waits for the host's seam, so
   // an unusable configuration fails at the load call rather than later.
   const resolvedConfig = resolveConfig(config)
+  // The retention window is user configuration; install it before any fold can run.
+  configureRetention(resolvedConfig)
   return installExecutionSeam(ctx, {
     services: inject,
+    attachmentTimeoutMs: resolvedConfig.executionSeamTimeoutMs,
     attach: (scope, seam) => applyWithExecutionSeam(scope, resolvedConfig, seam, ctx, config),
     reportFailure: (error, seamName) => ctx.logger?.warn?.(
       `ptc-plus: execution seam ${seamName} failed to attach`,
@@ -710,6 +727,11 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
     )
     return cleanup
   }
+  // Execution ownership is a per-attachment property: `owned` installs the
+  // session runtime, `deferred` leaves run_code to the official provider.
+  const executionShape = nextConfig => (
+    defersToOfficialRepl(nextConfig, seam.provider) ? 'deferred' : 'owned'
+  )
   const startActivation = record => {
     if (record.cancelled || disposed || activating !== record) {
       record.completion.resolve({ status: 'superseded' })
@@ -720,7 +742,9 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
     }
     let candidate
     try {
-      candidate = installPtCRuntime(ctx, record.config, seam, toolSchemasForAgent, toolSdkSchemasForAgent, sessionId, sessionLog, () => settingsWriter)
+      candidate = record.shape === 'deferred'
+        ? createDeferredRuntime()
+        : installPtCRuntime(ctx, record.config, seam, toolSchemasForAgent, toolSdkSchemasForAgent, sessionId, sessionLog, () => settingsWriter)
       record.runtime = candidate
     } catch (error) {
       const failedRuntime = error?.[INSTALL_CLEANUP]
@@ -765,6 +789,7 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
     const record = {
       config: nextConfig,
       generation,
+      shape: executionShape(nextConfig),
       runtime: undefined,
       disposal: undefined,
       disposed: false,
@@ -814,6 +839,15 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
         return beginActivation(nextConfig, generation, cleanup)
       }
       const current = committed
+      if (current.shape !== executionShape(nextConfig)) {
+        // Ownership changes are installation changes: dispose the live kernels
+        // and install the other shape, so no committed cell can mix the two
+        // execution contracts or extend state the new owner cannot see.
+        current.retiring = true
+        void disposeRuntime(current)
+        const cleanup = disposeRetainedRuntimes()
+        return beginActivation(nextConfig, generation, cleanup)
+      }
       if (!nextConfig.cordisToolsEnabled) current.runtime.cancelCordisActivation()
       return enqueueTransition(async () => {
         if (disposed || committed !== current) return { status: 'superseded' }
@@ -863,9 +897,15 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
   ctx.effect(() => async () => controller.dispose(), 'ptc-plus runtime lifecycle')
 
   const handbackOwners = Object.fromEntries(['sessions', 'sessionPersistence', 'sessionQuery'].map(name => [name, ctx.get(name)]))
+  // One spelling of "the current document": the same resolved configuration the
+  // reconciliation loop applies, so a delivered message and the assembled prompt can
+  // never read two different prompt-text documents. Read lazily: the settings section
+  // replaces `configSource` after activation.
+  const currentPromptText = () => resolvePromptTextConfig(configSource())
   const messageOwner = createRuntimeMessageOwner(context => (
     committed?.retiring ? [] : committed?.runtime.contextsForRequest(context) ?? []
-  ), sessionLog.project, () => committed !== undefined && committed.retiring !== true, handbackOwners.sessionQuery)
+  ), sessionLog.project, () => committed !== undefined && committed.retiring !== true, handbackOwners.sessionQuery,
+  currentPromptText)
   ctx.effect(() => ctx.systemPrompt.context({
     name: PTC_DELIVERY_CONTEXT, order: 98, text: '',
   }), 'ptc-plus dynamic message delivery witness')
@@ -882,6 +922,8 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
     await handBackRuntimeSessions(ctx, handbackOwners)
   }, 'ptc-plus provider handback')
 
+  // The settings section replaces this source after activation; the prompt-text
+  // accessor above reads it lazily for exactly that reason.
   let configSource = () => resolveConfig(volatileConfig ?? resolvedConfig)
   let configurationGeneration = 0
   let configurationRollback = false
@@ -912,6 +954,7 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
   }
   const reconcile = (propagateFailure = false) => {
     const current = resolveConfig(configSource())
+    configureRetention(current)
     const generation = ++configurationGeneration
     if (!current.enabled) {
       const operation = controller.uninstall()
@@ -959,6 +1002,7 @@ function applyWithExecutionSeam(ctx, resolvedConfig, seam, volatileHost, volatil
   }
   ctx.effect(() => seam.onSourceChange(() => {
     const current = resolveConfig(configSource())
+    configureRetention(current)
     if (!current.enabled) return undefined
     if (seam.language !== 'typescript') {
       const language = seam.language

package/internal/bounded-literal.js

@@ -0,0 +1,85 @@
+/**
+ * Compile-time evidence that a declaration's initializer is a bounded object
+ * literal.
+ *
+ * Recovery records a binding's value at settlement so it can be installed
+ * without re-executing the cell. Recording an arbitrary object is unsafe: the
+ * value codec enumerates an object's own keys before it can apply any budget,
+ * and enumerating a graph with millions of keys exhausts the worker heap before
+ * a cap can reject it (a four-million-key object aborts a 128 MiB worker).
+ *
+ * This module decides the question where it is cheap — on the syntax tree of the
+ * initializer — and returns the proven shape only for literals whose size is
+ * fixed by their source: an object literal with a bounded number of plain,
+ * non-computed properties whose values are primitives, array literals, or other
+ * such literals up to a fixed depth. Everything else (an identifier, a call, a
+ * class instance) yields no evidence, and its binding stays unrecorded and is
+ * named by recovery instead of being captured.
+ */
+
+/** Maximum number of own properties a recordable literal may declare. */
+export const RECORDED_LITERAL_MAX_PROPERTIES = 32
+
+/** Maximum nesting depth of recordable literals, counting the outer object. */
+export const RECORDED_LITERAL_MAX_DEPTH = 3
+
+/** Maximum number of array elements a recordable array literal may declare. */
+export const RECORDED_LITERAL_MAX_ELEMENTS = 64
+
+const OBJECT_PROPERTY_TYPES = new Set(['ObjectProperty', 'Property'])
+const LITERAL_KEY_TYPES = new Set(['StringLiteral', 'NumericLiteral', 'Literal', 'Identifier'])
+const PRIMITIVE_LITERAL_TYPES = new Set(['StringLiteral', 'NumericLiteral', 'BooleanLiteral', 'NullLiteral',
+  'BigIntLiteral', 'RegExpLiteral'])
+
+function isRecordableValue(node, depth) {
+  if (node === null || node === undefined) return false
+  // ESTree parsers emit `Literal`; Babel emits the typed variants above.
+  if (node.type === 'Literal') {
+    const value = node.value
+    return value === null || ['number', 'string', 'boolean', 'bigint'].includes(typeof value)
+      || node.regex !== undefined
+  }
+  if (PRIMITIVE_LITERAL_TYPES.has(node.type)) return true
+  if (node.type === 'TemplateLiteral') return node.expressions.length === 0
+  if (node.type === 'UnaryExpression') {
+    return ['-', '+', '!', 'void'].includes(node.operator) && isRecordableValue(node.argument, depth)
+  }
+  if (node.type === 'ObjectExpression') return boundedLiteralEvidence(node, depth) !== undefined
+  if (node.type === 'ArrayExpression') {
+    return node.elements.length <= RECORDED_LITERAL_MAX_ELEMENTS
+      && node.elements.every(element => isRecordableValue(element, depth))
+  }
+  return false
+}
+
+/**
+ * Evidence for one object literal, or `undefined` when the literal's size is
+ * not fixed by its source.
+ *
+ * @param {object} node an ESTree/Babel `ObjectExpression`
+ * @param {number} [depth] nest level of this literal, 1 for the top object
+ * @returns {{ properties: number, depth: number } | undefined}
+ */
+export function boundedLiteralEvidence(node, depth = 1) {
+  if (node?.type !== 'ObjectExpression') return undefined
+  if (depth > RECORDED_LITERAL_MAX_DEPTH) return undefined
+  if (node.properties.length > RECORDED_LITERAL_MAX_PROPERTIES) return undefined
+  let proven = 0
+  for (const property of node.properties) {
+    // `kind` is 'init' on most Babel versions and absent on some parses; an
+    // accessor or method arrives as `ObjectMethod`, which this branch rejects
+    // through the `type` check above.
+    if (!OBJECT_PROPERTY_TYPES.has(property.type) || property.computed === true
+      || (property.kind !== undefined && property.kind !== 'init') || property.method === true) return undefined
+    const key = property.key
+    if (!LITERAL_KEY_TYPES.has(key.type)) return undefined
+    const valueNode = property.value
+    if (valueNode.type === 'ObjectExpression') {
+      if (boundedLiteralEvidence(valueNode, depth + 1) === undefined) return undefined
+    } else if (!isRecordableValue(valueNode, depth)) {
+      return undefined
+    }
+    proven += 1
+  }
+  return { properties: proven, depth }
+}

package/internal/capability-command-receipt.js

@@ -6,8 +6,10 @@ const FALLBACKS = Object.freeze({
   pending: 'Capabilities prepared; they take effect at the first accepted model step for session',
   unavailable: 'Select an active PTC session; the command did not update session',
   usage: 'Use /capabilities to inspect or /capabilities refresh to apply saved settings for session',
+  paused: 'Capabilities and context are off; the session stays with the Host capabilities for session',
+  off: 'Capability management is off; the session stays with the Host capabilities for session',
 })
-const STATES = new Set(['recorded', 'pending', 'unavailable', 'usage', 'saved-only'])
+const STATES = new Set(['recorded', 'pending', 'unavailable', 'usage', 'saved-only', 'paused', 'off'])
 
 export function capabilityCommandReceipt(state, sessionId, error, proposal) {
   if (!STATES.has(state) || typeof sessionId !== 'string' || !sessionId) throw new TypeError('invalid capability command receipt')

package/internal/capability-environment.js

@@ -14,6 +14,8 @@ import { PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
 import { deepFreeze } from './record-utils.js'
 import { capabilityProfileConfiguration } from './runtime-config.js'
 import { readRuntimeAvailability } from './runtime-messages.js'
+import { PLAN_CATEGORY_LINES, PLAN_NAVIGATION, PLAN_OVERAGE, PLAN_OVERAGE_HOLE,
+  PROMPT_SLOT_IDS, planCategorySlotId, resolvePromptText, resolvePromptTextConfig } from './prompt-text.js'
 
 export const CAPABILITY_PLAN_FORM = 'capability-plan'
 export const CAPABILITY_EVIDENCE_KEY = 'dshPtcPlusCapabilities'
@@ -25,6 +27,54 @@ const LEGACY_NAVIGATION = 'Use capabilities.search({query}) to retrieve complete
 const NAVIGATION = 'Use capabilities.search({query}) to retrieve complete tool, Skill and MCP contracts. Unlisted capabilities remain discoverable. Skill descriptions are summaries; follow each Skill\'s declared invocation eligibility to load its body before following it.'
 const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex')
 const messageText = message => message?.content?.filter(block => block.type === 'text').map(block => block.text).join('\n') ?? ''
+const byteLength = value => Buffer.byteLength(value, 'utf8')
+
+/**
+ * Delivered plan-channel text, resolved from the prompt-text document.
+ *
+ * The planner must receive the same words the panel shows, so the navigation
+ * sentence, the five category lines and the overage template are read once here
+ * rather than defaulting inside the planner. `isDefault` decides whether the
+ * snapshot can keep a historical generation: only an edited channel needs the v5
+ * record, so an untouched configuration stays byte-identical to before.
+ */
+function planChannelText(config) {
+  const prompt = resolvePromptTextConfig(config)
+  const navigationSentence = prompt.text(PROMPT_SLOT_IDS.planNavigationSentence)
+  const overageSentence = prompt.text(PROMPT_SLOT_IDS.planOverageSentence)
+  const categoryLines = Object.keys(PLAN_CATEGORY_LINES)
+    .map(category => [category, prompt.text(planCategorySlotId(category))])
+  const isDefault = navigationSentence === PLAN_NAVIGATION
+    && overageSentence === PLAN_OVERAGE
+    && categoryLines.every(([category, line]) => line === PLAN_CATEGORY_LINES[category])
+  return { navigationSentence, overageSentence, categoryLines, isDefault }
+}
+
+/**
+ * Directory budget for the delivered guidance.
+ *
+ * Editing a navigation sentence changes how many bytes the directory spends before
+ * any capability entry, so the budget moves with the text: an unchanged document
+ * therefore keeps today's budget exactly, and a longer sentence does not silently
+ * shrink the catalog.
+ */
+const planDirectoryBudget = (configured, navigationSentence) => (
+  configured + byteLength(navigationSentence) - byteLength(PLAN_NAVIGATION))
+
+/**
+ * Recorded plan text; a v5 snapshot carries the words and the budget it was
+ * composed from.
+ *
+ * The budget belongs in the record because it depends on the navigation sentence:
+ * replaying it from the current default literal would let a later edit of that
+ * literal silently change what an old snapshot replays to.
+ */
+const planPromptText = (channel, directoryBudgetBytes) => ({ promptText: {
+  navigationSentence: channel.navigationSentence,
+  categoryLines: channel.categoryLines.map(([category, line]) => [category, line]),
+  overageSentence: channel.overageSentence,
+  directoryBudgetBytes,
+} })
 
 /** Saved inputs and explicit session choices are distinct; automatic cancels a saved override. */
 export function sessionCapabilitySettings(sourceSettings, sessionOverrides = {}) {
@@ -85,9 +135,19 @@ function sourcePlan(message, id) {
   const source = message?.source
   if (source?.kind !== PTC_MESSAGE_SOURCE_KIND || source.form !== CAPABILITY_PLAN_FORM || source.sessionId !== id) return undefined
   const snapshot = source.snapshot
-  const generation = ['ptc-capability-environment/v1', 'ptc-capability-environment/v2', 'ptc-capability-environment/v3', 'ptc-capability-environment/v4'].indexOf(snapshot?.schema)
+  const generation = ['ptc-capability-environment/v1', 'ptc-capability-environment/v2', 'ptc-capability-environment/v3',
+    'ptc-capability-environment/v4', 'ptc-capability-environment/v5'].indexOf(snapshot?.schema)
+  // Historical generations each had one planner generation for a given settings
+  // shape, so their plan schema is part of the record's identity. Generation 5
+  // records the plan words instead, and its plan schema follows from the recorded
+  // settings: the recomputation below proves the whole plan, which makes a separate
+  // schema guess both unnecessary and wrong (a v5 snapshot may carry context
+  // settings and therefore a v3 plan, or a closed plan and therefore a v2 one).
+  const expectedPlanSchema = generation === 2 ? 'ptc-capability-plan/v2'
+    : generation >= 3 && snapshot.settings.policy !== undefined ? 'ptc-capability-plan/v3' : 'ptc-capability-plan/v1'
   if (source.digest !== digest(snapshot) || generation < 0
-    || !Array.isArray(snapshot.capabilities) || snapshot.plan?.schema !== (generation === 3 ? 'ptc-capability-plan/v3' : generation === 2 ? 'ptc-capability-plan/v2' : 'ptc-capability-plan/v1')) {
+    || !Array.isArray(snapshot.capabilities)
+    || (generation < 4 && snapshot.plan?.schema !== expectedPlanSchema)) {
     throw new Error('damaged session capability plan')
   }
   if (generation >= 1) {
@@ -100,30 +160,74 @@ function sourcePlan(message, id) {
     }
     if (JSON.stringify(merged) !== JSON.stringify(snapshot.settings)) throw new Error('inconsistent session capability choices')
   }
-  if (generation === 3 ? typeof snapshot.settings.contextEnabled !== 'boolean' : snapshot.settings.contextEnabled !== undefined) {
+  // v4 implies a context generation; v5 only says the plan words were edited, so it
+  // may or may not carry context settings.
+  const contextGeneration = generation === 3 ? typeof snapshot.settings.contextEnabled === 'boolean'
+    : generation === 4 ? true : snapshot.settings.contextEnabled === undefined
+  if (!contextGeneration) {
     throw new Error('inconsistent capability context generation')
   }
-  if (generation === 2 || generation === 3 && snapshot.settings.policy !== undefined) {
+  if (generation === 2 || generation >= 3 && snapshot.settings.policy !== undefined) {
     if (!snapshot.settings.policy || typeof snapshot.settings.recoveryEnabled !== 'boolean'
       || typeof snapshot.settings.previewEnabled !== 'boolean') throw new Error('damaged capability policy settings')
   } else if (snapshot.settings.policy !== undefined) throw new Error('inconsistent historical capability generation')
-  if (snapshot.navigationText !== undefined && snapshot.navigationText !== NAVIGATION) throw new Error('unknown capability navigation contract')
+  // A v5 snapshot carries the plan words it was composed from; a historical
+  // generation may only claim the registry defaults it was delivered with.
+  const recorded = generation === 4 ? planRecord(snapshot) : undefined
+  if (recorded === undefined) {
+    if (snapshot.promptText !== undefined) throw new Error('inconsistent capability plan text generation')
+    if (snapshot.navigationText !== undefined && snapshot.navigationText !== NAVIGATION) throw new Error('unknown capability navigation contract')
+  } else if (snapshot.navigationText !== recorded.navigationSentence) {
+    throw new Error('damaged capability plan text')
+  }
   const expected = createCapabilityPlan({ ...snapshot.settings, capabilities: snapshot.capabilities,
     coverage: snapshot.coverage, navigationText: snapshot.navigationText ?? LEGACY_NAVIGATION,
+    ...(recorded === undefined ? {} : {
+      categories: recorded.categoryLines,
+      directoryBudgetBytes: recorded.directoryBudgetBytes,
+    }),
     configurationRevision: digest(snapshot.settings) })
-  if (JSON.stringify(expected) !== JSON.stringify(snapshot.plan)
+  if ((generation >= 4 && snapshot.plan?.schema !== expected.schema)
+    || JSON.stringify(expected) !== JSON.stringify(snapshot.plan)
     || messageText(message) !== messageText(planMessage(snapshot, id, source.refresh === true))) {
     throw new Error('inconsistent session capability plan')
   }
   return deepFreeze(structuredClone(snapshot))
 }
 
+/**
+ * Validated plan words of a v5 snapshot.
+ *
+ * Returns `undefined` only when the snapshot carries no record at all; a record that
+ * exists but cannot be replayed throws, because a half-recorded plan text would let
+ * a later replay silently deliver different words than the ones recorded here.
+ */
+function planRecord(snapshot) {
+  const record = snapshot.promptText
+  if (record === undefined || record === null) return undefined
+  const categories = record.categoryLines
+  const known = Object.keys(PLAN_CATEGORY_LINES)
+  if (typeof record.navigationSentence !== 'string' || record.navigationSentence.length === 0
+    || typeof record.overageSentence !== 'string' || record.overageSentence.split(PLAN_OVERAGE_HOLE).length !== 2
+    || !Number.isSafeInteger(record.directoryBudgetBytes) || record.directoryBudgetBytes < 0
+    || !Array.isArray(categories) || categories.length !== known.length
+    || categories.some(pair => !Array.isArray(pair) || pair.length !== 2
+      || !known.includes(pair[0]) || typeof pair[1] !== 'string' || pair[1].length === 0)
+    || new Set(categories.map(pair => pair[0])).size !== categories.length) {
+    throw new Error('damaged capability plan text')
+  }
+  return { navigationSentence: record.navigationSentence, overageSentence: record.overageSentence,
+    directoryBudgetBytes: record.directoryBudgetBytes,
+    categoryLines: categories.map(([category, line]) => [category, line]) }
+}
+
 function planMessage(snapshot, id, refresh = false) {
   const plan = snapshot.plan
+  const overage = snapshot.promptText?.overageSentence ?? PLAN_OVERAGE
   const text = plan.enabled
     ? ['PTC Plus session capability environment' + (refresh ? ' refreshed; replaces the preceding capability plan.' : ':'),
       plan.directoryText, plan.catalogText,
-      ...(plan.budgets.overageBytes ? [`Explicit full contracts exceed the configured budget by ${plan.budgets.overageBytes} UTF-8 bytes.`] : [])]
+      ...(plan.budgets.overageBytes ? [overage.replace(PLAN_OVERAGE_HOLE, String(plan.budgets.overageBytes))] : [])]
       .filter(Boolean).join('\n\n')
     : snapshot.settings.contextEnabled === false
       ? 'PTC Plus capability and context settings are paused for this session. Use the host-provided capability contracts and result presentation.'
@@ -132,6 +236,43 @@ function planMessage(snapshot, id, refresh = false) {
     sessionId: id, refresh, digest: digest(snapshot), snapshot }, content: [{ type: 'text', text }] })
 }
 
+/**
+ * Delivered plan text for a snapshot, without the message envelope.
+ *
+ * Replay and the surface gate both need the bytes the model reads; keeping the
+ * composition private to this module means a caller cannot assemble a different
+ * plan and call it the delivered one.
+ */
+export function capabilityPlanText(snapshot, id, refresh = false) {
+  return planMessage(snapshot, id, refresh).content[0].text
+}
+
+/**
+ * Delivered plan message for a snapshot, envelope included.
+ *
+ * What this composition can claim is consistency, not provenance: the settings merge
+ * is a fixed point of the recorded settings, the recorded plan deep-equals a
+ * recomputation from them, the delivered text equals a recomposition of that plan and
+ * the snapshots it reads are deeply frozen. It recomputes the digest, so it cannot
+ * attest that these bytes are the ones a session log once carried.
+ */
+export function capabilityPlanMessage(snapshot, id, refresh = false) {
+  return planMessage(snapshot, id, refresh)
+}
+
+/**
+ * Delivered plan text of a plan message, after the replay contract accepted it.
+ *
+ * The reader above stays a recognizer and hands out no composition state; a caller
+ * that needs the bytes the model read asks this projection instead. An unreplayable
+ * message throws, so a lane that compares bytes cannot pass by receiving `undefined`.
+ */
+export function capabilityPlanTextFromMessage(message, sessionId) {
+  if (message?.source?.form !== CAPABILITY_PLAN_FORM) return undefined
+  sourcePlan(message, sessionId)
+  return message.content[0].text
+}
+
 /** Recognize capability-owned presentation for bounded offline context accounting. */
 export function readCapabilityContextMessage(message, sessionId) {
   const source = message?.source
@@ -702,12 +843,24 @@ export function createCapabilityEnvironment({ ctx, config, toolSchemasForAgent,
       const capabilities = requiresCapabilityInventory(settings) ? await inventory(agent, sections ?? [], settings, signal) : []
       const effective = effectiveCapabilitySettings(settings)
       const coverage = (effective.policy ? effective.enabled && effective.policy.allocation.statistics : effective.statistics?.enabled === true) ? await store?.coverage(agent, capabilities, settings.statistics) : undefined
+      const planChannel = planChannelText(currentConfig)
+      const directoryBudgetBytes = planDirectoryBudget(settings.directoryBudgetBytes, planChannel.navigationSentence)
       const plan = createCapabilityPlan({ ...settings, configurationRevision: digest(settings),
-        capabilities, coverage, navigationText: NAVIGATION })
+        capabilities, coverage, navigationText: planChannel.navigationSentence,
+        categories: planChannel.categoryLines,
+        directoryBudgetBytes })
       const hasChoices = settings.contextEnabled !== undefined || settings.policy !== undefined || choice !== undefined || previous?.schema === 'ptc-capability-environment/v2'
-      const snapshot = deepFreeze({ schema: settings.contextEnabled !== undefined ? 'ptc-capability-environment/v4' : settings.policy ? 'ptc-capability-environment/v3' : hasChoices ? 'ptc-capability-environment/v2' : 'ptc-capability-environment/v1',
-        ...(hasChoices ? { sourceSettings, sessionOverrides } : {}), navigationText: NAVIGATION, settings, capabilities, ...(coverage === undefined ? {} : { coverage }), plan })
-      const message = planMessage(snapshot, id, force)
+      // An edited plan channel needs the v5 record, and that generation requires the
+      // saved inputs and session choices it was composed from.
+      const recordsText = !planChannel.isDefault
+      const snapshot = deepFreeze({ schema: recordsText ? 'ptc-capability-environment/v5'
+        : settings.contextEnabled !== undefined ? 'ptc-capability-environment/v4' : settings.policy ? 'ptc-capability-environment/v3'
+          : hasChoices ? 'ptc-capability-environment/v2' : 'ptc-capability-environment/v1',
+        ...(hasChoices || recordsText ? { sourceSettings, sessionOverrides } : {}),
+        ...(recordsText ? planPromptText(planChannel, directoryBudgetBytes) : {}),
+        navigationText: planChannel.navigationSentence, settings, capabilities, ...(coverage === undefined ? {} : { coverage }), plan })
+      const initialized = sessionEvents(agent.session).some(event => event.type === 'system/message')
+      const message = planMessage(snapshot, id, force && initialized)
       agent.signal?.throwIfAborted?.()
       signal?.throwIfAborted()
       // Initialized sessions commit a refresh and its notification atomically.
@@ -716,7 +869,7 @@ export function createCapabilityEnvironment({ ctx, config, toolSchemasForAgent,
         hostSections: sections ?? [], expanded: new Set(), used: new Map(),
         ...(requiresCapabilityInventory(settings) ? { liveCapabilities: new Map(capabilities.map(item => [item.id, item])) } : {}) }
       restoreEvidence(agent, state)
-      if (choice?.commandId && !sessionEvents(agent.session).some(event => event.type === 'system/message')) {
+      if (choice?.commandId && !initialized) {
         state.pendingCommand = choice.commandId
         state.pendingPrevious = stateFor(agent)
       }
@@ -1186,7 +1339,12 @@ export function createCapabilityEnvironment({ ctx, config, toolSchemasForAgent,
         || String(agent.session.id ?? agent.id) !== sessionId) {
         throw new Error('ptc-plus: capability observation target is no longer available')
       }
-      return { schema: 'ptc-capability-session-catalog/v1', management, entries }
+      const savedSettings = capabilityConfiguration(currentConfig)
+      // The saved group and management switches gate session writes in change();
+      // report them so the Client can block staged choices with the reason.
+      return { schema: 'ptc-capability-session-catalog/v1', management, entries,
+        savedSettings: { enabled: effectiveCapabilitySettings(savedSettings).enabled === true,
+          contextEnabled: savedSettings.contextEnabled !== false } }
     },
     async observeAllocation({ sessionId, configuration } = {}, signal) {
       signal?.throwIfAborted()

package/internal/capability-plan.js

@@ -1,16 +1,12 @@
 import { capabilityRule, validateCapabilityPolicy, effectiveCapabilitySettings } from './capability-policy.js'
 import { Buffer } from 'node:buffer'
+import { PLAN_CATEGORY_LINES } from './prompt-text.js'
 
 const MANAGED_CATEGORIES = new Set(['tool', 'skill', 'resource', 'resource-template', 'task'])
 const EXCLUDED_CATEGORIES = new Set(['language', 'node', 'repl', 'ptc-plus', 'global-binding'])
 const SELECTIONS = new Set(['full', 'on-demand', 'closed'])
-const CATEGORY_NAVIGATION = new Map([
-  ['tool', 'Tools: search by task or tools.<name> for parameters and results.'],
-  ['skill', 'Skills: search by task or skills.<name> for when to use and how to load instructions.'],
-  ['resource', 'MCP resources: search by server or resource purpose.'],
-  ['resource-template', 'MCP templates: search by server or resource purpose.'],
-  ['task', 'Tasks: search by the operation you need.'],
-])
+/** Category guidance defaults; the registry owns the delivered literals. */
+const CATEGORY_NAVIGATION = new Map(Object.entries(PLAN_CATEGORY_LINES))
 
 function isRecord(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) }
 
@@ -121,6 +117,13 @@ function createLegacyCapabilityPlan(input) {
   const budgetBytes = integer(options.budgetBytes, 'contract budget bytes')
   const directoryBudgetBytes = integer(options.directoryBudgetBytes, 'directory budget bytes')
   const navigationText = text(options.navigationText, 'bounded discovery guidance')
+  const categoryNavigation = options.categories === undefined
+    ? CATEGORY_NAVIGATION
+    : new Map(options.categories.map(pair => {
+      if (!Array.isArray(pair) || pair.length !== 2) throw new TypeError('ptc-plus: capability categories must be [category, guidance] pairs')
+      const category = text(pair[0], `capability category ${pair[0]}`)
+      return [category, text(pair[1], `capability guidance for ${category}`)]
+    }))
   if (bytes(navigationText) > directoryBudgetBytes) throw new RangeError('ptc-plus: discovery guidance exceeds directory byte budget')
   const manual = record(options.manual ?? {}, 'manual capability settings')
   const overrides = record(manual.overrides ?? {}, 'capability overrides')
@@ -220,7 +223,7 @@ function createLegacyCapabilityPlan(input) {
   const directoryCategories = []
   const availableCategories = new Set(capabilities.filter(capability => selections.get(capability.id).selection !== 'closed')
     .map(capability => capability.category))
-  for (const [category, guidance] of CATEGORY_NAVIGATION) {
+  for (const [category, guidance] of categoryNavigation) {
     if (!availableCategories.has(category)) continue
     const proposed = `${directoryText}\n${guidance}`
     if (bytes(proposed) <= directoryBudgetBytes) {

package/internal/capability-statistics.js

@@ -198,12 +198,16 @@ export function capabilityCoverage(state, query) {
   const workspaceId = options.workspaceId === null ? null : identity(options.workspaceId, 'coverage workspace identity')
   if (state.status !== 'usable') return { status: state.status, windowSize: state.limits.windowSize, eligible: null, used: null, coverage: null }
   const window = state.windows.find(item => item.userId === userId && item.workspaceId === workspaceId && item.id === id && item.revision === revision)
-  const families = window ? state.families.filter(item => qualifies(item, window)).sort(orderSamples).slice(0, state.limits.windowSize) : []
+  // "Nothing recorded yet" and "recorded families are not currently settled"
+  // are different facts from a measured window; neither may read as a zero.
+  if (window === undefined) return { status: 'no-samples', windowSize: state.limits.windowSize, eligible: null, used: null, coverage: null }
+  const families = state.families.filter(item => qualifies(item, window)).sort(orderSamples).slice(0, state.limits.windowSize)
   // A resumed family can expose a gap behind the irreversible eviction frontier.
   // Surviving samples do not prove the recent settled window until it is full again.
-  if (window?.floor > 0 && families.length < state.limits.windowSize) {
+  if (window.floor > 0 && families.length < state.limits.windowSize) {
     return { status: 'incomplete-window', windowSize: state.limits.windowSize, eligible: null, used: null, coverage: null }
   }
+  if (families.length === 0) return { status: 'pending-settlement', windowSize: state.limits.windowSize, eligible: null, used: null, coverage: null }
   const used = families.filter(family => family.observations.some(item => item.id === id && item.revision === revision && item.used
     && (workspaceId === null || item.workspaceId === workspaceId))).length
   return { status: 'usable', windowSize: state.limits.windowSize, eligible: families.length, used, coverage: families.length ? used / families.length : null }