dsh-ptc-plus 0.5.2 → 0.5.3

package/internal/session-runtime.js

@@ -180,6 +180,34 @@ export function vanishedBindingDiagnostic(names) {
   })
 }
 
+/**
+ * Notice for bindings a recorded revision superseded.
+ *
+ * A revision that rewrites its target puts the target off the recorded path, so
+ * the target's declarations stop building the environment. They are not missing:
+ * the log says which revision replaced them, and reporting that relation keeps
+ * the model from reading a later `x is not defined` as its own mistake.
+ */
+export function supersededDiagnostic(bindings, supersessions = []) {
+  const names = bindings.length === 0 ? '' : ` (${bindings.join(', ')})`
+  const relations = supersessions.map(item =>
+    `cell ${item.supersededCallSeq} by cell ${item.supersedingCallSeq}`).join('; ')
+  return diagnostic({
+    code: 'PTC-R007',
+    severity: 'warning',
+    phase: 'recover',
+    message: (bindings.length === 0
+      ? 'A recorded revision replaced the cell it edited'
+      : `Superseded ${bindings.length} binding(s)${names} because a recorded revision replaced the cell that declared them`)
+      + `${relations === '' ? '' : ` (${relations})`}. The replaced cell stays in the session log but no longer builds this environment.`,
+    stateEffect: 'rolled-back',
+    help: [
+      'this is not a recovery failure: an accepted edit rewrote the cell that declared these bindings, and the revision does not declare them',
+      'redeclare a superseded name in a new cell before using it again',
+    ],
+  })
+}
+
 function unverifiedCompletionDiagnostic(count) {
   return diagnostic({
     code: 'PTC-R003',
@@ -329,19 +357,21 @@ class SessionKernel {
     this.liveCallSeqs = new Set()
     this.unverifiedCompletions = []
     this.restoredFromRecord = []
-    this.recoveryNotice = disposedCells > 0
+    this.recoveryNotices = disposedCells > 0
       // A kernel whose owning agent or session was disposed must not resurrect
       // the disposed environment: the history is gone by contract, and a later
       // cell starts from an empty REPL with the loss reported once.
-      ? recoveryDiagnostic([], disposedCells)
+      ? [recoveryDiagnostic([], disposedCells)]
       : history.volatileSuffix.length === 0
-        ? undefined
-        : recoveryDiagnostic(droppedBindingNames(history), history.volatileSuffix.length)
-    this.recoveryNoticeShown = false
+        ? []
+        : [recoveryDiagnostic(droppedBindingNames(history), history.volatileSuffix.length)]
     // Bindings a recovery told the model were live, and the last help pair that
     // explained a recovery. Both exist to keep one event from being reported
     // twice and to notice a binding that stops existing afterwards.
     this.announcedLive = new Set()
+    // A recorded supersession is a durable fact; announcing it once per runtime
+    // keeps later folds from repeating a relation the model already read.
+    this.announcedSupersessions = new Set()
     this.recoveryHelpSignature = undefined
     this.recoveryEventCount = 0
     this.active = undefined
@@ -558,27 +588,29 @@ class SessionKernel {
         if (worker !== undefined) await this.resetWorker(worker)
         this.rollbackToDurable()
         if (config.durableReplay) {
-          this.recoveryNotice = undefined
+          this.recoveryNotices = []
           try {
             this.history = recoverJournal(observedSession, request.callSeq, {
               visibleCallSeqs,
+              editRewritesHistory: config.editRewritesHistory === true,
             })
           } catch (error) {
-            /* c8 ignore start -- a fold that throws is not reachable from any supported session; cover or prove it in 0.5.3 */
+            /* c8 ignore start -- the fold reports damaged history as data, so no supported session reaches this catch */
             const boundary = recoveryBoundaryForHistory(this.history, undefined, { reset: true })
             if (boundary !== undefined) recoveryBoundaries.push(boundary)
             this.history = emptyHistory()
-            this.recoveryNotice = recoveryDiagnostic([], 1)
+            this.recoveryNotices = [recoveryDiagnostic([], 1)]
             this.initialRecoveryBoundary = undefined
             /* c8 ignore stop */
           }
-          /* c8 ignore start -- volatile suffix on the first fold; cover in 0.5.3 */
+          /* c8 ignore start -- volatile suffix on the first fold; no case settles a volatile suffix before the first replay */
           if (this.history.volatileSuffix.length > 0) {
-            this.recoveryNotice = recoveryDiagnostic(droppedBindingNames(this.history), this.history.volatileSuffix.length)
+            this.recoveryNotices = [recoveryDiagnostic(
+              droppedBindingNames(this.history), this.history.volatileSuffix.length)]
           }
           /* c8 ignore stop */
           this.initialRecoveryBoundary = recoveryBoundaryForHistory(this.history)
-          /* c8 ignore start -- first-fold recovery boundary; cover in 0.5.3 */
+          /* c8 ignore start -- first-fold recovery boundary; no case makes the first replay record one */
           if (this.initialRecoveryBoundary !== undefined) {
             recoveryBoundaries.push(this.initialRecoveryBoundary)
             this.initialRecoveryBoundary = undefined
@@ -587,7 +619,7 @@ class SessionKernel {
         } else {
           this.history = emptyHistory()
           this.replayed = true
-          this.recoveryNotice = recoveryDiagnostic([], 1)
+          this.recoveryNotices = [recoveryDiagnostic([], 1)]
         }
       }
     }
@@ -680,6 +712,7 @@ class SessionKernel {
             const recovered = recoverJournal(observedSession, request.callSeq, {
               extraBoundaries: [boundary],
               visibleCallSeqs: visibleExecutableCallSeqs(observedSession),
+              editRewritesHistory: config.editRewritesHistory === true,
             })
             const nextPathLength = pathToHead(recovered).length
             if (nextPathLength >= previousPathLength) throw new Error('recovery did not contract the historical frontier')
@@ -698,10 +731,12 @@ class SessionKernel {
           this.durability = durabilityState()
         }
       }
-      // One recovery event produces one notice. The four facts below describe the
-      // same event, so they are composed once instead of overwriting each other:
-      // an earlier overwrite dropped the restored-name list whenever a later fact
-      // arrived, and a repeat entry re-emitted the same sentence.
+      // One recovery event produces one report. The facts below describe the same
+      // event, so each one that holds is collected instead of overwriting the ones
+      // already found: an earlier overwrite dropped the restored-name list whenever
+      // a later fact arrived, and a relation dropped that way was then cleared
+      // without ever reaching the model. The facts never name the same binding, so
+      // collecting them states the event once per fact rather than twice per name.
       const restoredCount = this.restoredFromRecord.length
       const allLive = [...new Set(this.restoredFromRecord.flatMap(item => item.bindings))]
       // Report only what this recovery added. A later recovery that installs
@@ -716,6 +751,8 @@ const failedNames = [...new Set(this.restoredFromRecord
   .filter(name => typeof name === 'string'))]
       const droppedNames = this.missingBindings === undefined ? [] : [...new Set(this.missingBindings)]
       const endedNames = this.rewindEndedBindings === undefined ? [] : [...new Set(this.rewindEndedBindings)]
+      const supersededNames = this.supersededEndedBindings === undefined
+        ? [] : [...new Set(this.supersededEndedBindings)]
       const alreadyReported = this.recoveryEventCount > 0
       // A complete restore is invisible to the model. Every recorded binding was
       // installed, nothing was dropped or ended, and the next cell behaves exactly
@@ -726,58 +763,78 @@ const failedNames = [...new Set(this.restoredFromRecord
       const completeRestore = failedNames.length === 0
         && droppedNames.length === 0
         && endedNames.length === 0
+        && supersededNames.length === 0
       if (restoredCount > 0 && completeRestore) {
         this.restoredFromRecord = []
-      /* c8 ignore start -- needs a rewind that ended an announced name; cover in 0.5.3 */
+      /* c8 ignore start -- needs a rewind that ended an announced name after a reported recovery; no case does */
       } else if (restoredCount > 0 && liveNames.length === 0 && failedNames.length === 0 && alreadyReported) {
         this.restoredFromRecord = []
       /* c8 ignore stop */
       } else if (restoredCount > 0) {
         this.recoveryEventCount += 1
-        this.recoveryNotice = restoredFromRecordDiagnostic(
+        this.recoveryNotices.push(restoredFromRecordDiagnostic(
           restoredCount,
           liveNames,
           failedNames,
           alreadyReported,
-        )
+        ))
       }
-      /* c8 ignore start -- needs a proven name the replay never visits; cover in 0.5.3 */
+      /* c8 ignore start -- needs a proven name the replay never visits; no case records one */
       if (droppedNames.length > 0) {
-        this.recoveryNotice = recoveryDiagnostic(droppedNames, droppedNames.length)
+        this.recoveryNotices.push(recoveryDiagnostic(droppedNames, droppedNames.length))
       /* c8 ignore stop */
       } else if (restoredCount === 0 && skipped > 0) {
-        this.recoveryNotice = recoveryDiagnostic([], skipped)
+        this.recoveryNotices.push(recoveryDiagnostic([], skipped))
       }
       // A rewind that ended a binding is recorded, not a loss: report it only when
       // the replay installed nothing under that name anywhere (path, off-path or
-      // catalog), so a correct value never carries a "dropped" notice.
-      if (this.recoveryNotice === undefined && endedNames.length > 0) {
-        this.recoveryNotice = rewindEndedDiagnostic(endedNames)
+      // catalog), so a correct value never carries a "dropped" notice. A revision
+      // that superseded a cell is the other recorded ending: the environment it
+      // built differs from the cells the log still lists, so the relation is
+      // reported once per runtime instead of on every later fold.
+      const freshSupersessions = (this.supersessions ?? [])
+        .filter(item => !this.announcedSupersessions.has(item.supersedingCallSeq))
+      // A restored cell and a superseded one are two facts about the same recovery,
+      // not alternatives: the names this relation withdrew are excluded from the
+      // missing and rewind lists, so a report that chose the restore notice over it
+      // left a withdrawn name reported nowhere.
+      if (freshSupersessions.length > 0 || supersededNames.length > 0) {
+        this.recoveryNotices.push(supersededDiagnostic(supersededNames, freshSupersessions))
+        for (const item of freshSupersessions) this.announcedSupersessions.add(item.supersedingCallSeq)
       }
-      if (this.recoveryNotice === undefined && this.unverifiedCompletions.length > 0) {
-        this.recoveryNotice = unverifiedCompletionDiagnostic(this.unverifiedCompletions.length)
+      if (endedNames.length > 0) {
+        this.recoveryNotices.push(rewindEndedDiagnostic(endedNames))
       }
       // A completion the replay could not certify is not a lost binding: the
       // replay established them, and only the recorded payload stays unproved.
-      if (this.recoveryNotice !== undefined) {
+      if (this.unverifiedCompletions.length > 0) {
+        this.recoveryNotices.push(unverifiedCompletionDiagnostic(this.unverifiedCompletions.length))
+      }
+      if (this.recoveryNotices.length > 0) {
         // Remember what was promised as live, so a binding that disappears later
         // is reported by name instead of surfacing as an unexplained ReferenceError.
         for (const name of liveNames) this.announcedLive.add(name)
         // The help pair explains the recovery once. Repeating it on every later
         // recovery in the same session is noise the model cannot act on twice.
-        const signature = this.recoveryNotice.message
-        if (this.recoveryHelpSignature === signature) this.recoveryNotice = { ...this.recoveryNotice, help: [] }
-        else this.recoveryHelpSignature = signature
+        const signature = this.recoveryNotices.map(item => item.message).join('\n')
+        if (this.recoveryHelpSignature === signature) {
+          this.recoveryNotices = this.recoveryNotices.map(item => ({ ...item, help: [] }))
+        } else {
+          this.recoveryHelpSignature = signature
+        }
       }
       this.restoredFromRecord = []
       this.missingBindings = undefined
       this.rewindEndedBindings = undefined
+      this.supersededEndedBindings = undefined
+      this.supersessions = undefined
     }
-    const leadingDiagnostics = [
-      ...(this.recoveryNotice === undefined || this.recoveryNoticeShown ? [] : [this.recoveryNotice]),
-    ]
-    this.recoveryNoticeShown = this.recoveryNotice !== undefined
-    this.recoveryNotice = undefined
+    // Every recovery reports the facts it established. Suppressing a later recovery's
+    // notice hid a relation the runtime had already marked as announced, so a name the
+    // revision withdrew was reported nowhere; what is deduplicated is the explanation
+    // (below) and each name or relation this runtime already stated.
+    const leadingDiagnostics = this.recoveryNotices
+    this.recoveryNotices = []
     if (request.journal !== undefined) request.journal.diagnostics.push(...leadingDiagnostics)
     let result
     try {
@@ -938,9 +995,17 @@ const failedNames = [...new Set(this.restoredFromRecord
     // correct.
     const installed = new Set(replayedNames)
     for (const name of this.bindingCatalog.inputs().knownBindings) installed.add(name)
-    this.rewindEndedBindings = [...endedBindings].filter(name => !installed.has(name))
+    // A superseded name is ended by the record that replaced its cell, so it is
+    // reported apart from a rewind and never as a binding recovery failed to
+    // install: the log says which revision replaced it.
+    const supersededEnded = new Set((this.history.supersededBindings ?? [])
+      .filter(name => !installed.has(name)))
+    this.rewindEndedBindings = [...endedBindings]
+      .filter(name => !installed.has(name) && !supersededEnded.has(name))
+    this.supersededEndedBindings = [...supersededEnded]
+    this.supersessions = this.history.supersessions ?? []
     this.missingBindings = (this.history.provenBindings ?? [])
-      .filter(name => !installed.has(name) && !endedBindings.has(name))
+      .filter(name => !installed.has(name) && !endedBindings.has(name) && !supersededEnded.has(name))
   }
 
   completeJournal(journal, status, result, volatileReason, diagnostics = [], completion = undefined, values = undefined) {
@@ -1372,7 +1437,8 @@ export class SessionRuntime {
         kernel.surfaceGeneration = surfaceGeneration(session)
       } else {
         const timeline = foldSessionTimeline(observed.events)
-        const history = recoverJournal(observed, undefined, { visibleCallSeqs: visible })
+        const history = recoverJournal(observed, undefined, { visibleCallSeqs: visible,
+          editRewritesHistory: this.config.editRewritesHistory === true })
         const head = history.nodes[history.head]
         if (head === undefined) return unavailableReplMemorySnapshot()
         // A cold inventory can describe a proved recorded frontier without
@@ -1468,6 +1534,7 @@ export class SessionRuntime {
           ? emptyHistory()
           : recoverJournal(sessionLog, callSeq, {
             visibleCallSeqs: visibleExecutableCallSeqs(sessionLog),
+            editRewritesHistory: cellConfig.editRewritesHistory === true,
             ...(liveOnlyLost ? { liveOnlyLost: true } : {}),
           })
       } catch (error) {

package/internal/user-bindings-owner.js

@@ -1,5 +1,12 @@
 import { PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
+import { sessionExecutionAvailable } from './host-tool-sdk.js'
 import { bindingToggleMessage } from './binding-toggle-receipt.js'
+import {
+  bindingAdoptionMessage,
+  clearedBindingAdoption,
+  declinedBindingEntries,
+  withBindingAdoption,
+} from './binding-adoption.js'
 import { RPC_CONTRACTS } from './rpc-contract.js'
 import { randomUUID } from 'node:crypto'
 import { dirname } from 'node:path'
@@ -26,6 +33,7 @@ import {
   createUserBindingsSnapshot,
   normalizeUserBindingEntry,
   normalizeUserBindingsDocument,
+  selectUserBindingsSnapshot,
   storedUserBindingsDocument,
 } from './user-bindings.js'
 
@@ -78,6 +86,40 @@ function parseAuthoringCommand(rawInput) {
   return { kind: 'help' }
 }
 
+/**
+ * The adoption subcommands of `/binding`. They state which supplied entries this
+ * session uses; authoring and adoption share one command because both answer
+ * questions about the same global catalog, and a second command would suggest
+ * they were separate features.
+ */
+function parseAdoptionCommand(rawInput) {
+  const input = typeof rawInput === 'string' ? rawInput.trim() : ''
+  if (input === 'status') return { kind: 'status' }
+  if (input === 'reset') return { kind: 'reset' }
+  const decision = /^(use|skip)\s+(\S+)$/.exec(input)
+  if (decision === null) return undefined
+  return { kind: decision[1] === 'use' ? 'use' : 'skip', id: decision[2] }
+}
+
+function adoptionStatusText(catalog, adoption) {
+  const declined = declinedBindingEntries(adoption)
+  const supplied = catalog.entries
+  const listed = supplied.map(entry => `${entry.id} (${entry.name}): ${declined.has(entry.id)
+    ? 'not used by this session' : 'used by this session'}`)
+  const unavailable = [...declined].filter(id => !supplied.some(entry => entry.id === id))
+  return [
+    'Global binding catalog supply and this session\'s adoption of it. Adoption decides which supplied entries this session uses; it does not report whether the worker installed them.',
+    ...(listed.length === 0 ? ['The global catalog supplies no enabled entries.'] : listed),
+    ...(unavailable.length === 0 ? [] : [`Declined but not supplied by the global catalog, therefore not used and not revivable here: ${JSON.stringify(unavailable)}`]),
+  ].join('\n')
+}
+
+function adoptionReceipt(adoption) {
+  return `Session binding adoption recorded. This session declines ${JSON.stringify([...declinedBindingEntries(adoption)])}. `
+    + 'The global catalog and other sessions are unchanged, and adoption can only withdraw a supplied entry. '
+    + 'Whether the worker installed the entries this session still uses is reported with the next accepted cell, not by this receipt.'
+}
+
 function authoringTask(command, current) {
   if (command.kind === 'new') {
     return `Create a Global User Binding draft for this requirement:\n\n${command.requirement}`
@@ -265,6 +307,48 @@ export function createUserBindingsOwner(ctx, options = {}) {
   const requireEnabled = () => {
     if (!enabled) throw new Error('Global User Bindings are disabled')
   }
+  // Adoption is read from the session's own recorded decision, never from a
+  // second in-memory map: the log is the owner, so a restart reconstructs the
+  // same environment without a migration step.
+  const adoptionForAgent = (agent) => {
+    if (typeof options.bindingAdoptionForAgent !== 'function' || agent === undefined || agent === null) return undefined
+    return options.bindingAdoptionForAgent(agent)
+  }
+  /**
+   * Supply minus this session's declines. The catalog decides which entries
+   * exist; adoption only withdraws one, so no entry can appear here that the
+   * global configuration did not supply.
+   */
+  const adoptedCatalog = (snapshot, adoption) => {
+    const declined = declinedBindingEntries(adoption)
+    if (declined.size === 0) return snapshot
+    const kept = snapshot.entries.filter(entry => !declined.has(entry.id))
+    if (kept.length === snapshot.entries.length) return snapshot
+    return selectUserBindingsSnapshot(snapshot, kept.map(entry => entry.id))
+  }
+  const recordAdoption = (agent, adoption) => {
+    const session = agent?.session
+    if (session === undefined || typeof session.append !== 'function') {
+      throw new Error('binding adoption requires a live session')
+    }
+    if (session.append('user/message', bindingAdoptionMessage(adoption), { surfaceOp: 'append' }) === undefined) {
+      throw new Error('the session did not record the binding adoption decision')
+    }
+    return { kind: 'success', text: adoptionReceipt(adoption) }
+  }
+  const stateAdoption = async (agent, command) => {
+    requireEnabled()
+    // Status and validation read the full supplied catalog: an adopted subset
+    // cannot prove what it was derived from.
+    const catalog = await store.snapshot()
+    const current = adoptionForAgent(agent)
+    if (command.kind === 'status') return { kind: 'success', text: adoptionStatusText(catalog, current) }
+    if (command.kind === 'reset') return recordAdoption(agent, clearedBindingAdoption())
+    if (!catalog.entries.some(entry => entry.id === command.id)) {
+      throw new Error(`the global binding catalog does not supply entry ${JSON.stringify(command.id)}; this session can decline a supplied entry but cannot add or revive one`)
+    }
+    return recordAdoption(agent, withBindingAdoption(current, command.id, command.kind === 'use'))
+  }
   const draftFor = (capability) => {
     if (typeof capability !== 'string' || capability === '') {
       throw new TypeError('draft capability must be a non-empty string')
@@ -482,7 +566,7 @@ export function createUserBindingsOwner(ctx, options = {}) {
     const requireCurrentAgent = () => {
       if (!agentIsCurrent(agent, sessionId, agentGeneration)
         || commandRegistrations.get(sessionId)?.agent !== agent
-        || ctx.tools.get('run_code', agent) === undefined) {
+        || !sessionExecutionAvailable(ctx.tools, agent)) {
         throw new Error('this binding authoring Agent is no longer active')
       }
     }
@@ -617,6 +701,14 @@ export function createUserBindingsOwner(ctx, options = {}) {
 
   const commandHandler = async ({ agent, rawInput, signal, commandId }) => {
     signal?.throwIfAborted?.()
+    const adoption = parseAdoptionCommand(rawInput)
+    if (adoption !== undefined) {
+      try {
+        return await stateAdoption(agent, adoption)
+      } catch (error) {
+        return { kind: 'error', text: error instanceof Error ? error.message : String(error) }
+      }
+    }
     const command = parseAuthoringCommand(rawInput)
     if (command.kind === 'help') return { kind: 'error', text: `Usage: ${COMMAND_USAGE}` }
     try {
@@ -660,14 +752,14 @@ export function createUserBindingsOwner(ctx, options = {}) {
         // still claiming one.
         if (disposed || !enabled || lifecycleGeneration !== registration.generation
           || !agentIsCurrent(agent, sessionId, agentGeneration)
-          || ctx.tools.get('run_code', agent) === undefined
+          || !sessionExecutionAvailable(ctx.tools, agent)
           || commandRegistrations.get(sessionId) !== registration) {
           throw new Error('Global User Bindings binding command registration is no longer eligible')
         }
         registerOwned(commandCtx, commandCtx.commands, {
           name: 'binding',
-          description: 'Create or revise a Global User Binding draft with the current agent',
-          input: { hint: 'new <requirement> | edit <id> <requirement>' },
+          description: 'Author a Global User Binding draft, or state which supplied entries this session uses',
+          input: { hint: 'new <requirement> | edit <id> <requirement> | status | use <id> | skip <id> | reset' },
           handler: commandHandler,
         }, 'binding command')
       })
@@ -712,13 +804,13 @@ export function createUserBindingsOwner(ctx, options = {}) {
     }
     if (!agentIsCurrent(agent, sessionId, agentGeneration)) return
     const eligible = enabled && draftProjectionAvailable && !disposed
-      && ctx.tools.get('run_code', agent) !== undefined
+      && sessionExecutionAvailable(ctx.tools, agent)
     const current = commandRegistrations.get(sessionId)
     if (eligible && current?.agent === agent) return
     if (current !== undefined) await removeCommandFor(sessionId, current)
     if (!agentIsCurrent(agent, sessionId, agentGeneration)) return
     const stillEligible = enabled && draftProjectionAvailable && !disposed
-      && ctx.tools.get('run_code', agent) !== undefined
+      && sessionExecutionAvailable(ctx.tools, agent)
     if (stillEligible) {
       registerCommandFor(agent)
       return
@@ -918,6 +1010,17 @@ export function createUserBindingsOwner(ctx, options = {}) {
     async snapshot() {
       return enabled ? store.snapshot() : undefined
     },
+    /**
+     * The catalog entries one session's worker should receive. Without a stated
+     * adoption this is exactly the supplied catalog, so 0.5.2 behavior is
+     * unchanged for every session that never declines an entry.
+     */
+    async snapshotForAgent(agent) {
+      if (!enabled) return undefined
+      const snapshot = await store.snapshot()
+      const adoption = adoptionForAgent(agent)
+      return adoption === undefined ? snapshot : adoptedCatalog(snapshot, adoption)
+    },
     async list() {
       requireEnabled()
       return store.list()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ptc-plus",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "icon": "assets/ptc-plus-icon.svg",
   "description": "A session-bound agent-native REPL for DeepSeek Harness PTC mode.",
   "type": "module",
@@ -69,9 +69,15 @@
     "@deepseek-ai/dsh-skill-filesystem": "*",
     "@deepseek-ai/dsh-spill-policy": "*",
     "@deepseek-ai/dsh-tool-cordis": "*",
+    "@deepseek-ai/dsh-tool-executor-ptc": "*",
     "@deepseek-ai/dsh-tools": "*",
     "@deepseek-ai/dsh-typert-protocol": "*"
   },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-tool-executor-ptc": {
+      "optional": true
+    }
+  },
   "scripts": {
     "build": "node scripts/client-bundle.mjs build && node scripts/compiler-bundle.mjs build",
     "build:check": "node scripts/client-bundle.mjs check && node scripts/compiler-bundle.mjs check",
@@ -88,8 +94,9 @@
     "test:client:fallback": "node scripts/client-fallback-smoke.mjs",
     "test:client:layout": "node scripts/client-binding-layout.mjs",
     "readme:screenshots": "node scripts/readme-screenshots.mjs",
-    "host:baseline:update": "node scripts/dsh-dependency-baseline.mjs update",
-    "host:baseline:verify": "node scripts/dsh-dependency-baseline.mjs verify",
+    "host:channels:update": "node scripts/host-channel-manifest.mjs update",
+    "host:channels:graph": "node scripts/host-channel-manifest.mjs graph",
+    "host:channels:verify": "node scripts/host-channel-manifest.mjs verify",
     "test:host-contract": "node scripts/dsh-host-contract-suite.mjs",
     "prepack": "npm run build:check",
     "hooks:install": "node scripts/review-findings.mjs install-hook",
@@ -109,14 +116,15 @@
     "test:backend": "node scripts/test-suite-files.mjs",
     "test:backend:fast": "node scripts/test-suite-files.mjs --fast",
     "test:ci:runtime": "node --test --test-concurrency=1 test/package-contract.test.js test/compiler-platform.test.js test/direct-surface-policy.test.js test/isolated-entrance.test.js test/plugin-native-call-transport.test.js",
-    "verify": "npm run review:validate && npm run host:baseline:verify && npm run semantic:check && npm run build:check && node --check index.js && node --check internal/kernel-worker.js && node --check scripts/migrate-session-log.mjs && node --check scripts/expensive-headless-acceptance.mjs && node --check scripts/ab-headless-trajectories.mjs && node scripts/deterministic-test-groups.mjs",
-    "verify:check": "npm run review:validate && npm run host:baseline:verify && npm run semantic:check && npm run build:check && node --check index.js && node --check internal/kernel-worker.js && node scripts/deterministic-test-groups.mjs --check",
-    "verify:ci": "npm run review:validate && npm run host:baseline:verify && npm run semantic:check && npm run build:check && node --check index.js && node --check internal/kernel-worker.js && node --check scripts/migrate-session-log.mjs && node scripts/deterministic-test-groups.mjs --ci",
+    "verify": "npm run review:validate && npm run host:channels:verify && npm run host:shape-check && npm run semantic:check && npm run build:check && node --check index.js && node --check internal/kernel-worker.js && node --check scripts/migrate-session-log.mjs && node --check scripts/expensive-headless-acceptance.mjs && node --check scripts/ab-headless-trajectories.mjs && node scripts/deterministic-test-groups.mjs",
+    "verify:check": "npm run review:validate && npm run host:channels:verify && npm run host:shape-check && npm run semantic:check && npm run build:check && node --check index.js && node --check internal/kernel-worker.js && node scripts/deterministic-test-groups.mjs --check",
+    "verify:ci": "npm run review:validate && npm run host:channels:verify && npm run host:shape-check && npm run semantic:check && npm run build:check && node --check index.js && node --check internal/kernel-worker.js && node --check scripts/migrate-session-log.mjs && node scripts/deterministic-test-groups.mjs --ci",
     "check": "node scripts/review-findings.mjs check",
     "verify:docs": "node scripts/review-findings.mjs docs",
     "test:expensive": "node scripts/expensive-headless-acceptance.mjs",
     "test:ab": "node scripts/ab-headless-trajectories.mjs",
-    "test:package:consumer": "node scripts/npm-consumer-smoke.mjs"
+    "test:package:consumer": "node scripts/npm-consumer-smoke.mjs",
+    "host:shape-check": "node scripts/check-host-version-literals.mjs"
   },
   "keywords": [
     "deepseek-harness",

package/src/client-capabilities-view.js

@@ -9,10 +9,28 @@ import {
   accountPromptText, parsePromptTextDocument, resolvePromptText,
 } from '../internal/prompt-text.js'
 
+/**
+ * One capability, three separate facts, in the reader's language. Saved,
+ * delivered and usable are different questions, so a reader must be able to see
+ * which one failed instead of reading one blanket "applied".
+ */
+export function capabilityProofCopy(t, proof) {
+  const delivery = ['delivered', 'pending', 'absent'].includes(proof?.delivery) ? proof.delivery : undefined
+  const usability = ['proven', 'unproven'].includes(proof?.usability) ? proof.usability : undefined
+  if (delivery === undefined || usability === undefined) return t('capabilities.quick.unknown')
+  return t('capabilities.proof.line', {
+    saved: t(proof.saved === true ? 'capabilities.proof.saved.yes' : 'capabilities.proof.saved.no'),
+    delivery: t(`capabilities.proof.delivery.${delivery}`),
+    usability: t(`capabilities.proof.usability.${usability}`),
+  })
+}
+
 export function capabilityCommandText(t, text) {
   if (text?.key) return t(text.key, text.params)
   const receipt = readCapabilityCommandReceipt(text)
-  return receipt ? t(`capabilities.receipt.${receipt.state}`, { session: receipt.sessionId, error: receipt.error ?? '' }) : text
+  if (!receipt) return text
+  const line = t(`capabilities.receipt.${receipt.state}`, { session: receipt.sessionId, error: receipt.error ?? '' })
+  return receipt.proof === undefined ? line : `${line} ${capabilityProofCopy(t, receipt.proof)}`
 }
 
 // Host-owned context the model sees in PTC mode. The plugin never receives the host's
@@ -115,9 +133,14 @@ export function createCapabilityCommandCard(React) {
           : node.outcome ? (typeof text === 'string' && !text.trim() ? undefined : capabilityCommandText(t, text))
             ?? t(node.outcome.kind === 'error' ? 'capabilities.commandFailed' : 'capabilities.refreshAcknowledged')
             : t('capabilities.refreshing')
+      // A command that names one capability carries that capability's three
+      // facts; the notice states them beside its session outcome so "saved"
+      // cannot be read as "delivered" or "usable".
+      const notice = receipt?.proof === undefined || outcome === undefined
+        ? outcome : `${outcome} ${capabilityProofCopy(t, receipt.proof)}`
       return h('p', { className: 'ptcPlusCapabilityCommandNotice',
         role: node.outcome?.kind === 'error' ? 'alert' : 'status',
-        'data-state': node.outcome?.kind ?? 'pending' }, outcome)
+        'data-state': node.outcome?.kind ?? 'pending' }, notice)
     }
     let json
     if (typeof text === 'string') {
@@ -1427,6 +1450,10 @@ export function createCapabilityRefreshView(React, commands) {
 export function createSessionCapabilityControlsView(React, { commands, Modal, Select, inspectSessionCatalog }) {
   const h = React.createElement
   const emptyDrafts = () => ({})
+  // The panel reports the three capability facts only where it holds evidence:
+  // the receipts its own commands returned. A catalogue row says what the plan
+  // will do; it cannot say a cell reached the capability.
+  const emptyProofs = () => ({})
   return function SessionCapabilityControls({ sessionId, open, enabled, t, onClose }) {
     const source = React.useMemo(() => commands.source(sessionId), [sessionId])
     const available = React.useSyncExternalStore(source.subscribe, source.getSnapshot)
@@ -1448,6 +1475,7 @@ export function createSessionCapabilityControlsView(React, { commands, Modal, Se
     const [sort, setSort] = React.useState(null)
     const [focusDimension, setFocusDimension] = React.useState(null)
     const [status, setStatus] = React.useState(null)
+    const [proofs, setProofs] = React.useState(emptyProofs)
     const [pending, setPending] = React.useState(false)
     const request = React.useRef(null)
     const applying = React.useRef(false)
@@ -1480,6 +1508,7 @@ export function createSessionCapabilityControlsView(React, { commands, Modal, Se
       setPane('list')
       setFocusDimension(null)
       setStatus(null)
+      setProofs(emptyProofs())
       setPending(false)
       setError(null)
     }, [sessionId])
@@ -1646,15 +1675,20 @@ export function createSessionCapabilityControlsView(React, { commands, Modal, Se
         let pendingCount = 0
         let failure = null
         let savedOnly = null
+        const observed = {}
         for (const [id, selection, dimension] of staged) {
           if (controller.signal.aborted) break
+          const line = `set ${targetScope} ${encodeURIComponent(id)} ${dimension ? dimension + ' ' : ''}${selection}`
           try {
-            const result = await commands.run(sessionId, `set ${targetScope} ${encodeURIComponent(id)} ${dimension ? dimension + ' ' : ''}${selection}`, controller.signal)
+            const result = await commands.run(sessionId, line, controller.signal)
             const receipt = readCapabilityCommandReceipt(result.text)
             if (!receipt || receipt.sessionId !== sessionId || !['recorded', 'pending'].includes(receipt.state)) {
               throw new Error(receipt ? capabilityCommandText(t, result.text) : t('capabilities.quick.unknownReceipt'))
             }
             if (receipt?.state === 'pending') pendingCount += 1
+            // A receipt that names the capability carries the only proof this
+            // panel can hold: what the save did and did not establish.
+            if (receipt.proof !== undefined) observed[receipt.proof.id] = { proof: receipt.proof, command: `/capabilities ${line}` }
             completed += 1
           } catch (cause) {
             failure = String(cause?.message ?? cause)
@@ -1663,6 +1697,7 @@ export function createSessionCapabilityControlsView(React, { commands, Modal, Se
             break
           }
         }
+        if (mounted.current && Object.keys(observed).length) setProofs(current => ({ ...current, ...observed }))
         if (request.current !== controller || controller.signal.aborted || !mounted.current) return
         const refreshed = await load(controller.signal)
         if (request.current !== controller || controller.signal.aborted || !mounted.current) return
@@ -1900,6 +1935,13 @@ export function createSessionCapabilityControlsView(React, { commands, Modal, Se
             h('dt', null, t('capabilities.quick.effective')), h('dd', null, statusLabel(selected.effective)),
             selected.sourceDimensions ? h(React.Fragment, null, h('dt', null, t('capabilities.policy.frozenSource')), h('dd', null, dimensionFacts(selected.sourceDimensions))) : null,
             selected.effectiveDimensions ? h(React.Fragment, null, h('dt', null, t('capabilities.policy.effectiveDimensions')), h('dd', null, dimensionFacts(selected.effectiveDimensions))) : null),
+          h('div', { className: 'ptcPlusCapabilityProof', 'data-capability-proof': selected.id },
+            h('h4', null, t('capabilities.proof.title')),
+            proofs[selected.id]
+              ? h(React.Fragment, null,
+                h('p', { className: 'ptcPlusDetail', role: 'status' }, capabilityProofCopy(t, proofs[selected.id].proof)),
+                h('small', null, t('capabilities.proof.observed', { command: proofs[selected.id].command })))
+              : h('p', { className: 'ptcPlusDetail' }, t('capabilities.proof.unobserved'))),
           selected.source?.kind === 'mcp' && selected.category !== 'server'
             ? (() => {
               const server = catalog.find(entry => entry.category === 'server' && entry.source?.server === selected.source.server)