total-recall-brain 3.47.3 → 3.48.0

package/metadata.plugin.schema.json

@@ -151,6 +151,10 @@
                 "minimum": 1,
                 "maximum": 600000
               },
+              "interactive": {
+                "type": "boolean",
+                "description": "The command is a terminal session (a remote shell, a sign-in). Run from the terminal CLI with stdin and stdout on a TTY, it is attached to the terminal with no runner timeout. Every other caller keeps piped output and the timeout."
+              },
               "args": {
                 "type": "array",
                 "items": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "total-recall-brain",
-  "version": "3.47.3",
+  "version": "3.48.0",
   "description": "The Vibe Coding Brain & Autonomous Software Factory: memory, rules, secrets, and 33 visual plugins automatically managed across all your devices.",
   "type": "module",
   "bin": {

package/scaffold/.agent/skills/total-recall/plugins/mesh/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "tr-plugin-mesh",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-mesh",
-      "version": "0.3.0",
+      "version": "0.3.2",
       "license": "MIT",
       "dependencies": {
         "@gregiteen/ssss-cli": "0.14.5",
@@ -15,7 +15,7 @@
       "devDependencies": {
         "jsdom": "^29.1.1",
         "supertest": "^7.3.1",
-        "total-recall-brain": "3.47.0",
+        "total-recall-brain": "3.47.4",
         "vitest": "^4.1.12"
       }
     },
@@ -7177,9 +7177,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.47.0",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.47.0.tgz",
-      "integrity": "sha512-S4UIdbbTyxw7C4+rix+7oHMm/6gYkcxwNBcP6kRDySX40p5IgqVTKgHk1n8rmaKiyYFoIX/HZHlHSjNrHgn0Gw==",
+      "version": "3.47.4",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.47.4.tgz",
+      "integrity": "sha512-XqUOHFfxiiMVCE7J6nGJdZNrh2M9HXEhIA9ZiKdrGab+AebxMzN5C8mmGVM1Wo1we9szHVUyYr6w+FHOEvni+A==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/scaffold/.agent/skills/total-recall/plugins/mesh/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-mesh",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "type": "module",
   "description": "Headscale and Tailscale SSH control-server mesh administration and node discovery",
   "scripts": {

package/scaffold/.agent/skills/total-recall/plugins/mesh/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://github.com/gregiteen/total-recall/blob/main/metadata.plugin.schema.json",
   "id": "mesh",
   "name": "Headscale",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Control-server mesh administration, Tailscale SSH, and peer node discovery.",
   "license": "MIT",
   "reuse": {
@@ -166,8 +166,9 @@
       },
       {
         "name": "ssh",
-        "description": "Mesh ssh operation",
-        "effect": "write"
+        "description": "Open a terminal session on a mesh node, or run a command there",
+        "effect": "write",
+        "interactive": true
       },
       {
         "name": "exec",

package/scaffold/.agent/skills/total-recall/plugins/mesh/skills/mesh/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: mesh
 description: "Control-server mesh administration, Tailscale SSH, and peer node discovery."
-version: 0.3.0
+version: 0.3.2
 repo_scoped: false
 ---
 
@@ -22,8 +22,8 @@ total-recall mesh status  # Inspect live mesh state
 total-recall mesh view  # Read independent owner observations for mesh screens
 total-recall mesh nodes  # Mesh nodes operation
 total-recall mesh doctor  # Mesh doctor operation
-total-recall mesh ssh  # Mesh ssh operation
-total-recall mesh exec  # Mesh exec operation
+total-recall mesh ssh <node> [cmd]  # Terminal session on a node, no time limit when run from a terminal
+total-recall mesh exec <node> <cmd>  # Scripted command (bounded by the runner timeout)
 total-recall mesh access  # Mesh access operation
 total-recall mesh ping  # Mesh ping operation
 total-recall mesh leader  # Read the elected leader and its server port
@@ -31,6 +31,10 @@ total-recall mesh leader-pin  # Change the pinned leader address and optional se
 total-recall mesh enroll  # Mesh enroll operation
 ```
 
+## Terminal sessions
+
+`ssh` is declared `interactive`. Run from a terminal (stdin and stdout on a TTY), Total Recall attaches it to that terminal with no runner timeout: window resizes and Ctrl-C reach ssh. A command given from a terminal gets a remote terminal (`ssh -t`), so `total-recall mesh ssh <node> 'claude setup-token'` can prompt. Piped or scripted, `ssh` runs under the runner timeout like any other command; use `exec` for scripted work.
+
 ## Owned Raw Commands
 
 This plugin owns: `ssh\s`, `scp\s`, `tailscale\s+(status|ping)\b`.

package/scaffold/.agent/skills/total-recall/plugins/mesh/src/cli/mesh.mjs

@@ -402,8 +402,11 @@ export default async function meshCli(argv = []) {
         return;
       }
 
+      // Run from a terminal, total-recall attaches this command to it (manifest
+      // `interactive`), so ssh reads and writes the person's terminal directly.
       const sshArgs = buildSshArgs(resolved, {
         command: args.length ? args.join(' ') : null,
+        terminal: process.stdin.isTTY === true && process.stdout.isTTY === true,
       });
       const res = spawnSync('ssh', sshArgs, { stdio: 'inherit' });
       process.exitCode = res.status ?? 1;

package/scaffold/.agent/skills/total-recall/plugins/mesh/src/core/mesh-access.mjs

@@ -234,10 +234,13 @@ export function formatAccessTarget(resolved) {
  * cannot silently offer a different key first and get the connection refused
  * before the right key is ever tried.
  */
-export function buildSshArgs(resolved, { command = null, extraOptions = [] } = {}) {
+export function buildSshArgs(resolved, { command = null, extraOptions = [], terminal = false } = {}) {
   if (!resolved?.complete) return null;
 
   const args = [];
+  // ssh gives a remote command no terminal unless asked, so a sign-in run from a
+  // person's terminal (`mesh ssh node 'claude setup-token'`) could not prompt.
+  if (terminal && command) args.push('-t');
   if (resolved.port && resolved.port !== DEFAULT_SSH_PORT) args.push('-p', String(resolved.port));
   if (resolved.identity_file) {
     args.push('-i', resolved.identity_file, '-o', 'IdentitiesOnly=yes');

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/package-lock.json

@@ -1,17 +1,17 @@
 {
   "name": "tr-plugin-meta-harness",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "tr-plugin-meta-harness",
-      "version": "0.4.3",
+      "version": "0.4.4",
       "dependencies": {
         "@gregiteen/ssss-cli": "0.14.5"
       },
       "devDependencies": {
-        "total-recall-brain": "3.47.1"
+        "total-recall-brain": "3.47.3"
       }
     },
     "node_modules/@alcalzone/ansi-tokenize": {
@@ -5546,9 +5546,9 @@
       }
     },
     "node_modules/total-recall-brain": {
-      "version": "3.47.1",
-      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.47.1.tgz",
-      "integrity": "sha512-9yDByVZMNxNE10hjPf0vEmvBLGGUpD8sqAN7svuZpJEb2TSTPA1eSSwaZ5H4QScJQTT3DcV8MeQjuyLy8urnEw==",
+      "version": "3.47.3",
+      "resolved": "https://registry.npmjs.org/total-recall-brain/-/total-recall-brain-3.47.3.tgz",
+      "integrity": "sha512-F7QAR+Sj8fWb2h0a0zrgBSmsujE3P0i7lrt4Dj3aI8FjZf1tcEMmwM57BDDo7IIXZAEu3OSCDw9ggnbrOy4pYA==",
       "dev": true,
       "license": "MIT",
       "workspaces": [

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tr-plugin-meta-harness",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Total Recall Metaharness plugin",
   "type": "module",
   "scripts": {

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "meta-harness",
   "name": "Metaharness",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "Discover, configure, document, track, and run coding agent harnesses through Total Recall across mesh nodes.",
   "gate": {
     "tasks": ["Run work in another agent harness", "Choose which harness takes a task", "Check harness versions, sign-in and quota", "Read a harness's official documentation"],

package/scaffold/.agent/skills/total-recall/plugins/meta-harness/src/router.mjs

@@ -286,7 +286,12 @@ export async function routeTask(taskDescription, options = {}) {
     ...(remote || lean.fleet ? {} : { fleet: complexity.tier === 'local' ? cachedFleet : () => ({ ok: false, error: 'Not read: this route places no local work', nodes: [] }) }),
   });
   const quotas = quotaReport.quotas;
-  const rank = ready => selectOptimalHarness(taskDescription, ready.map(h => h.id), quotas, { ...options, tierOverride: complexity.tier, empiricalScorecard: computeEmpiricalScorecard(receipts) });
+  // No ready harness means none can take the task. The ranking reads an empty list as the whole
+  // catalog, so a node whose only ready harness was walled for quota chose an OpenRouter harness
+  // outside the included policy, with no credit behind it.
+  const rank = ready => (ready.length
+    ? selectOptimalHarness(taskDescription, ready.map(h => h.id), quotas, { ...options, tierOverride: complexity.tier, empiricalScorecard: computeEmpiricalScorecard(receipts) })
+    : { selected: null, candidates: [] });
   let excluded = pool.excluded;
   let routing = rank(pool.ready);
   // Quota walls come from launches this machine saw refused. With none recorded here, a route kept

package/scaffold/.agent/skills/total-recall/references/mesh.md

@@ -7,6 +7,8 @@ Credential lookup, control-server API keys and mesh sync tokens use auth. Enroll
 Presence accepts fresh authenticated observations. Unknown activity cannot imply an active user. No active target is an error for automatic dispatch. Commands succeed only after their actual execution result; notification acknowledgement is not proof the user viewed it. Test timeouts, stale records, denied peers, local execution and remote failures. Never copy/merge brains during leader changes. Significant mesh extraction and truthfulness work remains in progress until owner and integration suites pass.
 
 
+`mesh ssh <node>` is declared `interactive`: from a terminal it is a real session with no time limit (window resizes and Ctrl-C reach ssh). `mesh ssh <node> '<command>'` from a terminal gets a remote terminal (`ssh -t`), so sign-ins such as `claude setup-token` work. Piped or scripted, it runs as before under the runner timeout; use `mesh exec` for scripted commands.
+
 Host service adapters require the explicitly selected absolute TR_PACKAGE_ROOT; independently installed host packages are never execution substitutes. The mesh owner runtime suite passes 249 tests plus three Node manifest/host-boundary tests; these do not prove live mesh provider health.
 
 ## Developer-owned control server

package/scaffold/.agent/skills/total-recall/references/plugins.md

@@ -8,6 +8,8 @@ Plugin UI is purpose-specific and belongs in its repository. Bind cards to actua
 
 The bridge rejects undeclared commands even when a manifest declares no commands. Cards execute only explicitly declared read effects. Owner panels may submit one declared secret string with `host.run(command, args, { stdin: value })`; the authenticated server validates the declaration and 64 KiB UTF-8 bound, pipes it with `--stdin`, and suppresses child output. Workspace components resolve to owner UI element ids/tags; missing interfaces and unsupported device access stay unavailable. Live card regions mount owner panels. Full provider behavior and audio sessions still require separate end-to-end verification.
 
+Plugin commands run in a child process with piped, bounded output and a timeout (`timeout_ms`, 1..600000; default 30 s). A subcommand that is a terminal session, such as a remote shell or a sign-in, declares `interactive: true`. When the terminal CLI runs it with stdin and stdout on a TTY, the child is attached to the terminal (all three streams, the terminal's foreground process group) with no timeout, and the CLI exits with its code. The server, scripts, piped calls and composable calls keep piped output and the timeout.
+
 Configuration uses validated records/SSSS contracts. A manifest task schedule is not an active runner. Resolve node placement and daemon evidence; do not run recurring work on an arbitrary laptop. Verify tests/package provenance separately from install/runtime readiness. Keep the owner skill and this router's relevant reference synchronized whenever capabilities change.
 
 

package/src/core/plugin-contracts/manifest.mjs

@@ -53,6 +53,8 @@ export function validateManifestContract(manifest) {
       // The runner refuses anything outside this range, so a manifest that
       // declares it must fail validation rather than every call at run time.
       if (sub.timeout_ms !== undefined && (!Number.isInteger(sub.timeout_ms) || sub.timeout_ms < 1 || sub.timeout_ms > 600000)) errors.push(`${where}.timeout_ms must be an integer from 1 to 600000`);
+      // Run from a terminal, an interactive command is attached to it with no timeout (plugin-runner.mjs).
+      if (sub.interactive !== undefined && typeof sub.interactive !== 'boolean') errors.push(`${where}.interactive must be a boolean`);
       if (sub.args !== undefined) {
         if (!Array.isArray(sub.args)) errors.push(`${where}.args must be an array`);
         else {

package/src/core/plugin-runner.mjs

@@ -24,6 +24,11 @@ export const CLI_MAX_OUTPUT_BYTES = 16 * 1024 * 1024;
 export const MAX_INPUT_BYTES = 64 * 1024;
 export const MAX_REQUEST_BYTES = 1024 * 1024;
 
+/** Both ends a person types into and reads from are a terminal. */
+export function stdioIsTerminal() {
+  return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+
 /** A credential is one declared string on stdin, never a command-line value. */
 export function validatePluginSecretInput(plugin, subcommand, input) {
   if (input === undefined) return;
@@ -39,8 +44,9 @@ export function validatePluginSecretInput(plugin, subcommand, input) {
 
 /**
  * @param {object} plugin  A discovered plugin ({ id, dir, manifest }).
- * @param {{ subcommand?: string, args?: string[], cwd?: string, projectRoot?: string|null, timeoutMs?: number }} [options]
- * @returns {Promise<{ ok: boolean, exitCode: number|null, signal: string|null, timedOut: boolean, truncated: boolean, output: string, durationMs: number }>}
+ * @param {{ subcommand?: string, args?: string[], cwd?: string, projectRoot?: string|null, timeoutMs?: number, tty?: boolean }} [options]
+ *   `tty` overrides terminal detection (stdin and stdout are TTYs) for an interactive subcommand.
+ * @returns {Promise<{ ok: boolean, exitCode: number|null, signal: string|null, timedOut: boolean, truncated: boolean, output: string, durationMs: number, interactive?: boolean }>}
  */
 export function runPluginCommand(plugin, options = {}) {
   const { subcommand = '', args = [], cwd = process.cwd(), timeoutMs: requestedTimeoutMs, stdin = 'ignore', stdinText, stdinRequest, composable = false, secretsBrainDir } = options;
@@ -95,6 +101,24 @@ export function runPluginCommand(plugin, options = {}) {
   const childArgv = [CHILD, handler, command, ...(subcommand ? [String(subcommand)] : []), ...safeArgs];
   // Only an explicitly selected project owns repository state. The cwd fallback above preserves legacy activation.
   const statePluginsDir = options.projectRoot ? projectPluginsDir(projectRoot) : recordPluginsDir(plugin);
+  const env = {
+    ...process.env,
+    TR_PACKAGE_ROOT: PACKAGE_ROOT,
+    TOTAL_RECALL_BIN: path.join(PACKAGE_ROOT, 'bin', 'total-recall.mjs'),
+    TR_PLUGIN_ID: plugin.id,
+    TR_PLUGIN_DIR: plugin.dir,
+    TR_PLUGIN_CONFIG: JSON.stringify(readPluginRecord(plugin)?.configuration || {}),
+    ...(statePluginsDir ? { TR_PLUGIN_STATE_DIR: path.join(path.dirname(statePluginsDir), 'plugin-state', plugin.id) } : {}),
+    ...(secretsBrainDir ? { TR_SECRETS_BRAIN: secretsBrainDir } : {}),
+    TR_PLUGIN_COMMAND_MODE: composable ? 'composable' : 'cli',
+  };
+
+  // An interactive subcommand (a remote shell, a sign-in) run by a person at a terminal is
+  // attached to that terminal: no pipes, no output buffer, no timer. Every other caller (the
+  // server, a script, a nested composable call, a stdin request) keeps the bounded path below.
+  const attach = declaration?.interactive === true && stdin === 'inherit' && stdinPayload === undefined &&
+    !composable && (options.tty ?? stdioIsTerminal());
+  if (attach) return runAttached(childArgv, { cwd, env });
 
   return new Promise((resolve) => {
     const started = Date.now();
@@ -108,19 +132,7 @@ export function runPluginCommand(plugin, options = {}) {
     const child = spawn(process.execPath, childArgv, {
       cwd,
       detached: process.platform !== 'win32',
-      env: {
-        ...process.env,
-        TR_PACKAGE_ROOT: PACKAGE_ROOT,
-        TOTAL_RECALL_BIN: path.join(PACKAGE_ROOT, 'bin', 'total-recall.mjs'),
-        TR_PLUGIN_ID: plugin.id,
-        TR_PLUGIN_DIR: plugin.dir,
-        TR_PLUGIN_CONFIG: JSON.stringify(readPluginRecord(plugin)?.configuration || {}),
-        ...(statePluginsDir ? { TR_PLUGIN_STATE_DIR: path.join(path.dirname(statePluginsDir), 'plugin-state', plugin.id) } : {}),
-        ...(secretsBrainDir ? { TR_SECRETS_BRAIN: secretsBrainDir } : {}),
-        TR_PLUGIN_COMMAND_MODE: composable ? 'composable' : 'cli',
-        FORCE_COLOR: '0',
-        NO_COLOR: '1'
-      },
+      env: { ...env, FORCE_COLOR: '0', NO_COLOR: '1' },
       stdio: [stdinPayload !== undefined ? 'pipe' : stdin === 'inherit' ? 'inherit' : 'ignore', 'pipe', 'pipe']
     });
 
@@ -181,3 +193,32 @@ export function runPluginCommand(plugin, options = {}) {
     child.on('close', (code, signal) => finish(code, signal));
   });
 }
+
+/**
+ * Run a handler on this process's own terminal. The child is not detached: it stays in the
+ * terminal's session and foreground process group, so it gets window resizes (SIGWINCH), Ctrl-C
+ * and the other terminal signals itself. Like a shell waiting on a job, this process ignores
+ * SIGINT and SIGQUIT until the child exits, then reports the child's exit code.
+ */
+function runAttached(childArgv, { cwd, env }) {
+  return new Promise((resolve) => {
+    const started = Date.now();
+    const signals = process.platform === 'win32' ? ['SIGINT'] : ['SIGINT', 'SIGQUIT'];
+    const ignore = () => {};
+    for (const name of signals) process.on(name, ignore);
+    let settled = false;
+    const finish = (exitCode, signal, spawnError) => {
+      if (settled) return;
+      settled = true;
+      for (const name of signals) process.removeListener(name, ignore);
+      const message = spawnError ? `[runner] ${spawnError.message}` : '';
+      resolve({
+        ok: !spawnError && exitCode === 0, exitCode, signal, timedOut: false, truncated: false, interactive: true,
+        output: message, stdout: '', stderr: message, durationMs: Date.now() - started,
+      });
+    };
+    const child = spawn(process.execPath, childArgv, { cwd, env, stdio: 'inherit' });
+    child.on('error', (err) => finish(null, null, err));
+    child.on('close', (code, signal) => finish(code, signal));
+  });
+}