total-recall-brain 3.44.0 → 3.46.0

package/scaffold/.agent/skills/total-recall/plugins/ssss/ui/chunks/validate.md

@@ -0,0 +1,34 @@
+---
+type: ui-chunk:chunk
+plugin: ssss
+id: validate
+title: Document contract
+description: Validates one SSSS Markdown document's frontmatter against the effective registry, optionally with an extension registry, and lists each error and warning.
+timestamp: '2026-11-08T08:12:00Z'
+intents: ["validate ssss document", "check frontmatter against registry", "why is this ssss document invalid", "validate with extension registry"]
+surfaces: [page]
+operations: [validate]
+data: ["validate:/ok", "validate:/valid", "validate:/type", "validate:/errors", "validate:/warnings", "validate:/error", "validate:/checkedAt"]
+panel: home
+---
+<section class="ssss-contract" data-design-component="ledger-sheet" aria-labelledby="ssss-validate-title">
+  <style>
+    .ssss-contract { display:grid; gap:var(--spacing-md, 12px); }
+    .ssss-contract h2 { margin:0; font:var(--typography-heading-font-weight, 650) var(--typography-heading-font-size, 18px)/var(--typography-heading-line-height, 1.3) var(--typography-heading-font-family, sans-serif); }
+    .ssss-contract p { margin:0; color:var(--color-quiet, #c2b59f); }
+    .ssss-contract table { width:100%; border-collapse:collapse; }
+    .ssss-contract th, .ssss-contract td { text-align:left; vertical-align:top; padding:var(--spacing-sm, 8px); border-top:1px solid var(--color-line, #564636); }
+    .ssss-contract th { font-weight:400; white-space:nowrap; }
+  </style>
+  <h2 id="ssss-validate-title">Document contract</h2>
+  <p>Give a document path inside the current workspace. Only the verdict comes back. The document's contents are never returned.</p>
+  <table>
+    <tbody>
+      <tr><th scope="row"><code data-design-component="field-pointer">valid</code></th><td>Whether the frontmatter satisfies the type it declares.</td></tr>
+      <tr><th scope="row"><code data-design-component="field-pointer">type</code></th><td>The SSSS primitive type the document claims.</td></tr>
+      <tr><th scope="row"><code data-design-component="field-pointer">errors</code></th><td>Each violation that makes the document invalid.</td></tr>
+      <tr><th scope="row"><code data-design-component="field-pointer">warnings</code></th><td>Findings that do not block validity.</td></tr>
+      <tr><th scope="row"><code data-design-component="field-pointer">error</code></th><td>Why the check could not run, such as a path outside the workspace.</td></tr>
+    </tbody>
+  </table>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/ssss/ui/chunks/validation-diagnostics.md

@@ -0,0 +1,17 @@
+---
+type: ui-chunk:chunk
+plugin: ssss
+id: validation-diagnostics
+title: Diagnose SSSS frontmatter validation findings
+description: Distinguish a file that the validator could not open from a document whose declared SSSS type failed its required fields.
+timestamp: '2026-11-08T23:21:00Z'
+intents: ["fix a missing SSSS frontmatter field", "diagnose SSSS validation findings", "distinguish invalid document from unavailable file"]
+surfaces: [page]
+operations: [validate]
+data: ["validate:/ok", "validate:/valid", "validate:/type", "validate:/errors", "validate:/warnings", "validate:/error"]
+panel: home
+---
+<section data-design-component="ledger-sheet">
+  <h2>Separate document errors from file errors</h2>
+  <ol><li>Enter the file path inside the selected workspace and run Validate document.</li><li>Confirm the expected primitive type, then read the individual findings.</li><li>Review warnings separately from errors that block the document.</li></ol>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/ssss/ui/chunks/workspace-registry-preflight.md

@@ -0,0 +1,17 @@
+---
+type: ui-chunk:chunk
+plugin: ssss
+id: workspace-registry-preflight
+title: Check the workspace registry before validating documents
+description: Verify the current lock and extension combination before diagnosing a workspace document against that registry.
+timestamp: '2026-11-08T23:21:00Z'
+intents: ["check SSSS registry before validating documents", "diagnose workspace schema version drift", "verify lock and extension registry together"]
+surfaces: [page]
+operations: [registry, validate]
+data: ["registry:/valid", "registry:/expected_integrity", "registry:/actual_integrity", "registry:/specVersion", "validate:/type", "validate:/valid"]
+panel: home
+---
+<section data-design-component="ledger-sheet">
+  <h2>Check the registry before inspecting a document</h2>
+  <p>Verify the lock using the workspace's extension registry. When it matches, validate the document with the same extension. If the lock differs, compare the recorded and computed integrity before changing the schema.</p>
+</section>

package/scaffold/.agent/skills/total-recall/plugins/ssss/ui/home.js

@@ -0,0 +1,348 @@
+const ink = 'var(--color-ink, #1b1814)';
+const panel = 'var(--color-panel, #27211a)';
+const line = 'var(--color-line, #564636)';
+const paper = 'var(--color-paper, #f7ebd6)';
+const quiet = 'var(--color-quiet, #c2b59f)';
+const amber = 'var(--color-amber, #b98439)';
+const gold = 'var(--color-gold, #f4c97a)';
+const sans = 'var(--typography-body-font-family, IBM Plex Sans, system-ui, sans-serif)';
+const mono = 'var(--typography-evidence-font-family, IBM Plex Mono, ui-monospace, monospace)';
+
+const page = `
+  <style>
+    :host { display:block; color:${paper}; font:var(--typography-body-font-size, 14px)/var(--typography-body-line-height, 1.45) ${sans}; }
+    * { box-sizing:border-box; }
+    h2,h3,p,dl,dd,ul { margin:0; }
+    .sheet {
+      background:var(--component-ledger-sheet-background-color, ${ink});
+      border:1px solid var(--component-ledger-sheet-border-color, ${line});
+      border-radius:var(--radius-md, 10px); overflow:hidden;
+    }
+    header { display:flex; flex-wrap:wrap; align-items:center; gap:var(--spacing-md, 12px);
+      padding:var(--spacing-md, 12px) var(--spacing-lg, 16px); border-bottom:1px solid ${line}; }
+    .mark { width:32px; height:32px; flex:none; color:${gold}; }
+    .title { flex:1 1 200px; }
+    h2 { font:var(--typography-heading-font-weight, 650) var(--typography-heading-font-size, 18px)/var(--typography-heading-line-height, 1.3) ${sans}; }
+    h3 { font-size:15px; margin-bottom:var(--spacing-sm, 8px); }
+    .quiet, label, dt { color:${quiet}; }
+    .ledger { display:grid; grid-template-columns:repeat(auto-fit, minmax(min(100%, 200px), 1fr)); gap:1px; background:${line}; }
+    .slot {
+      min-width:0; background:var(--component-ledger-slot-background-color, ${panel});
+      border-left:3px solid var(--component-ledger-slot-border-color, ${amber});
+      padding:var(--component-ledger-slot-padding, 12px 16px);
+    }
+    dd { margin-top:var(--spacing-xs, 4px); font-size:16px; font-weight:650; overflow-wrap:anywhere; }
+    small, .path { display:block; margin-top:var(--spacing-xs, 4px); color:${quiet}; font-family:${mono}; font-size:12px; overflow-wrap:anywhere; }
+    .reading { display:flex; flex-wrap:wrap; justify-content:space-between; gap:var(--spacing-sm, 8px);
+      padding:var(--spacing-sm, 8px) var(--spacing-lg, 16px); border-bottom:1px solid ${line}; }
+    .groups { display:grid; grid-template-columns:repeat(auto-fit, minmax(min(100%, 280px), 1fr)); }
+    section.group { min-width:0; padding:var(--spacing-lg, 16px); border-bottom:1px solid ${line}; border-right:1px solid ${line}; }
+    form { display:grid; gap:var(--spacing-sm, 8px); }
+    label { display:grid; gap:var(--spacing-xs, 4px); }
+    .choice { display:flex; align-items:center; gap:6px; min-height:44px; color:${paper}; }
+    button, input, select {
+      min-height:44px; max-width:100%; padding:6px 10px; font:inherit; color:${paper};
+      background:${panel}; border:1px solid ${line}; border-radius:var(--radius-sm, 5px);
+    }
+    input[type=text] { width:100%; min-width:0; font-family:${mono}; }
+    input[type=checkbox] { min-height:auto; width:18px; height:18px; }
+    button { cursor:pointer; }
+    .primary { border-color:${gold}; color:${gold}; }
+    button:disabled, select:disabled { opacity:.55; cursor:wait; }
+    :focus-visible { outline:2px solid ${gold}; outline-offset:2px; }
+    .outcome { margin-top:var(--spacing-md, 12px); }
+    .verdict { font-weight:650; }
+    [data-tone=pass] { color:var(--component-verdict-pass-text-color, var(--color-pass, #c2e4ad)); }
+    [data-tone=fail] { color:var(--component-verdict-fail-text-color, var(--color-fail, #ffaaa1)); }
+    .fields { display:grid; grid-template-columns:max-content 1fr; gap:2px var(--spacing-md, 12px); margin-top:var(--spacing-sm, 8px); }
+    .fields dt { font-family:${mono}; color:var(--component-field-pointer-text-color, ${gold}); font-size:12px; }
+    .fields dd { margin:0; font-size:13px; font-weight:400; font-family:${mono}; overflow-wrap:anywhere; }
+    ul.findings { padding-left:18px; margin-top:var(--spacing-xs, 4px); font-family:${mono}; font-size:12px; }
+    pre {
+      margin:var(--spacing-sm, 8px) 0 0; max-height:280px; overflow:auto; white-space:pre-wrap; overflow-wrap:anywhere;
+      background:var(--component-evidence-readout-background-color, ${panel});
+      padding:var(--component-evidence-readout-padding, 12px); border-radius:var(--radius-sm, 5px);
+      font:var(--typography-evidence-font-size, 13px)/var(--typography-evidence-line-height, 1.5) ${mono};
+    }
+    pre:empty { display:none; }
+    details { margin-top:var(--spacing-sm, 8px); }
+    summary { cursor:pointer; color:${quiet}; min-height:28px; }
+    .changed { animation:settle .2s ease-out; }
+    @keyframes settle { from { transform:translateY(3px); opacity:.75; } to { transform:none; opacity:1; } }
+    @media (prefers-reduced-motion: reduce) { .changed { animation:none; } }
+  </style>
+  <article class="sheet" aria-label="SSSS installation and contract checks">
+    <header>
+      <svg class="mark" viewBox="0 0 40 40" aria-hidden="true">
+        <path d="M10 8h17l3 3M10 16h14l6-5M10 24h14l6-5M10 32h17l3-5M10 8v24"
+          fill="none" stroke="currentColor" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"/>
+      </svg>
+      <div class="title"><h2>SSSS</h2><p class="quiet">Engine, portable skill and project scaffold</p></div>
+      <label>Brain <select id="scope">
+        <option value="auto">Current brain</option><option value="project">Project</option><option value="global">Shared</option>
+      </select></label>
+      <button type="button" id="inspect" class="primary">Check installation</button>
+      <button type="button" id="repair">Repair managed files</button>
+    </header>
+    <dl class="ledger">
+      <div class="slot"><dt>Engine / spec</dt><dd id="engine">—</dd><small id="engine-note"></small></div>
+      <div class="slot"><dt>Portable skill</dt><dd id="skill">—</dd><small id="skill-note"></small></div>
+      <div class="slot"><dt>Project scaffold</dt><dd id="scaffold">—</dd><small id="scaffold-note"></small></div>
+    </dl>
+    <div class="reading" aria-live="polite">
+      <strong id="install-verdict" class="verdict">Not checked yet</strong>
+      <time id="install-time" class="quiet"></time>
+    </div>
+    <div class="groups">
+      <section class="group" aria-labelledby="validate-title">
+        <h3 id="validate-title">Document contract</h3>
+        <form id="validate">
+          <label>Document path <input type="text" name="file" required autocomplete="off"></label>
+          <label>Extension registry path <input type="text" name="extension" autocomplete="off"></label>
+          <button type="button">Validate document</button>
+        </form>
+        <div class="outcome" id="validate-outcome" aria-live="polite"></div>
+      </section>
+      <section class="group" aria-labelledby="registry-title">
+        <h3 id="registry-title">Registry lock</h3>
+        <form id="registry">
+          <label>Lock file path <input type="text" name="lock" required autocomplete="off"></label>
+          <label>Extension registry path <input type="text" name="extension" autocomplete="off"></label>
+          <button type="button">Verify registry</button>
+        </form>
+        <div class="outcome" id="registry-outcome" aria-live="polite"></div>
+      </section>
+      <section class="group" aria-labelledby="scaffold-title">
+        <h3 id="scaffold-title">New SSSS project</h3>
+        <form id="scaffold-form">
+          <label>New directory <input type="text" name="directory" required autocomplete="off"></label>
+          <label>Extension name <input type="text" name="extension" autocomplete="off"></label>
+          <label class="choice"><input type="checkbox" name="with-total-recall"> Include Total Recall wiring</label>
+          <button type="button">Create project</button>
+        </form>
+        <div class="outcome" id="scaffold-outcome" aria-live="polite"></div>
+      </section>
+      <section class="group" aria-labelledby="conformance-title">
+        <h3 id="conformance-title">Engine conformance</h3>
+        <p class="quiet">Runs the canonical reference suite. Allow up to two minutes.</p>
+        <form id="conformance"><button type="button">Run engine conformance</button></form>
+        <div class="outcome" id="conformance-outcome" aria-live="polite"></div>
+      </section>
+    </div>
+  </article>`;
+
+function element(tag, text, attributes = {}) {
+  const node = document.createElement(tag);
+  if (text !== undefined && text !== null) node.textContent = String(text);
+  for (const [name, value] of Object.entries(attributes)) node.setAttribute(name, value);
+  return node;
+}
+
+function fields(entries) {
+  const list = element('dl', undefined, { class: 'fields' });
+  for (const [name, value] of entries) {
+    if (value === undefined || value === null || value === '') continue;
+    list.append(element('dt', name), element('dd', value));
+  }
+  return list;
+}
+
+function findings(title, items) {
+  if (!Array.isArray(items) || !items.length) return [];
+  const list = element('ul', undefined, { class: 'findings' });
+  for (const item of items) {
+    list.append(element('li', typeof item === 'string' ? item : item?.message || JSON.stringify(item)));
+  }
+  return [element('p', title + ' (' + items.length + ')', { class: 'quiet' }), list];
+}
+
+export class SsssHome extends HTMLElement {
+  set host(value) {
+    this.bridge = value;
+    if (this.isConnected && this.shadowRoot) this.inspect();
+  }
+  get host() { return this.bridge; }
+
+  connectedCallback() {
+    if (!this.shadowRoot) {
+      this.attachShadow({ mode: 'open' }).innerHTML = page;
+      this.find('inspect').onclick = () => this.inspect();
+      this.find('scope').onchange = () => this.inspect();
+      this.find('repair').onclick = () => this.inspect('repair');
+      this.bindForm('validate', 'validate', result => this.showValidation(result));
+      this.bindForm('registry', 'registry', result => this.showRegistry(result));
+      this.bindForm('scaffold-form', 'scaffold', result => this.showScaffold(result));
+      this.bindForm('conformance', 'conformance', result => this.showConformance(result));
+    }
+    this.inspect();
+  }
+
+  find(id) { return this.shadowRoot.getElementById(id); }
+
+  bindForm(id, operation, show) {
+    const form = this.find(id);
+    // The dashboard frame intentionally disables native form submission.
+    const run = () => {
+      if (!form.reportValidity()) return;
+      const args = [];
+      for (const [name, value] of new FormData(form)) {
+        if (name === 'with-total-recall') args.push('--with-total-recall');
+        else if (String(value).trim()) args.push('--' + name, String(value).trim());
+      }
+      this.perform(operation, args, this.find(operation === 'scaffold' ? 'scaffold-outcome' : id + '-outcome'), show);
+    };
+    form.querySelector('button').onclick = run;
+    form.onkeydown = event => {
+      if (event.key !== 'Enter' || event.isComposing || !event.target.matches('input[type="text"]')) return;
+      event.preventDefault();
+      run();
+    };
+  }
+
+  // Runs one operation through the authenticated bridge and returns its parsed verdict.
+  async run(operation, args) {
+    if (!this.host?.run) throw new Error('Command bridge unavailable. Open this Home from the Total Recall dashboard.');
+    let reply;
+    try {
+      reply = await this.host.run(operation, [...args, '--json']);
+    } catch (error) {
+      // A failed check emits one JSON verdict followed by human-readable stderr.
+      for (const line of String(error?.message || '').split('\n')) {
+        if (!line.startsWith('{')) continue;
+        try {
+          const verdict = JSON.parse(line);
+          if (verdict?.ok === false) return verdict;
+        } catch { /* A bridge error may carry no owner verdict. */ }
+      }
+      throw error;
+    }
+    const result = typeof reply === 'string' ? JSON.parse(reply) : reply;
+    if (typeof result?.ok !== 'boolean') throw new Error('SSSS returned no verdict.');
+    return result;
+  }
+
+  lock(busy) {
+    this.busy = busy;
+    for (const control of this.shadowRoot.querySelectorAll('button,select')) control.disabled = busy;
+  }
+
+  async perform(operation, args, outcome, show) {
+    if (this.busy) return;
+    this.lock(true);
+    outcome.replaceChildren(element('p', 'Running…', { class: 'quiet' }));
+    let nodes;
+    try {
+      const result = await this.run(operation, args);
+      nodes = show(result);
+    } catch (error) {
+      nodes = [element('p', 'Unavailable', { class: 'verdict', 'data-tone': 'fail' }), element('p', error.message, { class: 'path' })];
+    } finally {
+      this.lock(false);
+    }
+    const stamp = new Date().toISOString();
+    outcome.replaceChildren(...nodes, element('time', stamp, { class: 'path', datetime: stamp }));
+    outcome.classList.remove('changed');
+    void outcome.offsetWidth;
+    outcome.classList.add('changed');
+  }
+
+  verdict(ok, pass, fail) {
+    return element('p', ok ? pass : fail, { class: 'verdict', 'data-tone': ok ? 'pass' : 'fail' });
+  }
+
+  showValidation(result) {
+    return [
+      this.verdict(result.ok, 'Valid', 'Invalid'),
+      fields([['type', result.type], ['error', result.error]]),
+      ...findings('Errors', result.errors),
+      ...findings('Warnings', result.warnings),
+    ];
+  }
+
+  showRegistry(result) {
+    return [
+      this.verdict(result.ok, 'Lock matches the effective registry', 'Lock does not match'),
+      fields([
+        ['specVersion', result.specVersion],
+        ['expected_integrity', result.expected_integrity],
+        ['actual_integrity', result.actual_integrity === null ? 'none in lock' : result.actual_integrity],
+        ['error', result.error],
+      ]),
+    ];
+  }
+
+  showScaffold(result) {
+    const nodes = [
+      this.verdict(result.ok, 'Project created', 'Project not created'),
+      fields([
+        ['directory', result.directory],
+        ['version', result.version],
+        ['files', Array.isArray(result.files) ? result.files.length : undefined],
+        ['error', result.error],
+      ]),
+    ];
+    if (Array.isArray(result.files) && result.files.length) {
+      const list = element('details');
+      list.append(element('summary', 'Generated files'), element('pre', result.files.join('\n')));
+      nodes.push(list);
+    }
+    return nodes;
+  }
+
+  showConformance(result) {
+    return [
+      this.verdict(result.ok, 'Conformance passed', 'Conformance failed'),
+      fields([['exitCode', result.exitCode], ['signal', result.signal], ['error', result.error]]),
+      element('pre', result.output || '', { tabindex: '0' }),
+    ];
+  }
+
+  paintLedger(result) {
+    this.find('engine').textContent = result?.version ? result.version + ' / ' + result.specVersion : '—';
+    this.find('engine-note').textContent = result?.error || '';
+    for (const part of ['skill', 'scaffold']) {
+      const item = result?.[part];
+      const value = this.find(part);
+      value.textContent = item ? (item.ok ? item.files + ' files verified' : 'Needs repair') : '—';
+      if (item) value.dataset.tone = item.ok ? 'pass' : 'fail';
+      else delete value.dataset.tone;
+      this.find(part + '-note').textContent = item ? (item.error || item.path || '') : '';
+    }
+  }
+
+  async inspect(operation = 'status') {
+    if (this.busy || !this.shadowRoot) return;
+    const verdict = this.find('install-verdict');
+    const time = this.find('install-time');
+    this.paintLedger(null);
+    this.lock(true);
+    verdict.textContent = operation === 'repair' ? 'Repairing…' : 'Checking…';
+    delete verdict.dataset.tone;
+    try {
+      const result = await this.run(operation, ['--scope', this.find('scope').value]);
+      this.paintLedger(result);
+      verdict.dataset.tone = result.ok ? 'pass' : 'fail';
+      verdict.textContent = result.ok
+        ? (operation === 'repair' ? 'Repaired and verified' : 'Installation complete and current')
+        : 'Installation needs attention';
+      const notes = [];
+      if (result.error) notes.push(result.error);
+      if (result.recoveredFrom) notes.push('Previous scaffold kept at ' + result.recoveredFrom);
+      if (result.replacedLink) notes.push('Replaced link ' + result.replacedLink.path + ' → ' + result.replacedLink.target);
+      if (notes.length) this.find('engine-note').textContent = notes.join('. ');
+    } catch (error) {
+      verdict.dataset.tone = 'fail';
+      verdict.textContent = 'Reading unavailable: ' + error.message;
+    } finally {
+      this.lock(false);
+    }
+    const stamp = new Date().toISOString();
+    time.textContent = stamp;
+    time.dateTime = stamp;
+    verdict.classList.remove('changed');
+    void verdict.offsetWidth;
+    verdict.classList.add('changed');
+  }
+}
+
+if (!customElements.get('tr-ssss-home')) customElements.define('tr-ssss-home', SsssHome);

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

@@ -4,6 +4,8 @@ This is the maintained operations reference for Total Recall 3.39.1 source. Core
 
 Run `startup check --json`, `status --json`, `daemon status`, and relevant plugin status/help. Check configured backend health, authenticated instructions access, selected project/brain, daemon identity, SSSS tooling and freshness separately. A listening port or process is not health. `startup ensure` starts only configured managed stopped services; preserve running/unknown/foreign services. Scope/auth failures are not transport retries.
 
+`startup check` and `brief` also show what needs attention without affecting readiness: a dashboard bundle older than its frontend sources, and each installed plugin's `startup_check` (for example the git plugin's `unmerged`: branches and worktrees whose work is not in the default branch). Act on those lines; land or report every branch and worktree `total-recall git unmerged` lists before ending work. A server running from a source checkout rebuilds a missing or stale dashboard in the background, keeps serving the current bundle until the new one is complete, never installs dependencies, and reports its state in `/health` `dashboard`.
+
 Before tests/build/release, read the owning test/code-quality skills and actual repository config. Use the sanctioned remote test node, resolved by Total Recall. Run one background checker at a time; honor live locks and never delete another job's lock. Hash/synchronize the exact tested sources, inspect raw completion and exit status, and clean owned test fixtures/jobs. Run full suites for significant changes. Browser mocks do not certify live provider delivery. Never infer publication from a local version bump, a package build or a wrapper exit.
 
 Use the five project files plus source OpenWiki hubs throughout work. Append timestamped actions/failures/verification to the tracker's bottom Action Log. Keep implementation, tests, gates, package, release, deployed source and live evidence distinct. No deferred required work without the user's instruction.
@@ -16,7 +18,7 @@ Publication/deployment use the owning push/deploy procedures when authorized. Sh
 
 Use `brain status` to check the current project and physical global storage. Preview `brain relocate-global <dir>` before adding `--apply`. The destination must be a new private directory outside Git on the same filesystem as home. The home skills path links to the relocated tree. Keep repository brains in their own directories.
 
-Run normal preflight from home for global orchestration. Pass a repository working directory when routing repository work through Meta Harness. Use `plugin copies` to audit old project copies of shared defaults. `--apply` deletes verified bundled matches. Add `--archive-stale` to retain differing older copies in the replacement archive and use the shared versions.
+Run normal preflight from home for global orchestration. Pass a repository working directory when routing repository work through Metaharness. Use `plugin copies` to audit old project copies of shared defaults. `--apply` deletes verified bundled matches. Add `--archive-stale` to retain differing older copies in the replacement archive and use the shared versions.
 
 ## Optional developer API
 

package/src/cli/agent.mjs

@@ -31,7 +31,7 @@ Options:
   --allow-unknown-auth     Explicitly permit a harness without a verified login probe
 
 Auth:
-  The Meta Harness owner probes login and resolves only adapter-declared credentials through auth.
+  The Metaharness owner probes login and resolves only adapter-declared credentials through auth.
 
 Available Harnesses:
   agy, claude, codex, dsh, hermes, openclaw

package/src/cli/api.mjs

@@ -41,7 +41,7 @@ function parse(argv) {
   return out;
 }
 
-async function call(method, routePath, { query, data }) {
+export async function callApi(method, routePath, { query = {}, data } = {}) {
   const { url, token } = brainConnection();
   const qs = new URLSearchParams(query).toString();
   const res = await fetch(`${url.replace(/\/$/, '')}${routePath}${qs ? `?${qs}` : ''}`, {
@@ -97,7 +97,7 @@ export default async function apiCli(argv = []) {
       console.error('Usage: total-recall api call <METHOD> </api/path> [--data json] [--query k=v]');
       process.exit(1);
     }
-    return finish(await call(method, routePath, opts), opts);
+    return finish(await callApi(method, routePath, opts), opts);
   }
 
   const group = first;
@@ -121,7 +121,7 @@ export default async function apiCli(argv = []) {
   route.params.forEach((name, i) => {
     p = p.replace(`:${name}`, encodeURIComponent(rest[i]));
   });
-  return finish(await call(route.method, p, opts), opts);
+  return finish(await callApi(route.method, p, opts), opts);
 }
 
 function finish(r, opts) {

package/src/cli/brief.mjs

@@ -177,6 +177,9 @@ const { queryHarnessUsage } = await import('../core/meta-harness.mjs');
 const harnesses = await queryHarnessUsage().catch(() => []);
 const warnings = [];
 if (!runtime.ready) warnings.push('Shared runtime readiness failed or unknown: total-recall startup check --json.');
+// Unfinished merges, a stale dashboard and other plugin startup checks.
+const { startupFindings } = await import('./startup.mjs');
+for (const line of startupFindings(runtime)) warnings.push(line);
 if (!project?.project_id) warnings.push('No project brain here (total-recall init) — memory, secrets and rules are global-only.');
 if (secrets.rotation_due && secrets.rotation_due !== 0) warnings.push(`Secrets overdue for rotation: ${secrets.rotation_due} (total-recall auth secret rotation-due).`);
 if (secrets.shared_values && secrets.shared_values !== 0) warnings.push(`Credential values reused across keys/apps: ${secrets.shared_values} group(s) (total-recall auth secret shared).`);

package/src/cli/command.mjs

@@ -247,21 +247,59 @@ function existingTag(file, key) {
   try { return fs.readFileSync(file, 'utf8').match(new RegExp(`^// @${key} (.+)$`, 'm'))?.[1] || undefined; } catch { return undefined; }
 }
 
+/** Where the background recompile records its outcome: <agentDir>/state and <agentDir>/logs. */
+export function compileRecordPaths(isGlobal) {
+  const agentDir = path.dirname(resolveTargetDir(isGlobal));
+  return {
+    status: path.join(agentDir, 'state', 'command-compile.json'),
+    log: path.join(agentDir, 'logs', 'command-compile.log'),
+  };
+}
+
+// Runs in the detached child: compile, then record the exit code and output.
+const COMPILE_RECORDER = `
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const [cli, layer, statusFile, logFile] = process.argv.slice(1);
+const startedAt = new Date().toISOString();
+const r = spawnSync(process.execPath, [cli, 'compile', layer], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+const code = r.status === null ? 1 : r.status;
+fs.writeFileSync(logFile, (r.stdout || '') + (r.stderr || '') + (r.error ? String(r.error) + '\\n' : ''));
+const record = { ok: code === 0, code, signal: r.signal || null, layer, startedAt, finishedAt: new Date().toISOString(), log: logFile };
+fs.writeFileSync(statusFile + '.tmp', JSON.stringify(record, null, 2));
+fs.renameSync(statusFile + '.tmp', statusFile);
+`;
+
 /**
  * Composable instructions: the surfaces list every command, so any change to
  * the command set recompiles them (project layer, or every project for global).
+ * A global compile takes minutes, so it runs in the background; its exit code and
+ * output are recorded, and the next `command` call reports a failure.
  */
 export function recompileSurfaces(isGlobal) {
   if (process.env.TR_COMMAND_NO_COMPILE === '1' || !process.argv[1]) return;
   try {
-    const child = spawn(process.execPath, [process.argv[1], 'compile', isGlobal ? '--global' : '--project'], { detached: true, stdio: 'ignore' });
+    const { status, log } = compileRecordPaths(isGlobal);
+    fs.mkdirSync(path.dirname(status), { recursive: true });
+    fs.mkdirSync(path.dirname(log), { recursive: true });
+    const child = spawn(process.execPath, ['-e', COMPILE_RECORDER, process.argv[1], isGlobal ? '--global' : '--project', status, log], { detached: true, stdio: 'ignore' });
     child.unref();
-    console.log('  ⏳ Instruction surfaces recompiling in the background (command list updated).');
+    console.log(`  ⏳ Instruction surfaces recompiling in the background (command list updated). Outcome: ${status}`);
   } catch (error) {
     console.warn(`  ⚠️  Command saved, but surface recompile failed to start: ${error.message}`);
+    process.exitCode = 1;
   }
 }
 
+/** Report a failed background recompile; returns the record when it failed. */
+export function reportFailedCompile(isGlobal, out = console.warn) {
+  let record;
+  try { record = JSON.parse(fs.readFileSync(compileRecordPaths(isGlobal).status, 'utf8')); } catch { return null; }
+  if (record.ok) return null;
+  out(`  ❌ The last instruction-surface recompile (${record.layer}, ${record.finishedAt}) failed with exit ${record.code}. Surfaces may not list current commands. Log: ${record.log}. Run 'total-recall compile ${record.layer}' to retry.`);
+  return record;
+}
+
 /**
  * Register every `commands` entry of an installed plugin as a composable command.
  * A command that already exists and was generated from this plugin is refreshed;
@@ -319,6 +357,7 @@ export default async function commandCmd(rawArgs = []) {
 
   const action = cleanArgs[0];
   const name = cleanArgs[1];
+  if (process.env.TR_COMMAND_NO_COMPILE !== '1') reportFailedCompile(isGlobal);
 
   if (!action || action === '--help' || action === '-h') {
     printHelp();

package/src/cli/config.mjs

@@ -152,6 +152,8 @@ export default async function configCommand(args) {
   Commands:
     get [key]      Retrieve the value of a configuration key. If key is omitted, lists all keys.
     set <key> <v>  Set the value of a configuration key. Converts inputs to correct type.
+    drawer <right|bottom>                 Read a workspace drawer as JSON
+    drawer <right|bottom> --file <json>   Save a workspace drawer configuration
 
   Options:
     --global       Explicitly target the global brain configuration (~/.agent/)
@@ -177,6 +179,20 @@ export default async function configCommand(args) {
     return;
   }
 
+  if (command === 'drawer') {
+    const { readDrawerConfig, writeDrawerConfig } = await import('../core/workspace-drawers.mjs');
+    const [, edge, fileFlag, file] = remainingArgs;
+    if (!edge || (remainingArgs.length !== 2 && (remainingArgs.length !== 4 || fileFlag !== '--file' || !file))) {
+      throw new Error('Usage: total-recall config drawer <right|bottom> [--file <json>] [--global|--project]');
+    }
+    const brain = layer === 'auto' && process.env.TR_BRAIN ? path.resolve(process.env.TR_BRAIN) : resolveBrainDir(layer);
+    const current = readDrawerConfig(brain, edge);
+    if (file && fs.statSync(file).size > 512 * 1024) throw new Error('Drawer file exceeds 512 KiB.');
+    const result = file ? await writeDrawerConfig(brain, edge, JSON.parse(fs.readFileSync(file, 'utf8')), current.version) : current;
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
   const brainDir = resolveBrainDir(layer);
   const configDir = path.join(brainDir, 'config');
   const securityPath = path.join(configDir, 'security.yml');

package/src/cli/connect.mjs

@@ -5,6 +5,7 @@ import { agentDir as configAgentDir, brainDir as configBrainDir, xdgConfigHome,
 import { fileURLToPath } from 'node:url';
 import { resolveAgentDir, getBothBrains, detectProjectBrain } from './agent-dir.mjs';
 import { discoverRepoSkills, projectSkillsAsCommands } from './skill-projection.mjs';
+import { writeBrainConnection } from '../core/memory-brain.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Resolve templates dir relative to this file (src/cli/ → ../../templates/)
@@ -379,13 +380,7 @@ function readInstructions(cwd, agentDir) {
 
 function ensureBrainConfig(brainDir, opts) {
   if (!opts.brain) return null;
-  const configDir = path.join(brainDir, 'config');
-  fs.mkdirSync(configDir, { recursive: true });
-  const config = { url: opts.brain };
-  if (opts.token) config.token = opts.token;
-  const filePath = path.join(configDir, 'brain.json');
-  fs.writeFileSync(filePath, JSON.stringify(config, null, 2));
-  return filePath;
+  return writeBrainConnection(brainDir, { url: opts.brain, token: opts.token || undefined });
 }
 
 function registerClient(brainDir, clientName, preset, projectionPath) {