martty 0.3.1 → 0.3.2-beta.1

package/README.md

@@ -15,9 +15,10 @@ x64. Requires Node.js 22.19+.
 
 > **Rename note:** the project and recommended npm package have moved from
 > DeepSeek Harness TUI / `martty` to **Martty** / `martty`.
-> The `dsh-tui` command, configuration, and session data remain compatible.
-> The production profile is now `martty`; legacy `tui` profiles
-> continue to work.
+> Configuration and session data remain compatible. The production profile is
+> now `martty`; legacy `tui` profiles continue to work. The `dsh-tui` command
+> is no longer installed by the `martty` package — see
+> [Migrating from DeepSeek Harness TUI / the scoped package](#migrating-from-deepseek-harness-tui--the-scoped-package).
 
 ## Global Agent TUI
 
@@ -49,8 +50,35 @@ missing profile and installs the TUI plus its ACP dependency; no global
 
 `martty` is the recommended package name. Starting with `0.2.13`, it and the
 legacy `martty` package are published by the same CI run
-with identical versions and artifacts. Existing scoped-package installs remain
-supported. To switch package names:
+with identical versions and artifacts. The scoped name is deprecated; switch
+package names with:
+
+```sh
+npm install --global martty
+```
+
+No removal is needed first, whatever state the legacy package is in —
+published versions of `martty` register `dsh-tui`
+(every version) and `martty` (0.2.14/0.2.20) global commands, and `npm link`ed
+legacy checkouts own the same names (a checkout of this repository links as
+`martty`, so it replaces — or is replaced by — an installed `martty` with no
+collision). The `martty` package declares only `martty-cli` so npm never
+refuses the install over a bin another package owns (`EEXIST`); a
+postinstall step then retires the stale `martty`/`dsh-tui`/`dsb` links that
+verifiably belonged to the legacy package (a third-party `dsh-tui` stays
+untouched), creates the `martty` command itself, and detaches the legacy
+package's bin declarations so a later `npm rm -g` can't take `martty` down
+with it. Removing `martty` afterwards is optional
+cleanup; `martty` warns at launch while it remains — on an interactive
+terminal the notice prints when the session exits, so the TUI cannot hide
+it. With `--ignore-scripts`
+the postinstall never runs — invoke `martty-cli` once (or `npx martty`) and
+the first launch finishes the migration itself. And after `npm rm -g
+martty`, the `martty` command left behind is a self-cleaning shim: invoking
+it once prints the reinstall hint and removes it — nothing dead is left
+in `<prefix>/bin`.
+
+Inside a `dsh` profile the same switch is:
 
 ```sh
 dsh plugin --profile tui remove martty
@@ -58,8 +86,13 @@ dsh plugin --profile martty add martty@latest
 ```
 
 The recommended profile changes from `tui` to `martty`; runtime behavior,
-config, and session data remain unchanged. `dsh-tui` and legacy `tui`
-profiles remain compatible.
+config, and session data remain unchanged. Legacy `tui` profiles remain
+compatible.
+
+The `martty` package no longer installs a `dsh-tui` command: the name
+collided with both the legacy package and an unrelated `dsh-tui` package on
+npm, which blocked `npm install --global martty` outright. If your fingers
+still type `dsh-tui`, alias it: `alias dsh-tui=martty`.
 
 The profile Host mounts the ACP plugin on Base, then starts a separate TUI
 Client process over standard ACP stdin/stdout. For standalone use, run
@@ -198,10 +231,11 @@ Creator-authored UI Presets and Theme Plugins preview as process-local dynamic
 Packages, then persist explicitly under `$MARTTY_HOME/plugins` through
 `tui_plugin_save`; `tui_plugin_read` resumes authoring after restart.
 
-`MARTTY_HOME` resolves explicitly first, then to `$DSH_HOME/.martty`, then to
-`~/.martty`. UI choices live in `$MARTTY_HOME/settings.json`. On first use,
-legacy Creator artifacts and settings are copied forward without deleting or
-overwriting the old files.
+`MARTTY_HOME` (or `OMA_HOME`) resolves explicitly first, then to
+`$DSH_HOME/.oma`, then to `~/.oma` — the configuration home Martty shares
+with Backchat. UI choices live in `$MARTTY_HOME/settings.json`. On first use,
+a legacy `.martty` directory and old Creator artifacts/settings are copied
+forward without deleting or overwriting the old files.
 
 Third-party TUI plugins remain ordinary installed packages. Their Host-side
 registrar contributes an absolute Client module entry to `tuiClientPlugins`;
@@ -228,7 +262,8 @@ npx --yes martty --demo
 
 The profile path remains recommended for an existing DSH installation that
 wants standard plugin management and a durable `martty` profile. `martty` is the
-primary command; `dsh-tui` remains a compatibility alias.
+primary command; the legacy `dsh-tui` command is no longer installed
+(`alias dsh-tui=martty` restores it).
 
 ## Highlights
 

package/bin/martty.js

@@ -9,10 +9,15 @@ import { resolveDependencyStack } from '../lib/agent.js'
 import { bootClient, parseClientArgv, painterArgs, uiSettingsPath } from '../lib/boot.js'
 import { runHarnessCommandAsync } from '../lib/harnesses.js'
 import { nativeBinary } from '../lib/spawn-tui.js'
+import { reportLaunchNotices, warnAboutLegacyPackage } from '../lib/install-migration.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const configuredBin = process.env.MARTTY_BIN || process.env.DSH_TUI_BIN
 
+const migrationNotices = []
+warnAboutLegacyPackage({ argv1: process.argv[1], write: (line) => migrationNotices.push(line) })
+reportLaunchNotices(migrationNotices)
+
 const argv = process.argv.slice(2)
 const wantDemoSkin = argv.includes('--demo-skin')
 const wantDemo = argv.includes('--demo')

package/lib/acp-agent-pool.js

@@ -10,6 +10,21 @@ const identity = spec => JSON.stringify([spec.command, spec.args ?? [],
 const namespace = spec => createHash('sha256').update(identity(spec)).digest('hex').slice(0, 24)
 const setupMethods = new Set(['session/new', 'session/load', 'session/resume'])
 
+/** `configOptions` array from a setup/set result or a `config_option_update`. */
+function readConfigOptions(value) {
+  const found = value?.configOptions ?? value?.config_options
+  return Array.isArray(found) ? found : undefined
+}
+
+/** `[configId, value]` pair for one option entry, or undefined when incomplete. */
+function optionEntry(option) {
+  if (option === null || typeof option !== 'object' || Array.isArray(option)) return undefined
+  const id = option.id ?? option.configId ?? option.config_id
+  const value = option.currentValue ?? option.current_value
+  if (typeof id !== 'string' || id.length === 0 || value === undefined) return undefined
+  return [id, structuredClone(value)]
+}
+
 export function createAgentPool(initial, { spawnAgent, resolveAgent, diagnosticError, timeoutMs = 20 * 60_000 }) {
   const input = new PassThrough()
   const output = new PassThrough()
@@ -30,10 +45,15 @@ export function createAgentPool(initial, { spawnAgent, resolveAgent, diagnosticE
   const writeAgent = (owner, value) => owner.handle.stdin.write(JSON.stringify(value) + '\n')
 
   function metadata(owner) {
+    // Send Now reads this snapshot per session (`steer_route`). Steering and
+    // MiniMax extensions are advertised on initialize `_meta`, which
+    // `agentCapabilities` does not carry.
+    const negotiated = owner.init?._meta
     return {
       id: owner.id,
       agentInfo: owner.init?.agentInfo,
       agentCapabilities: owner.init?.agentCapabilities ?? {},
+      ...(negotiated && typeof negotiated === 'object' ? { _meta: negotiated } : {}),
       authMethods: (owner.init?.authMethods ?? []).map(method => {
         const id = owner.id === 'h1' ? method.id : `${owner.id}:${method.id}`
         authMethods.set(id, { owner, id: method.id })
@@ -80,9 +100,17 @@ export function createAgentPool(initial, { spawnAgent, resolveAgent, diagnosticE
     }
     if (setupMethods.has(pending.method) && result && typeof result === 'object') {
       const raw = result.sessionId ?? pending.params?.sessionId
-      result = { ...result, sessionId: sessionId(owner, raw),
+      const bound = sessionId(owner, raw)
+      recordOptions(owner, bound, readConfigOptions(result))
+      result = { ...result, sessionId: bound,
         _meta: { ...result._meta, marttyConnection: { ...metadata(owner), cwd: pending.params?.cwd } } }
     }
+    if (pending.method === 'session/set_config_option' && result && typeof result === 'object') {
+      recordOptions(owner, pending.sessionKey, readConfigOptions(result)
+        ?? (pending.params?.configId !== undefined
+          ? [{ id: pending.params.configId, currentValue: pending.params.value }]
+          : undefined))
+    }
     if (pending.method === 'session/list' && Array.isArray(result?.sessions)) {
       result = { ...result, sessions: result.sessions.map(session => ({ ...session,
         sessionId: sessionId(owner, session.sessionId) })) }
@@ -95,17 +123,67 @@ export function createAgentPool(initial, { spawnAgent, resolveAgent, diagnosticE
     owner.failed = diagnosticError(error, owner.handle)
     for (const pending of owner.pending.values()) {
       if (pending.reject) pending.reject(owner.failed)
-      else write(response(owner, { error: { code: -32603, message: owner.failed.message } }, pending))
+      // `agentExited` marks the reply as pool-synthesized so the client can
+      // tell a dead child apart from a refusal the agent itself authored.
+      else write(response(owner, { error: { code: -32603, message: owner.failed.message, data: { agentExited: true } } }, pending))
     }
     owner.pending.clear()
   }
 
+  /**
+   * Track each session's config options and what the connection last applied.
+   * `session/set_config_option` is session-scoped in ACP, but agents like
+   * pi-acp apply it to global state — a newer session's defaults then leak
+   * into older sessions' turns. Remembering every session's own options lets
+   * `session/prompt` re-assert them first, so each turn runs the model and
+   * effort its session chose. New sessions never assert: they just record
+   * the defaults their setup snapshot reported.
+   * @param {*} owner
+   * @param {string} sessionKey - namespaced session id
+   * @param {Array|undefined} options - `configOptions` entries
+   */
+  function recordOptions(owner, sessionKey, options) {
+    if (typeof sessionKey !== 'string' || !options) return
+    const entries = options.map(optionEntry).filter(Boolean)
+    if (entries.length === 0) return
+    const config = owner.configs.get(sessionKey) ?? new Map()
+    for (const [id, value] of entries) {
+      config.set(id, value)
+      owner.applied.set(id, value)
+    }
+    owner.configs.set(sessionKey, config)
+  }
+
+  /**
+   * Re-apply a session's recorded config options the connection no longer
+   * holds — one `set_config_option` per drifted option, in recorded order.
+   * Best effort: a rejected assert must not block the turn it guarded.
+   */
+  async function applySessionConfig(owner, sessionKey) {
+    const config = owner.configs.get(sessionKey)
+    const bound = sessions.get(sessionKey)
+    if (!config || !bound || bound.owner !== owner || owner.failed || closed) return
+    for (const [configId, value] of config) {
+      if (JSON.stringify(owner.applied.get(configId)) === JSON.stringify(value)) continue
+      const id = `martty-config-${++nextRequest}`
+      const params = { sessionId: bound.raw, configId, value }
+      const result = await new Promise((resolve, reject) => {
+        owner.pending.set(id, { resolve, reject, method: 'session/set_config_option', params, sessionKey })
+        writeAgent(owner, { jsonrpc: '2.0', id, method: 'session/set_config_option', params })
+      }).catch(() => undefined)
+      if (result === undefined) break // assert failed — keep remaining options eligible
+      recordOptions(owner, sessionKey, readConfigOptions(result)
+        ?? [{ id: configId, currentValue: value }])
+    }
+  }
+
   function connection(spec) {
     const key = identity(spec)
     const existing = connections.get(key)
     if (existing && !existing.failed) return existing
     const owner = { id: `h${++nextConnection}`, namespace: namespace(spec), spec, handle: spawnAgent(spec),
-      sessions: new Map(), pending: new Map(), init: undefined, initializing: undefined, failed: undefined }
+      sessions: new Map(), pending: new Map(), init: undefined, initializing: undefined, failed: undefined,
+      configs: new Map(), applied: new Map(), configChain: Promise.resolve() }
     connections.set(key, owner)
     owner.handle.child.on('error', error => fail(owner, error))
     owner.handle.child.once('close', (code, signal) => fail(owner,
@@ -124,6 +202,10 @@ export function createAgentPool(initial, { spawnAgent, resolveAgent, diagnosticE
         return
       }
       const forwarded = { ...message, params: incomingParams(owner, message.params) }
+      if (message.method === 'session/update'
+        && forwarded.params?.update?.sessionUpdate === 'config_option_update') {
+        recordOptions(owner, forwarded.params.sessionId, readConfigOptions(forwarded.params.update))
+      }
       if (message.id !== undefined) {
         const id = `martty-agent-${++nextRequest}`
         callbacks.set(id, { owner, id: message.id })
@@ -214,6 +296,8 @@ export function createAgentPool(initial, { spawnAgent, resolveAgent, diagnosticE
       if (message.method.startsWith('_dsh/cordis/') && readCordisCapability(owner.init) === null) {
         throw new Error('agent has not advertised _dsh/cordis')
       }
+      const sessionKey = typeof params?.sessionId === 'string' ? params.sessionId
+        : typeof params?.session_id === 'string' ? params.session_id : undefined
       if (params && typeof params === 'object') {
         params = { ...params }
         for (const key of ['sessionId', 'session_id']) {
@@ -224,9 +308,22 @@ export function createAgentPool(initial, { spawnAgent, resolveAgent, diagnosticE
       const forwarded = { ...message, params }
       if (message.id !== undefined) {
         const id = `martty-client-${++nextRequest}`
-        owner.pending.set(id, { id: message.id, method: message.method, params })
+        owner.pending.set(id, { id: message.id, method: message.method, params, sessionKey })
         forwarded.id = id
       }
+      if (message.method === 'session/prompt' && sessionKey !== undefined) {
+        // The prompt lands on stdin only after its session's config options
+        // are re-asserted — the chain keeps cross-session order. Registering
+        // the pending reply above (never inside the chain) keeps close() able
+        // to settle it while an assert is still in flight.
+        owner.configChain = owner.configChain.then(async () => {
+          // Asserts resolve `undefined` on a failed set_config_option rather
+          // than rejecting, so this chain cannot drop the prompt.
+          await applySessionConfig(owner, sessionKey)
+          if (!closed && !owner.failed) writeAgent(owner, forwarded)
+        })
+        return
+      }
       writeAgent(owner, forwarded)
     } catch (error) {
       if (message.id !== undefined) {

package/lib/acp-client.js

@@ -105,7 +105,12 @@ export function apply(ctx, config = {}) {
     }
   }
   liveAgent = null
-  const service = createAgentPool(agent, { spawnAgent, resolveAgent, diagnosticError })
+  const noteAgentDiagnostics = installAgentWarnings(ctx)
+  const service = createAgentPool(agent, {
+    spawnAgent: (spec) => spawnAgent(spec, noteAgentDiagnostics),
+    resolveAgent,
+    diagnosticError,
+  })
   if (liveAgentExitHook !== null) process.removeListener('exit', liveAgentExitHook)
   liveAgentExitHook = () => service.close()
   process.once('exit', liveAgentExitHook)
@@ -113,14 +118,14 @@ export function apply(ctx, config = {}) {
   provide(ctx, service)
 }
 
-function spawnAgent(agent) {
+function spawnAgent(agent, onDiagnosticLine) {
   const child = spawn(agent.command, agent.args ?? [], {
     stdio: ['pipe', 'pipe', 'pipe'],
     env: harnessEnvironment(agent.env),
   })
   child.stdin.on('error', () => {})
   child.stdout.on('error', () => {})
-  const diagnostics = drainDiagnostics(child.stderr)
+  const diagnostics = drainDiagnostics(child.stderr, onDiagnosticLine)
   return {
     kind: 'spawn',
     command: agent.command,
@@ -133,14 +138,67 @@ function spawnAgent(agent) {
   }
 }
 
-function drainDiagnostics(stream) {
+/**
+ * Agent stderr lines worth surfacing in the input dock: warnings and
+ * failures the agent reports but survives (e.g. a bundle entry that did
+ * not activate) would otherwise be invisible until something exits.
+ */
+const DIAGNOSTIC_NOTICE = /warn|error|fail|did not activate|refus|incompat/i
+
+/**
+ * Feed warning-shaped agent stderr lines to a `conversation.input.dock`
+ * notice when the client tree carries `tuiSlots`. Returns undefined when the
+ * slot service is absent — stderr stays diagnostics-only as before.
+ */
+function installAgentWarnings(ctx) {
+  const slots = ctx.get?.('tuiSlots') ?? ctx.tuiSlots
+  if (typeof slots?.register !== 'function') return undefined
+  let controller
+  try {
+    controller = slots.register(
+      { name: 'conversation.input.dock', id: 'acp-agent-warnings' },
+      [],
+    )
+  } catch {
+    return undefined
+  }
+  const shown = []
+  return (line) => {
+    if (!DIAGNOSTIC_NOTICE.test(line)) return
+    shown.push(line.trimEnd())
+    if (shown.length > 4) shown.shift()
+    try {
+      controller.update([{ id: 'latest', kind: 'notice', level: 'warn', text: shown.join('\n') }])
+    } catch {
+      // The contribution is gone (disposed or re-mounted); stderr keeps
+      // flowing to the diagnostics tail regardless.
+    }
+  }
+}
+
+function drainDiagnostics(stream, onLine) {
   const limit = 8192
   let tail = Buffer.alloc(0)
+  let pending = ''
   let state = 'text'
+  const emitLines = (text, flush = false) => {
+    if (onLine === undefined) return
+    pending += text
+    for (let index = pending.indexOf('\n'); index !== -1; index = pending.indexOf('\n')) {
+      const line = pending.slice(0, index)
+      pending = pending.slice(index + 1)
+      if (line.trim() !== '') onLine(line)
+    }
+    if (flush && pending.trim() !== '') {
+      onLine(pending)
+      pending = ''
+    }
+  }
   // stderr is not a UI surface. Drain it even without a diagnostics consumer,
   // strip control strings incrementally, and never retain their payloads.
   stream.setEncoding('utf8')
   stream.on('error', () => {})
+  stream.on('close', () => emitLines('', true))
   stream.on('data', (chunk) => {
     let text = ''
     for (const char of chunk) {
@@ -174,6 +232,7 @@ function drainDiagnostics(stream) {
       text += char
     }
     if (text.length === 0) return
+    emitLines(text)
     const combined = Buffer.concat([tail, Buffer.from(text)])
     let start = Math.max(0, combined.length - limit)
     // Never split a UTF-8 code point or retain the large incoming allocation.

package/lib/acp-session-status.js

@@ -68,6 +68,7 @@ export function installAcpSessionStatus(ctx, options = {}) {
   let selectionKnown = false
   let connection = 'connecting'
   let server
+  let dshRuntime
   const auth = { status: undefined, method: undefined }
   let initializeId
   let authMethods = []
@@ -94,7 +95,7 @@ export function installAcpSessionStatus(ctx, options = {}) {
     const value = stateFor(sessionId)
     const { permissionPreset: _permissionPreset, sandboxMode: _sandboxMode,
       connectionFacts, ...visible } = value
-    return structuredClone({ connection, server, auth, ...connectionFacts, ...visible })
+    return structuredClone({ connection, server, dshRuntime, auth, ...connectionFacts, ...visible })
   }
 
   function publish() {
@@ -146,6 +147,7 @@ export function installAcpSessionStatus(ctx, options = {}) {
       selectionKnown = false
       connection = 'connecting'
       server = undefined
+      dshRuntime = undefined
       auth.status = undefined
       auth.method = undefined
       delete auth.message
@@ -197,13 +199,44 @@ export function installAcpSessionStatus(ctx, options = {}) {
     if (!object(message)) return
     if (message.id !== undefined && message.id === initializeId) {
       initializeId = undefined
-      connection = message.error === undefined ? 'attached' : 'failed'
       fallback.error = message.error?.message
       const result = object(message.result) ? message.result : undefined
       server = readString(result?.agentInfo, 'name')
+      // The runtime the ACP agent actually booted (dsh-acp advertises it in
+      // agentCapabilities._meta.dsh.runtime); shown in /status so users can
+      // tell bundled from host installs (issue #157).
+      dshRuntime = readDshRuntime(result?.agentCapabilities)
       const methods = Array.isArray(result?.authMethods) ? result.authMethods : []
       authMethods = methods
       // initialize advertises choices, not the credential used by this process.
+      if (message.error === undefined) {
+        connection = 'attached'
+      } else {
+        // An agent that answered `initialize` with a refusal is still
+        // attached — only a locally synthesized failure (the pool's
+        // agentExited marker for a dead child) counts as 'failed'. A refused
+        // handshake may advertise auth methods in its error data (the -32000
+        // convention): surface sign-in the same way the refused
+        // session/new path does. A refusal demanding auth while declaring
+        // no methods can never be remedied, so it stays 'failed'.
+        const offered = Array.isArray(message.error.data?.authMethods)
+          ? message.error.data.authMethods : []
+        if (message.error.data?.agentExited === true
+          || (isAuthRequired(message.error) && offered.length === 0)) {
+          connection = 'failed'
+        } else {
+          connection = 'refused'
+          if (isAuthRequired(message.error)) {
+            authMethods = offered
+            auth.status = 'needs sign-in'
+          }
+          // The refusal's own words are the diagnosis — our transport's
+          // appended "Agent stderr:" tail is unrelated launch noise.
+          if (typeof fallback.error === 'string') {
+            fallback.error = fallback.error.split('\nAgent stderr:')[0].trimEnd()
+          }
+        }
+      }
       publish()
       return
     }
@@ -230,7 +263,7 @@ export function installAcpSessionStatus(ctx, options = {}) {
       if (message.error !== undefined) {
         if (isAuthRequired(message.error)) auth.status = 'needs sign-in'
         else {
-          connection = 'failed'
+          connection = message.error.data?.agentExited === true ? 'failed' : 'refused'
           const value = stateFor(setup.sessionId, false)
           value.error = readString(message.error, 'message') ?? 'Session setup failed'
           value.state = 'idle'
@@ -416,6 +449,15 @@ function isAuthRequired(error) {
     || error.code === 'auth_required' || error.code === 'AuthRequired')
 }
 
+function readDshRuntime(capabilities) {
+  const runtime = capabilities?._meta?.dsh?.runtime
+  if (!object(runtime)) return undefined
+  const version = readString(runtime, 'version')
+  const source = readString(runtime, 'source')
+  if (version === undefined && source === undefined) return undefined
+  return { version, source, base: readString(runtime, 'base') }
+}
+
 function readString(value, ...keys) {
   if (!object(value)) return undefined
   for (const key of keys) {

package/lib/agent.js

@@ -75,16 +75,11 @@ export function resolveStackedAgent(anchor = import.meta.url, options = {}) {
   const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
   for (const profile of ['tui-test', 'martty', 'tui']) {
     const bin = join(home, 'profiles', profile, 'node_modules', '.bin', 'dsh-acp')
-    const creator = join(
-      home,
-      'profiles',
-      profile,
-      'node_modules',
-      '@openma',
-      'deepseek-harness-tui',
-      'creator',
-    )
-    if (existsSync(bin) && existsSync(join(creator, 'package.json'))) {
+    const creator = [
+      join(home, 'profiles', profile, 'node_modules', '@openma', 'deepseek-harness-tui', 'creator'),
+      join(home, 'profiles', profile, 'node_modules', 'martty', 'creator'),
+    ].find((dir) => existsSync(join(dir, 'package.json')))
+    if (existsSync(bin) && creator) {
       return { command: bin, args: ['--bundle', creator] }
     }
   }

package/lib/creator-overlay.js

@@ -25,6 +25,38 @@ const jsonOutput = {
   render: (_args, value) => [{ type: 'text', text: JSON.stringify(value, null, 2) }],
 }
 
+/**
+ * Whether an acquireScope rejection says the preset is not registered yet.
+ * Preset declarations register asynchronously while the Host activates, so
+ * the overlay can run while the registry is still empty — this is the one
+ * failure worth retrying. Everything else (broken compositions, transport
+ * failures) fails fast.
+ */
+function presetNotFound(error) {
+  return error?.code === 'agent-preset/not-found'
+    || /^Unknown agent preset: /.test(error?.message ?? '')
+}
+
+/**
+ * Acquire one preset scope lease, retrying `agent-preset/not-found` until
+ * `waitMs` elapses — the registry may still be collecting declarations when
+ * this plugin mounts. A registry without `acquireScope` resolves undefined
+ * so the caller can reject it with the usual lease check.
+ */
+async function acquirePresetScope(agentPresets, preset, waitMs, pollMs) {
+  const acquire = agentPresets?.acquireScope
+  if (typeof acquire !== 'function') return undefined
+  const deadline = Date.now() + waitMs
+  for (;;) {
+    try {
+      return await acquire.call(agentPresets, preset)
+    } catch (error) {
+      if (!presetNotFound(error) || Date.now() >= deadline) throw error
+      await new Promise((resolve) => setTimeout(resolve, pollMs))
+    }
+  }
+}
+
 function requireAgent(exec) {
   if (exec?.agent === undefined) {
     throw new Error('TUI artifact tools require an Agent-backed Creator session')
@@ -190,7 +222,7 @@ const skillContent = skillDocument.slice(skillFrontmatter[0].length)
 
 /**
  * @param {object} ctx
- * @param {{ preset?: string }} [config]
+ * @param {{ preset?: string, scopeWaitMs?: number, scopePollMs?: number }} [config]
  */
 export async function apply(ctx, config = {}) {
   // Standalone launches mount this overlay directly into the ACP Host tree,
@@ -202,13 +234,38 @@ export async function apply(ctx, config = {}) {
   if (typeof preset !== 'string' || preset.length === 0) {
     throw new Error('tui-creator-overlay: preset must be a non-empty string')
   }
-  const key = await ctx.agentPresets.standingKeyFor(preset)
-  const scopeModule = await ctx.loader.import('@deepseek-ai/dsh-scope')
-  if (typeof scopeModule?.createScope !== 'function') {
-    throw new Error('tui-creator-overlay: profile dsh-scope module is unavailable')
+  // The preset registry hands out scope keys through acquireScope (a lease
+  // carrying generation.key); standingKeyFor never existed on the shipped
+  // registry. Holding the lease for the overlay's lifetime keeps the scope
+  // generation alive until the overlay is disposed. Declarations land after
+  // dependent rows activate, so a `not-found` result is retried briefly.
+  const scopeWaitMs = Number.isFinite(config.scopeWaitMs) ? Math.max(0, config.scopeWaitMs) : 10_000
+  const scopePollMs = Number.isFinite(config.scopePollMs) ? Math.max(1, config.scopePollMs) : 50
+  const lease = await acquirePresetScope(ctx.agentPresets, preset, scopeWaitMs, scopePollMs)
+  if (lease === null || typeof lease !== 'object' || !('key' in lease)) {
+    throw new Error(`tui-creator-overlay: preset scope is unavailable for ${JSON.stringify(preset)}`)
+  }
+  const release = typeof lease[Symbol.asyncDispose] === 'function'
+    ? () => lease[Symbol.asyncDispose]()
+    : async () => {}
+  let overlay
+  try {
+    const scopeModule = await ctx.loader.import('@deepseek-ai/dsh-scope')
+    if (typeof scopeModule?.createScope !== 'function') {
+      throw new Error('tui-creator-overlay: profile dsh-scope module is unavailable')
+    }
+    overlay = scopeModule.createScope(ctx, lease.key)
+  } catch (error) {
+    await release()
+    throw error
+  }
+  const dispose = async () => {
+    try {
+      await overlay.dispose()
+    } finally {
+      await release()
+    }
   }
-  const { createScope } = scopeModule
-  const overlay = createScope(ctx, key)
   try {
     const toolsModule = await ctx.loader.import('@deepseek-ai/dsh-tools')
     if (typeof toolsModule?.defineTool !== 'function') {
@@ -240,9 +297,9 @@ export async function apply(ctx, config = {}) {
       toolsModule.defineTool,
       createTuiPluginStore({ root: config.artifactRoot }),
     )
-    ctx.effect(() => () => overlay.dispose(), `tui-creator-overlay(${JSON.stringify(preset)})`)
+    ctx.effect(() => dispose, `tui-creator-overlay(${JSON.stringify(preset)})`)
   } catch (error) {
-    await overlay.dispose()
+    await dispose()
     throw error
   }
 }

package/lib/harness-registry.js

@@ -19,13 +19,13 @@ import { downloadFile } from './download.js'
 
 export const ACP_REGISTRY_URL = 'https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json'
 
-const OPENMA_PI_ACP = '@openma/pi-acp@0.1.3'
+export const OPENMA_PI_ACP = '@openma/pi-acp@latest'
 
 function preferMarttyPiAcp(records) {
   return records.map((record) => record.id === 'pi-acp' ? {
     ...record,
     label: 'Pi (OpenMA)',
-    version: '0.1.3',
+    version: 'latest',
     distributions: [{
       type: 'npx', command: 'npx', args: [OPENMA_PI_ACP], env: {},
     }],

package/lib/harnesses.js

@@ -16,12 +16,15 @@ import {
   installRegistryBinary,
   managedBinaryPath,
   normalizeAcpRegistry,
+  OPENMA_PI_ACP,
   readAcpRegistrySnapshot,
 } from './harness-registry.js'
 
 export { fetchAcpRegistry } from './harness-registry.js'
 
 const HARNESS_ID = /^[a-z0-9][a-z0-9-]*$/
+const PI_ACP_LATEST = OPENMA_PI_ACP
+const PI_ACP_SPEC = /^(?:@openma\/)?pi-acp(?:@.+)?$/
 const ANSI = Object.freeze({ reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m', cyan: '\x1b[36m', green: '\x1b[32m' })
 
 // Kept as a source-compatible empty export. The source of truth is the
@@ -361,8 +364,14 @@ function validateHarness(value) {
     || Object.entries(env).some(([key, item]) => key.length === 0 || typeof item !== 'string'))) {
     throw new Error('harness env must be an object of strings')
   }
-  const normalizedArgs = /^npx(?:\.(?:cmd|bat|exe))?$/i.test(path.win32.basename(value.command))
-    ? [...args].filter((arg) => arg !== '--yes' && arg !== '--prefer-offline')
+  const isNpx = /^npx(?:\.(?:cmd|bat|exe))?$/i.test(path.win32.basename(value.command))
+  const normalizedArgs = isNpx
+    ? [...args]
+      .filter((arg) => arg !== '--yes' && arg !== '--prefer-offline')
+      // A pinned pi-acp spec (any old `pi-acp@x` or `@openma/pi-acp@x` entry)
+      // always resolves `latest` at runtime instead — harness upgrades ship
+      // through npm, never through a Martty release.
+      .map((arg) => PI_ACP_SPEC.test(arg) ? PI_ACP_LATEST : arg)
     : [...args]
   return {
     id: value.id,