golem-kit 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.2.4
+
+- Chat and builder no longer fight over one Stop hook: the turn-end relay asks tmux which window it ran in instead of trusting the key baked in when it was installed, so a chat message sent after the builder was opened gets its reply and the composer unlocks. `installHooks` also keeps exactly one entry for itself, matched by script name, so a source-pin change between releases replaces it instead of stacking another.
+
+## 0.2.3
+
+- A model pin follows its agent: change `chat.agent` (or `agents.builder`) and the conversation saved on the old agent is retired on the next start instead of resumed with the new agent's pin. It stays readable in `.golem/conversations.json`, marked, and the next message opens a fresh conversation on the configured agent.
+- `chat: { provider: 'tmux', sandbox: 'none' }` launches the chat agent on the builder's bypass profile, for boxes where the CLI's own sandbox cannot start.
+
 ## 0.2.2
 
 - An app pins the model its terminal agents run on: `chat: { provider: 'tmux', agent, model }` for normal-mode chat and `agents.builderModel` for the builder. The pin rides the launch args (`-m` for Codex, `--model` for Claude Code) and is replayed on resume.

package/docs/agents.md

@@ -31,6 +31,8 @@ export default {
 
 - `builder` is the default choice in build mode. A person's own pick in the browser still wins and is remembered.
 - `builderModel` pins the builder CLI's model, in that CLI's own spelling (`--model` for Claude Code, `-m` for Codex). A terminal chat pins its own the same way: `chat: { provider: 'tmux', agent: 'codex', model: 'gpt-6-luna' }`. Both survive a resume. Left out, each CLI picks its default.
+- Change `chat.agent` (or `agents.builder`) and the conversation saved on the old agent is retired on the next server start, so its pin never follows it: it stays readable in `.golem/conversations.json`, marked `retired`, and the next message opens a fresh conversation on the configured agent.
+- `chat.sandbox` picks the terminal chat's launch profile: `'read-only'` (the default) is the CLI's own read-only sandbox, `'none'` is the builder's bypass profile. Use `'none'` where the sandbox cannot start, e.g. codex's `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` under `kernel.apparmor_restrict_unprivileged_userns=1`.
 - `ordinary` turns on the **Start a chat** button. Leave it out and there is no ordinary chat.
 - `ordinary.model` defaults to `claude-opus-5`.
 - `golem.config.ts` is bundled into the browser. Keep the API key in `.env.local` or the server environment, never in this file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "golem-kit",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Starter kit and local CLI for Golem applications.",
   "type": "module",
   "exports": {

package/src/config.ts

@@ -12,7 +12,14 @@ export type ModelConfig = { runtime: 'claude' | 'codex'; name?: string }
  * terminal agent in the `chat` window of the app's tmux session, briefed from `docs/chat.md`.
  * `roles` restricts chat to those account roles; absent, anyone signed in may chat.
  */
-export type ChatConfig = ({ provider: 'anthropic' } | { provider: 'tmux'; agent?: 'codex' | 'claude'; model?: string }) & { roles?: string[] }
+export type ChatConfig = ({ provider: 'anthropic' } | { provider: 'tmux'; agent?: 'codex' | 'claude'; model?: string; sandbox?: 'read-only' | 'none' }) & { roles?: string[] }
+/**
+ * The terminal chat's launch profile: the CLI's own read-only sandbox, or — where that sandbox cannot start
+ * (codex's bwrap under `kernel.apparmor_restrict_unprivileged_userns=1`) — the builder's bypass profile.
+ */
+export const chatPermissions = (chat: ChatConfig | undefined): 'bypass' | 'readonly' =>
+  chat?.provider === 'tmux' && chat.sandbox === 'none' ? 'bypass' : 'readonly'
+
 /** `brain: true` serves the app's `brain/` folder read-only and mounts the Brain reader beside the app. */
 
 /**
@@ -70,11 +77,12 @@ export async function loadAppConfig(root = process.cwd()): Promise<AppConfig> {
       config.agents = { ...config.agents, ordinary: ordinaryAgent({ backend: 'anthropic', ...rest }) }
       config.chat = { provider, ...chatRoles }
     } else if (provider === 'tmux') {
-      const { agent, model, ...unknown } = rest
+      const { agent, model, sandbox, ...unknown } = rest
       if (Object.keys(unknown).length) throw new Error(`golem.config.ts chat has unknown fields: ${Object.keys(unknown).join(', ')}`)
       if (agent !== undefined && agent !== 'codex' && agent !== 'claude') throw new Error("golem.config.ts chat.agent must be 'codex' or 'claude'")
       if (model !== undefined && (typeof model !== 'string' || !model)) throw new Error('golem.config.ts chat.model must be a nonempty string')
-      config.chat = { provider, ...(agent ? { agent } : {}), ...(model ? { model: model as string } : {}), ...chatRoles }
+      if (sandbox !== undefined && sandbox !== 'read-only' && sandbox !== 'none') throw new Error("golem.config.ts chat.sandbox must be 'read-only' or 'none'")
+      config.chat = { provider, ...(agent ? { agent } : {}), ...(model ? { model: model as string } : {}), ...(sandbox ? { sandbox: sandbox as 'read-only' | 'none' } : {}), ...chatRoles }
     } else throw new Error("golem.config.ts chat.provider must be 'anthropic' or 'tmux'")
   } else if (config.agents?.ordinary) config.chat = { provider: 'anthropic' }
   return config

package/src/dev-server.ts

@@ -7,7 +7,7 @@ import { buildBrowser, rebuild } from './browser-build.ts';
 import { createAppBackend, type AppBackend } from './backend/http.ts';
 import { ordinaryChat, type OrdinaryChat } from './chat.ts';
 import { openBrain } from './brain.ts';
-import { serverUrl } from './config.ts';
+import { chatPermissions, serverUrl } from './config.ts';
 import { discoverAgents, runtimeState, type AgentName } from './runtime/discovery.ts';
 import { SessionManager, type Session, type SessionBackend, type SessionSnapshot } from './runtime/session.ts';
 import { TmuxBackend, chatInstructions, type HarnessRef } from './runtime/tmux.ts';
@@ -46,11 +46,13 @@ export async function startDevServer(
   createBackend ??= async (backend, ref, buildMode = true) => {
     if (!ref && !(await discoverAgents()).some((found) => found.agent === backend && found.runnable)) throw new Error(`${backend} is not runnable here`);
     const model = buildMode ? app.config.agents?.builderModel : app.config.chat?.provider === 'tmux' ? app.config.chat.model : undefined;
-    return new TmuxBackend(appRoot, backend, ref, { stateDir: join(stateDirectory, 'harness'), api: serverUrl(host, port), window: buildMode ? 'builder' : 'chat', ...(model ? { model } : {}), ...(buildMode ? {} : { instructions: chatInstructions(appRoot), permissions: 'readonly' }) });
+    return new TmuxBackend(appRoot, backend, ref, { stateDir: join(stateDirectory, 'harness'), api: serverUrl(host, port), window: buildMode ? 'builder' : 'chat', ...(model ? { model } : {}), ...(buildMode ? {} : { instructions: chatInstructions(appRoot), permissions: chatPermissions(app.config.chat) }) });
   };
   const builder = await builderFlag(stateDirectory);
   const state = new ConversationState(stateDirectory);
-  const sessions = new SessionManager((snapshots) => state.save(snapshots));
+  // Retired conversations are no longer live, but they stay in the file: `save` writes them back beside the rest.
+  let retired: SessionSnapshot[] = [];
+  const sessions = new SessionManager((snapshots) => state.save([...retired, ...snapshots]));
   const app = await createAppBackend(appRoot, join(stateDirectory, 'data'));
   const chat = ordinaryChat(app);
   const brain = app.config.brain ? openBrain(join(appRoot, 'brain')) : undefined;
@@ -60,7 +62,16 @@ export async function startDevServer(
     owns: (conversation, owner) => { const session = sessions.get(conversation); return session?.backend === 'anthropic' && session.owner === owner; },
   });
   // Restored conversations wait for their next message; nothing is re-run.
-  const restored = await state.load();
+  const saved = await state.load();
+  // A pin follows its agent: when the app changes `chat.agent` (or `agents.builder`), the conversation saved
+  // on the old agent is retired rather than resumed, so the new agent's model never reaches the old CLI. It
+  // stays readable in the file, marked; the browser finds no conversation and starts one on the new agent.
+  const agentOf = (buildMode: boolean) => buildMode ? app.config.agents?.builder : app.config.chat?.provider === 'tmux' ? app.config.chat.agent : undefined;
+  const stale = saved.filter((snapshot) => !snapshot.retired && snapshot.backend !== 'anthropic'
+    && agentOf(snapshot.buildMode) !== undefined && agentOf(snapshot.buildMode) !== snapshot.backend);
+  for (const snapshot of stale) console.log(`Retired the ${snapshot.buildMode ? 'builder' : 'chat'} conversation on ${snapshot.backend}: this app now runs ${agentOf(snapshot.buildMode)}.`);
+  retired = saved.filter((snapshot) => snapshot.retired || stale.includes(snapshot)).map((snapshot) => ({ ...snapshot, retired: true }));
+  const restored = saved.filter((snapshot) => !snapshot.retired && !stale.includes(snapshot));
   const workers = await Promise.all(restored.map((snapshot) => snapshot.backend === 'anthropic'
     ? chat.backend(snapshot.transcript)
     : createBackend(snapshot.backend, snapshot.harness as HarnessRef | undefined, snapshot.buildMode)));

package/src/runtime/harness/claude-tmux.js

@@ -161,18 +161,19 @@ async function installHooks(cwd, session, stateDir, callbackUrl) {
   const command = ['node', s.shellQuote(HOOK_SCRIPT), s.shellQuote(stateDir), s.shellQuote(session)]
     .concat(callbackUrl ? [s.shellQuote(callbackUrl)] : [])
     .join(' ');
+  const hookName = path.basename(HOOK_SCRIPT);
   mergeLocalSettings(cwd, (settings) => {
     if (!settings.hooks || typeof settings.hooks !== 'object') settings.hooks = {};
     if (!Array.isArray(settings.hooks.Stop)) settings.hooks.Stop = [];
-    const ours = settings.hooks.Stop.some((m) =>
-      Array.isArray(m.hooks) && m.hooks.some((h) => h.command === command));
-    if (!ours) {
-      // Drop stale bc hook entries (e.g. a previous session in this cwd) first.
-      settings.hooks.Stop = settings.hooks.Stop.filter((m) =>
-        !(Array.isArray(m.hooks) && m.hooks.some((h) =>
-          typeof h.command === 'string' && h.command.includes(HOOK_SCRIPT))));
-      settings.hooks.Stop.push({ hooks: [{ type: 'command', command }] });
-    }
+    // Exactly ONE entry for our script, always. Matched on the basename, not the
+    // full path: a source pin (or an npx cache) moves the script between releases,
+    // and a path match let one entry per path pile up — every turn end then wrote
+    // every stale key's file. The hook resolves its own key at run time, so the
+    // single surviving entry serves every window in this cwd.
+    settings.hooks.Stop = settings.hooks.Stop.filter((m) =>
+      !(Array.isArray(m.hooks) && m.hooks.some((h) =>
+        typeof h.command === 'string' && h.command.includes(hookName))));
+    settings.hooks.Stop.push({ hooks: [{ type: 'command', command }] });
   });
   await excludeLocalSettings(cwd);
 }

package/src/runtime/harness/turnend-hook.js

@@ -22,18 +22,33 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { execFileSync } = require('node:child_process');
 
-// The hook runs inside the agent's own pane, so its tmux session identifies
-// the session exactly (the server attributes lieutenant turn-ends by it).
+// The hook runs inside the agent's own pane, so tmux identifies it exactly.
 // Empty when not under tmux; never fails the hook when tmux is absent.
-function tmuxSession() {
+// golem: '#S:#W', and -t $TMUX_PANE, because a bare display-message answers for
+// the session's ACTIVE window — from the builder's pane, while the chat window
+// was current, it said ':chat'. The pane id is the only self-reference a hook
+// running outside the active window can trust.
+function tmuxPane() {
   if (!process.env.TMUX) return '';
+  const target = process.env.TMUX_PANE ? ['-t', process.env.TMUX_PANE] : [];
   try {
-    return execFileSync('tmux', ['display-message', '-p', '#S'], { encoding: 'utf8' }).trim();
+    return execFileSync('tmux', ['display-message', '-p'].concat(target, ['#S:#W']), { encoding: 'utf8' }).trim();
   } catch {
     return '';
   }
 }
 
+// golem: runtimeKey(argvKey) — which agent's turn just ended.
+// Claude Code keeps ONE Stop hook per cwd, and window-granular agents (the
+// builder and the chat) share a cwd: the key baked into argv at install time is
+// whichever spawned last, so the other one's turn ends would land in the wrong
+// file and its send() would wait forever. Ask tmux instead. Session-granular
+// agents own their whole session (no ':' in their key) and keep the argv key.
+function runtimeKey(argvKey) {
+  if (!argvKey.includes(':')) return argvKey;
+  return tmuxPane() || argvKey;
+}
+
 function readStdin() {
   return new Promise((resolve) => {
     let data = '';
@@ -53,7 +68,7 @@ function readStdin() {
 
 async function main() {
   const stateDir = process.argv[2];
-  const session = process.argv[3];
+  const session = runtimeKey(process.argv[3] || '');
   const url = process.argv[4] || process.env.BC_TURNEND_URL || '';
   if (!stateDir || !session) return;
 
@@ -70,7 +85,7 @@ async function main() {
     event: payload.hook_event_name || 'Stop',
     session_id: payload.session_id || null,
     cwd: payload.cwd || null,
-    tmux_session: tmuxSession(),
+    tmux_session: tmuxPane().split(':')[0],
   };
   // What the agent last said, when the harness hands it over — the stall
   // alert quotes it so the board knows what a silent worker was waiting on.

package/src/runtime/session.ts

@@ -392,6 +392,8 @@ export type SessionSnapshot = {
   harness?: unknown
   transcript?: unknown
   updatedAt?: string
+  /** Set when the app's configured agent no longer matches `backend`: kept in the file, never restored. */
+  retired?: boolean
 }
 
 export class SessionManager {