dsh-ptc-plus 0.5.0 → 0.5.2

package/internal/session-state.js

@@ -94,6 +94,33 @@ export class BindingCatalog {
     }
   }
 
+  /**
+   * Catalog after installing recorded values.
+   *
+   * A restored node is not compiled: its source may be dead (it can reference a
+   * binding a recorded rewind ended), so there is no preparation to take
+   * declarations from. The journal records the names and values but not their
+   * declaration kind, so a restored binding is catalogued as reassignable. That is
+   * deliberately permissive: refusing a later `let`-style redeclaration would break
+   * continuation, while accepting one only widens what the session may do with a
+   * binding whose original declaration the log cannot describe.
+   */
+  restore(names) {
+    if (!Array.isArray(names) || names.length === 0) return this
+    const entries = new Map(this.#entries)
+    for (const name of names) {
+      if (typeof name !== 'string' || entries.has(name)) continue
+      entries.set(name, { kind: 'let', writable: true })
+    }
+    return new BindingCatalog({
+      entries,
+      namespaces: this.#namespaces,
+      userBindingAncestry: this.#userBindingAncestry,
+      rootCandidates: this.#rootCandidates,
+      dynamicOrigins: this.#dynamicOrigins,
+    })
+  }
+
   advance(prepared, source = undefined, committedRedeclarations = undefined, rootBindingFacts = undefined) {
     const semantics = normalizeLanguageSemantics(prepared.languageSemantics ?? LEGACY_LANGUAGE_SEMANTICS)
     if (semantics === LEGACY_LANGUAGE_SEMANTICS) {

package/internal/stateful-root-compiler.js

@@ -1,4 +1,5 @@
 /** Compile each cell into a private native frame backed by session identities. */
+import { boundedLiteralEvidence } from './bounded-literal.js'
 import { adaptRootModuleImports } from './managed-module-operations.js'
 import { parse } from '@babel/parser'
 import { createHash } from 'node:crypto'
@@ -321,11 +322,21 @@ export function compileStatefulRoot(program, {
       return remember(text, [{ generatedStart: 6, generatedEnd: 6 + source.length,
         originalStart: original.start, originalEnd: original.end }])
     }
+    const firstDeclaration = declarations.length
     const target = record(names[0], 'variable', node, bindings[0], `:${declarator.start}`)
     for (const binding of bindings.slice(1)) {
       record(binding.name, 'variable', node, binding, `:${declarator.start}`)
       declarations.at(-1).commitDependency = target
     }
+    // A single `const name = { … }` initializer proves its own size from the
+    // source, so settlement may record that value without walking an object the
+    // codec cannot size. A destructuring pattern has no one initializer to prove.
+    if (declarator.id.type === 'Identifier' && supplied === undefined && declarator.init !== null) {
+      const evidence = boundedLiteralEvidence(declarator.init)
+      if (evidence !== undefined) {
+        for (const declaration of declarations.slice(firstDeclaration)) declaration.boundedLiteral = evidence
+      }
+    }
     if (declarator.init === null && supplied === undefined) {
       return emptyCompletion(`${runtime}.declare(${JSON.stringify(names[0])}, ${JSON.stringify(target)})`)
     }

package/internal/stateful-root-runtime.js

@@ -333,6 +333,23 @@ export function createStatefulRootRuntime({ readAmbient, typeofAmbient, writeAmb
       const entry = mapGet(entries, name)
       return entry?.source === 'local' && entry.object !== true && entry.read === undefined ? { value: entry.value } : undefined
     },
+    /**
+     * Install a recorded binding without running the cell that produced it.
+     *
+     * A volatile cell cannot be replayed: re-executing its source would
+     * redispatch the ambient effects that made it volatile. Recovery therefore
+     * installs the value the journal recorded, as the committed local
+     * declaration the original cell's own commit produced. Returns false when
+     * the store cannot publish a session identity for the name, so the caller
+     * reports that binding instead of claiming it was restored.
+     */
+    restoreValue(name, value) {
+      const entry = storeValue(name, value, { declaration: true })
+      if (entry === undefined) return false
+      publish(name, () => read(name), next => write(name, next))
+      changed(name, 'local')
+      return true
+    },
     has: name => mapHas(entries, name) && mapGet(entries, name).object !== true && mapGet(entries, name).deleted !== true,
     facts() {
       const facts = []

package/internal/user-binding-console.js

@@ -55,6 +55,12 @@ export class UserBindingConsole {
   async reconfigure(options) {
     // Reconfiguration releases the current environments; the owner stays usable so
     // a later run can start again.
+    if (this.options.workerReclaimMs !== options.workerReclaimMs && Number.isSafeInteger(options.workerReclaimMs)) {
+      // A bound change needs no new worker: the close path reads the transport.
+      for (const environment of this.environments.values()) {
+        environment.worker.reclaimBoundMs = options.workerReclaimMs
+      }
+    }
     if (['maxWallMs', 'maxOutputBytes', 'maxOldGenerationSizeMb'].some(key => this.options[key] !== options[key])) {
       for (const capability of [...this.environments.keys()]) this.release(capability, 'reconfigured')
       const failures = await this.owner.releaseAll()
@@ -88,6 +94,7 @@ export class UserBindingConsole {
         workerData: { source, cwd: this.options.cwd, maxOutputBytes: this.options.maxOutputBytes },
         env: normalizeWorkerEnvironment(process.env),
         resourceLimits: { maxOldGenerationSizeMb: this.options.maxOldGenerationSizeMb },
+        reclaimBoundMs: this.options.workerReclaimMs,
         protocol: 'parent-port',
       })
       const worker = started.transport

package/internal/user-bindings-owner.js

@@ -1,5 +1,5 @@
 import { PTC_MESSAGE_SOURCE_KIND } from './message-sources.js'
-import { bindingToggleMessage, readBindingToggle } from './binding-toggle-receipt.js'
+import { bindingToggleMessage } from './binding-toggle-receipt.js'
 import { RPC_CONTRACTS } from './rpc-contract.js'
 import { randomUUID } from 'node:crypto'
 import { dirname } from 'node:path'
@@ -111,6 +111,7 @@ function runCandidate(source, invocation, options, signal, owner) {
       workerData: { source, invocation, valueLimits: options.valueLimits, cwd: options.cwd },
       env: normalizeWorkerEnvironment(process.env),
       resourceLimits: { maxOldGenerationSizeMb: options.maxOldGenerationSizeMb },
+      reclaimBoundMs: options.workerReclaimMs,
     })
     const worker = started.transport
     const outputLimitError = () => Object.assign(
@@ -183,10 +184,10 @@ export function createUserBindingsOwner(ctx, options = {}) {
     maxWallMs: options.maxWallMs,
     maxOutputBytes: options.maxOutputBytes,
     maxOldGenerationSizeMb: options.maxOldGenerationSizeMb,
+    workerReclaimMs: options.workerReclaimMs,
     valueLimits: options.valueLimits,
   }
   let disposed = false
-  const pendingConfigurationReceipts = new WeakMap()
   const codeConsole = new UserBindingConsole(currentOptions)
   const commandRegistrations = new Map()
   const sessionAgents = new Map()
@@ -387,15 +388,11 @@ export function createUserBindingsOwner(ctx, options = {}) {
     const sessions = new Set((ctx.agents?.list?.() ?? []).map(agent => agent.session).filter(Boolean))
     for (const session of sessions) {
       try {
+        // Before the first accepted step these are initial settings, not changes
+        // to an environment the model has received. The catalog owns first delivery.
+        if (session.deriveMessages()[0]?.role !== 'system') continue
         const message = createUserMessage(bindingToggleMessage(entry, next.revision))
-        // The Host alone establishes the first system head. Before that accepted
-        // boundary, keep UI configuration facts pending without waking the Agent.
-        if (session.deriveMessages()[0]?.role === 'system') session.append('user/message', message, { surfaceOp: 'append' })
-        else {
-          const pending = pendingConfigurationReceipts.get(session) ?? []
-          pending.push(message)
-          pendingConfigurationReceipts.set(session, pending)
-        }
+        session.append('user/message', message, { surfaceOp: 'append' })
       } catch (error) { reportContainedFailure('ptc-plus: binding configuration saved but its session receipt could not be appended', error) }
     }
     return next
@@ -916,23 +913,6 @@ export function createUserBindingsOwner(ctx, options = {}) {
   mountAuthoring()
 
   return Object.freeze({
-    committedEvent(session, event) {
-      if (event.type !== 'user/message' || !readBindingToggle(event.data)) return
-      const pending = pendingConfigurationReceipts.get(session)
-      if (pending) pendingConfigurationReceipts.set(session, pending.filter(message => message.id !== event.data.id))
-    },
-    async preStep(payload, next) {
-      const decision = await next()
-      if (disposed || decision?.kind !== 'enter' || payload.signal?.aborted || payload.agent?.signal?.aborted) return decision
-      const session = payload.agent?.session
-      const pending = pendingConfigurationReceipts.get(session)
-      if (!pending?.length) return decision
-      const visible = new Set(session.deriveMessages().map(message => message.id))
-      const remaining = pending.filter(message => !visible.has(message.id))
-      pendingConfigurationReceipts.set(session, remaining)
-      const proposed = new Set((decision.messages ?? []).map(message => message.id))
-      return { ...decision, messages: [...(decision.messages ?? []), ...remaining.filter(message => !proposed.has(message.id))] }
-    },
     path: store.filename,
     cwd: bindingsCwd,
     async snapshot() {
@@ -997,6 +977,7 @@ export function createUserBindingsOwner(ctx, options = {}) {
         maxWallMs: nextConfig.maxWallMs,
         maxOutputBytes: nextConfig.maxOutputBytes,
         maxOldGenerationSizeMb: nextConfig.maxOldGenerationSizeMb,
+        workerReclaimMs: nextConfig.workerReclaimMs,
         valueLimits: valueLimitsFromConfig(nextConfig),
       }
       if (nextEnabled === previousEnabled) {

package/internal/user-bindings.js

@@ -268,7 +268,7 @@ export function userBindingsDeclaration(snapshot) {
   return normalized.entries.map(entry => entry.declaration).join('\n\n')
 }
 
-export function userBindingsConfiguredContext(snapshot) {
+export function userBindingsConfiguredContext(snapshot, { entryLabel = 'Binding' } = {}) {
   const entries = normalizeUserBindingsSnapshot(snapshot).entries
     .filter(entry => {
       const { includeDeclaration, instructions } = bindingModelPreferences(entry.modelContext)
@@ -279,7 +279,7 @@ export function userBindingsConfiguredContext(snapshot) {
   const content = entries.map(entry => {
     const { includeDeclaration, instructions } = bindingModelPreferences(entry.modelContext)
     return [
-      `Binding: ${entry.name}`,
+      `${entryLabel}: ${entry.name}`,
       instructions,
       includeDeclaration ? `\`\`\`ts\n${entry.declaration}\n\`\`\`` : '',
     ].filter(Boolean).join('\n\n')

package/internal/validated-parse-repair.js

@@ -31,7 +31,7 @@ function startsInsideSurrogatePair(source, index) {
   return current >= 0xdc00 && current <= 0xdfff && previous >= 0xd800 && previous <= 0xdbff
 }
 
-function boundedUniqueSuffix(source) {
+export function boundedUniqueSuffix(source) {
   const first = Math.max(0, source.length - MAX_PARSE_REPAIR_ANCHOR_CODE_UNITS)
   for (let start = source.length - 1; start >= first; start -= 1) {
     if (startsInsideSurrogatePair(source, start)) continue
@@ -81,6 +81,11 @@ export function validatedEofClosureRepair({ source, position, prepare, targetCal
   const candidate = candidates[0]
   return Object.freeze({
     ...candidate,
+    // The diagnostic names the target cell instead of embedding the whole
+    // invocation: the JSON form is hundreds of characters the model has to copy
+    // before it can act, while the delimiter and the target are the two facts it
+    // needs.
+    targetCallSeq,
     invocation: renderInvocation(candidate.arguments),
   })
 }

package/internal/worker-client.js

@@ -1,4 +1,4 @@
-import { mkdtemp, rm } from 'node:fs/promises'
+import { mkdir, mkdtemp, rm } from 'node:fs/promises'
 import { randomBytes } from 'node:crypto'
 import { tmpdir } from 'node:os'
 import { isAbsolute, join } from 'node:path'
@@ -46,7 +46,15 @@ export class WorkerClient {
     return lastLine === undefined ? undefined : lastLine.slice(0, 300)
   }
 
-  async ensure(maxOldGenerationSizeMb) {
+  /**
+   * Start the session worker once and reuse it.
+   *
+   * `bounds` carries the startup bound for a worker that does not exist yet and
+   * the close bound this worker starts with; a later close reads the bound the
+   * owning kernel sets from its current configuration. It may be a getter, which
+   * is read after the scratch wait because a settings change can land there.
+   */
+  async ensure(maxOldGenerationSizeMb, bounds = {}) {
     if (this.pendingOutputFailure !== undefined) {
       const message = this.pendingOutputFailure
       this.pendingOutputFailure = undefined
@@ -61,7 +69,14 @@ export class WorkerClient {
       if (!isAbsolute(scratchRoot)) {
         throw new Error(`ptc-plus: host temporary directory must be absolute, got ${JSON.stringify(scratchRoot)}`)
       }
-      this.scratchReady = mkdtemp(join(scratchRoot, 'dsh-ptc-plus-'))
+      this.scratchReady = mkdtemp(join(scratchRoot, 'dsh-ptc-plus-')).catch(async error => {
+        // A host that points TMPDIR at a directory it has not created yet (macOS CI)
+        // fails mkdtemp with ENOENT; create the root once and retry instead of
+        // failing the cell with a worker-exit error.
+        if (error?.code !== 'ENOENT') throw error
+        await mkdir(scratchRoot, { recursive: true })
+        return mkdtemp(join(scratchRoot, 'dsh-ptc-plus-'))
+      })
     }
     this.workerLimit = maxOldGenerationSizeMb
     let scratchDirectory
@@ -79,13 +94,21 @@ export class WorkerClient {
     /* c8 ignore next */
     if (this.worker !== undefined) return this.workerReady
     const environment = normalizeWorkerEnvironment(process.env)
+    // A settings change can land while the scratch directory is being created,
+    // so the bounds are read here rather than at the call.
+    const resolvedBounds = typeof bounds === 'function' ? bounds() : bounds
     let worker
     try {
       const started = this.owner.start({
         helper: KERNEL_HELPER,
         entry: this.workerUrl,
-        workerData: { cwd: this.cwd, compilerCache: this.compilerCache?.() },
+        workerData: {
+          cwd: this.cwd,
+          compilerCache: this.compilerCache?.(),
+          startupProbeMs: resolvedBounds.startupProbeMs,
+        },
         resourceLimits: { maxOldGenerationSizeMb: this.workerLimit },
+        reclaimBoundMs: resolvedBounds.reclaimBoundMs,
         env: {
           ...environment,
           TEMP: scratchDirectory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-ptc-plus",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "icon": "assets/ptc-plus-icon.svg",
   "description": "A session-bound agent-native REPL for DeepSeek Harness PTC mode.",
   "type": "module",
@@ -42,7 +42,8 @@
     "LICENSE"
   ],
   "engines": {
-    "node": "^22.19.0 || >=24.0.0"
+    "node": "^22.19.0 || >=24.0.0",
+    "dsh": "*"
   },
   "allowScripts": {
     "esbuild": false
@@ -106,8 +107,10 @@
     "coverage:focus": "node scripts/coverage.mjs --focus",
     "test:backend:focus": "node scripts/test-suite-files.mjs --focus",
     "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",
     "check": "node scripts/review-findings.mjs check",
     "verify:docs": "node scripts/review-findings.mjs docs",

package/src/client-activity.js

@@ -249,12 +249,30 @@ function isValidModuleSemantics(value, version) {
     && (legacy || IMPORT_EXPRESSION_BOUNDARIES.has(value.importExpressionBoundary))
 }
 
+/**
+ * The retention window keeps everything recovery reads and replaces one payload
+ * with the digest of exactly the bytes it used to carry, so a recorded call keeps
+ * the Value V1 wire of its arguments or the digest of that wire, and a derived run
+ * keeps its source or the digest of that source. `normalizeCalls` and
+ * `normalizeDerivedRelation` accept exactly one of the two shapes and reject a
+ * record that claims both, so this boundary reports which shape it read.
+ */
+function payloadShape(value, textField, digestField, bytesField) {
+  if (Object.hasOwn(value, textField)) {
+    return Object.hasOwn(value, digestField) || Object.hasOwn(value, bytesField) ? undefined : 'text'
+  }
+  return typeof value[digestField] === 'string' && /^[a-f0-9]{64}$/u.test(value[digestField])
+    && isSafeSequence(value[bytesField]) ? 'digest' : undefined
+}
+
 function isValidCall(value) {
   if (!isRecord(value) || (value.ok !== true && value.ok !== false)) return false
   const fields = value.ok ? CALL_SUCCESS_FIELDS : CALL_ERROR_FIELDS
-  if (!hasExactFields(value, fields) || typeof value.global !== 'string'
-    || typeof value.member !== 'string' || !isValidValueWire(value.args)
+  const argsShape = payloadShape(value, 'args', 'argsDigest', 'argsBytes')
+  if (argsShape === undefined || !hasClosedFields(value, fields)
+    || typeof value.global !== 'string' || typeof value.member !== 'string'
     || !isSafeSequence(value.settle)) return false
+  if (argsShape === 'text' && !isValidValueWire(value.args)) return false
   return value.ok ? isValidValueWire(value.value) : typeof value.error === 'string'
 }
 
@@ -389,8 +407,10 @@ function isValidEditTarget(value) {
 
 function isValidDerivedRun(value) {
   try {
-    return hasExactFields(value, DERIVED_RUN_FIELDS)
-      && typeof value.code === 'string' && typeof value.description === 'string'
+    if (!isRecord(value) || !hasClosedFields(value, DERIVED_RUN_FIELDS)
+      || typeof value.description !== 'string') return false
+    const codeShape = payloadShape(value, 'code', 'codeDigest', 'codeBytes')
+    return codeShape === 'digest' || (codeShape === 'text' && typeof value.code === 'string')
   } catch {
     return false
   }
@@ -506,6 +526,7 @@ export function derivePtcToolView(block, toolName = undefined) {
     ? block.meta[GENERATED_RUN_CODE_DESCRIPTION_KEY]
     : undefined
   const description = (explicitDescription ?? generatedDescription)?.split(/\r?\n/, 1)[0] ?? ''
+  const descriptionGenerated = explicitDescription === undefined && generatedDescription !== undefined
   const output = settled ? resultText(block) : ''
   const state = !settled ? 'running'
     : block.error?.code === 'interrupted' ? 'stopped'
@@ -514,7 +535,7 @@ export function derivePtcToolView(block, toolName = undefined) {
     ? block.meta.dshPtcPlus
     : undefined
   if (journal === undefined) {
-    return Object.freeze({ state, description, code, output, ptc: false, features: Object.freeze([]) })
+    return Object.freeze({ state, description, descriptionGenerated, code, output, ptc: false, features: Object.freeze([]) })
   }
   const rewrites = isValidRewrites(block.meta.dshPtcPlusRewrites, journal)
     ? block.meta.dshPtcPlusRewrites
@@ -542,5 +563,5 @@ export function derivePtcToolView(block, toolName = undefined) {
       : undefined,
     ...operationFeatures(journal.operations),
   ])
-  return Object.freeze({ state, description, code, output, ptc: true, features: Object.freeze(features) })
+  return Object.freeze({ state, description, descriptionGenerated, code, output, ptc: true, features: Object.freeze(features) })
 }