@polderlabs/bizar 5.4.0 → 5.5.0

package/cli/service-env.mjs

@@ -0,0 +1,139 @@
+/**
+ * cli/service-env.mjs
+ *
+ * v5.x — Central env file builder for the Bizar service.
+ *
+ * Produces the content for `~/.config/bizar/service.env` (mode 0600),
+ * which is sourced by the systemd/launchd service and the headroom companion.
+ *
+ * All BIZAR_* vars are written here so the service has a consistent view
+ * of the environment. Values already present in `process.env` are honoured
+ * (never overwritten); everything else gets a safe default.
+ *
+ * Public API:
+ *   buildServiceEnvFile({ bizarHome, repoPath, options })
+ *     → string  (the env file content, ready to write)
+ *   defaultBizarEnv()
+ *     → Record<string, string>  (all defaults merged)
+ */
+
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+/** Default values for every BIZAR_* env var. */
+export function defaultBizarEnv() {
+  const home = homedir();
+  return {
+    BIZAR_HOME: join(home, '.config', 'bizar'),
+    BIZAR_REPO: '',
+    BIZAR_DASHBOARD_PORT: '4097',
+    BIZAR_DASHBOARD_HOST: '127.0.0.1',
+    BIZAR_LOG_LEVEL: 'info',
+    BIZAR_HEADROOM_AUTOSTART: '1',
+    BIZAR_LIGHTRAG_AUTOSTART: '1',
+    BIZAR_MEMORY_VAULT: join(home, '.bizar_memory'),
+    OPENCODE_SERVER_PASSWORD: '',
+  };
+}
+
+/**
+ * Generate a fresh `OPENCODE_SERVER_PASSWORD` using the platform's
+ * secure random source.
+ */
+function generatePassword() {
+  try {
+    if (process.platform === 'win32') {
+      // PowerShell
+      const out = execSync(
+        'powershell -Command "[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))"',
+        { encoding: 'utf8', timeout: 5000 },
+      );
+      return out.trim().replace(/\n/g, '');
+    }
+    // Linux/macOS
+    const out = execSync('openssl rand -hex 32', { encoding: 'utf8', timeout: 5000 });
+    return out.trim();
+  } catch {
+    // Fallback: rough approximation using /dev/urandom
+    try {
+      const { readFileSync } = require?.('node:fs') ?? (() => { throw new Error('no fs'); })();
+      const fd = require?.('node:fs')?.openSync?.('/dev/urandom', 'r');
+      if (fd !== undefined) {
+        const buf = Buffer.alloc(32);
+        require('node:fs').readSync(fd, buf, 0, 32);
+        require('node:fs').closeSync?.(fd);
+        return buf.toString('hex');
+      }
+    } catch { /* ignore */ }
+    // Last-resort: use Date.now() + PID — not great but better than nothing
+    return `${Date.now()}-${process.pid}`.split('').reverse().join('').slice(0, 64);
+  }
+}
+
+/**
+ * Build the service.env file content.
+ *
+ * @param {object} opts
+ * @param {string} [opts.bizarHome]   – default: ~/.config/bizar
+ * @param {string} [opts.repoPath]    – absolute path to the repo root
+ * @param {boolean} [opts.headroomAutoStart] – default: true
+ * @param {boolean} [opts.lightragAutoStart] – default: true
+ * @returns {string} env file content (does NOT write to disk)
+ */
+export function buildServiceEnvFile({ bizarHome, repoPath, headroomAutoStart = true, lightragAutoStart = true } = {}) {
+  const home = homedir();
+  const defaults = defaultBizarEnv();
+
+  const env = {
+    BIZAR_HOME:        bizarHome    || defaults.BIZAR_HOME,
+    BIZAR_REPO:        repoPath     || process.env.BIZAR_REPO || '',
+    BIZAR_DASHBOARD_PORT:  process.env.BIZAR_DASHBOARD_PORT  || defaults.BIZAR_DASHBOARD_PORT,
+    BIZAR_DASHBOARD_HOST:  process.env.BIZAR_DASHBOARD_HOST  || defaults.BIZAR_DASHBOARD_HOST,
+    BIZAR_LOG_LEVEL:       process.env.BIZAR_LOG_LEVEL       || defaults.BIZAR_LOG_LEVEL,
+    BIZAR_HEADROOM_AUTOSTART: String(
+      process.env.BIZAR_HEADROOM_AUTOSTART !== undefined
+        ? (process.env.BIZAR_HEADROOM_AUTOSTART === '1' || process.env.BIZAR_HEADROOM_AUTOSTART === 'true' ? '1' : '0')
+        : (headroomAutoStart ? '1' : '0')
+    ),
+    BIZAR_LIGHTRAG_AUTOSTART: String(
+      process.env.BIZAR_LIGHTRAG_AUTOSTART !== undefined
+        ? (process.env.BIZAR_LIGHTRAG_AUTOSTART === '1' || process.env.BIZAR_LIGHTRAG_AUTOSTART === 'true' ? '1' : '0')
+        : (lightragAutoStart ? '1' : '0')
+    ),
+    BIZAR_MEMORY_VAULT: process.env.BIZAR_MEMORY_VAULT || defaults.BIZAR_MEMORY_VAULT,
+  };
+
+  // Always add ~/.local/bin to PATH for uv tool binaries (lightrag-server, etc.)
+  const localBin = join(home, '.local', 'bin');
+  const existingPath = process.env.PATH || '/usr/local/bin:/usr/bin:/bin';
+  env.PATH = existingPath.includes(localBin) ? existingPath : `${localBin}:${existingPath}`;
+
+  // OPENCODE_SERVER_PASSWORD: honour existing env, otherwise generate fresh
+  const password = process.env.OPENCODE_SERVER_PASSWORD
+    || process.env.BIZAR_REDACT_PASSWORD === '1' ? ''
+    : (process.env.OPENCODE_SERVER_PASSWORD || generatePassword());
+  if (password) {
+    env.OPENCODE_SERVER_PASSWORD = password;
+  }
+
+  const lines = [
+    '# Generated by bizar service install — edit with care.',
+    `# Created: ${new Date().toISOString()}`,
+    `BIZAR_HOME=${env.BIZAR_HOME}`,
+    `BIZAR_REPO=${env.BIZAR_REPO}`,
+    `PATH=${env.PATH}`,
+    `BIZAR_DASHBOARD_PORT=${env.BIZAR_DASHBOARD_PORT}`,
+    `BIZAR_DASHBOARD_HOST=${env.BIZAR_DASHBOARD_HOST}`,
+    `BIZAR_LOG_LEVEL=${env.BIZAR_LOG_LEVEL}`,
+    `BIZAR_HEADROOM_AUTOSTART=${env.BIZAR_HEADROOM_AUTOSTART}`,
+    `BIZAR_LIGHTRAG_AUTOSTART=${env.BIZAR_LIGHTRAG_AUTOSTART}`,
+    `BIZAR_MEMORY_VAULT=${env.BIZAR_MEMORY_VAULT}`,
+  ];
+  if (password) {
+    lines.push(`OPENCODE_SERVER_PASSWORD=${password}`);
+  }
+
+  return lines.join('\n') + '\n';
+}

package/cli/service.mjs

@@ -377,6 +377,24 @@ export async function runService(sub, _rest) {
     }
     return;
   }
+  if (sub === 'restart') {
+    // v5.x — issue #7. Used by `bizar update` to make sure the service
+    // picks up the freshly-installed binary without leaving the old one
+    // running with stale inodes.
+    const { restartService } = await import('./service-controller.mjs');
+    const force = Array.isArray(_rest) && (_rest.includes('--force') || _rest.includes('-f'));
+    const dryRun = Array.isArray(_rest) && (_rest.includes('--dry-run'));
+    const r = restartService({ force, dryRun });
+    if (r.ok) {
+      console.log('[bizar-service] restarted.');
+      if (r.unitPath) console.log(`[bizar-service] unit: ${r.unitPath}`);
+      if (r.note) console.log(`[bizar-service] ${r.note}`);
+    } else {
+      console.error(`[bizar-service] restart failed: ${r.error}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
   if (sub === 'uninstall') {
     const { uninstallService } = await import('./service-controller.mjs');
     const force = Array.isArray(_rest) && (_rest.includes('--force') || _rest.includes('-f'));
@@ -400,6 +418,7 @@ export async function runService(sub, _rest) {
     bizar service logs
     bizar service follow
     bizar service install [--force] [--dry-run]
+    bizar service restart [--force] [--dry-run]
     bizar service uninstall [--force]
 
   Description:
@@ -408,6 +427,10 @@ export async function runService(sub, _rest) {
     user login. install is idempotent — when the on-disk unit matches
     the desired content, it returns without restarting the service.
     Pass --force to overwrite or to drop a stale registration.
+
+    restart stops the daemon, reinstalls the unit, and starts it again.
+    Used by \`bizar update\` to make sure the service picks up the new
+    code without leaving the old binary running.
   `);
 }
 

package/config/agents/_shared/AGENT_BASELINE.md

@@ -223,10 +223,10 @@ Bizar stores long-term memory in a **project memory vault** — Markdown files m
 
 ### Session Start
 
-1. Run `bizar memory search "<topic>"` to find relevant prior context.
-2. Read project-level index entries: `bizar memory search "project_index"` or browse notes with `bizar memory list`.
-3. Read the most recent session summaries: `bizar memory search "session_summary"`.
-4. If a relevant decision note exists, read it by path with `cat <vault-path>/projects/<projectId>/decisions/<name>.md`.
+1. Run `bizar_memory_search({ query: "<topic>" })` to find relevant prior context (the plugin's session-start hook also auto-injects relevant memory at session creation).
+2. Read project-level index entries: `bizar_memory_search({ query: "project_index" })` or browse notes with `bizar_memory_list({})`.
+3. Read the most recent session summaries: `bizar_memory_search({ query: "session_summary" })`.
+4. If a relevant decision note exists, read it by path with `bizar_memory_read({ path: "projects/<projectId>/decisions/<name>.md" })`.
 
 ### During Work
 
@@ -388,7 +388,7 @@ The following rules apply to every agent at all times. They are the single sourc
 - Bizar does not have a single knowledge cutoff shared by all models. Subagents may run on DeepSeek V4 Flash (opencode-zen, free tier) or MiniMax M2.7 / M3, each with their own training window.
 - For facts that change quickly (current positions, prices, breaking news) or anything that could have changed recently, **search before answering**: use `websearch` and `webfetch` or delegate to `@mimir` for deep research.
 - For stable technical knowledge (language semantics, well-established APIs, mathematical truths), answer directly without search.
-- Default to running `bizar memory search "<topic>"` at session start to retrieve prior project context before answering anything project-specific.
+- Default to running `bizar_memory_search({ query: "<topic>" })` at session start to retrieve prior project context before answering anything project-specific. (The plugin also auto-injects relevant memory via the session-start hook — agents don't need to manually call this if the hook is active.)
 - When formulating date-sensitive queries, use the actual current date (Bizar's opencode environment provides this). Do not hardcode years.
 - Do not over-rely on memory; if uncertain, search. Confabulating costs the user more than searching.
 
@@ -629,7 +629,7 @@ Rules:
 The memory vault uses three namespaces: `projects/<projectId>/` (project-specific), `global/bizar/` (cross-project), and `users/<userId>/` (personal). Run `bizar memory status` from the project root to see the active mode and resolved path. The user has been working on this project — their notes contain the real context, the gotchas, the failed approaches, the preferred patterns. **Read the relevant vault entries before making any non-trivial decision.**
 
 **When to read:**
-- At the start of every session: `bizar memory search "<topic>"` for relevant notes.
+- At the start of every session: the plugin's session-start hook auto-injects relevant memory context. You can also call `bizar_memory_search({ query: "<topic>" })` explicitly.
 - Before any non-trivial implementation decision: check for ADRs or design notes.
 - When you're about to suggest something the user has already tried.
 - When the codebase feels like it's working around something you don't understand.

package/install.sh

@@ -1,11 +1,17 @@
 #!/usr/bin/env bash
 #
-# install.sh — Cross-platform BizarHarness installer (v4.4.7 — thin shell wrapper).
+# install.sh — Cross-platform BizarHarness installer (v5.x — thin shell wrapper).
 #
-# v4.4.7 — Unified installer/updater. Almost all logic now lives in
-# `cli/provision.mjs:runProvision`, which is shared between `bizar install`
-# and `bizar update`. This bash script exists only for the platform-specific
-# steps that need sudo + a system package manager:
+# v5.x — Updated for issue #7. The install/update flow now:
+#   1. On first install: registers the system service that auto-starts
+#      the dashboard (`bizar service install`).
+#   2. On update: stops the running service before files are replaced
+#      (`bizar service stop` → npm upgrade → `bizar service restart`).
+#
+# Almost all logic still lives in `cli/provision.mjs:runProvision`, which
+# is shared between `bizar install` and `bizar update`. This bash script
+# exists only for the platform-specific steps that need sudo + a system
+# package manager:
 #
 #   - Linux:  ensure node is installed (apt/dnf/pacman/zypper), install uv,
 #             python3.12, jq, gh, browser-harness, Chrome runtime libs.
@@ -20,7 +26,7 @@
 #   --non-interactive   skip prompts (CI safe)
 #   --dry-run           print actions, make no changes
 #   --force             overwrite existing files
-#   --update            this is a re-install (currently a no-op alias)
+#   --update            this is a re-install
 #   --mode=install|update|install-only-system
 #                       install = full flow (the default)
 #                       update  = alias for install (provisioner auto-detects)
@@ -145,6 +151,21 @@ ensure_node() {
       action "Installing Node.js via zypper..."
       dry $SUDO zypper install -y nodejs20 npm20
       ;;
+    alpine)
+      action "Installing Node.js via apk..."
+      dry $SUDO apk add --no-cache nodejs npm
+      ;;
+    nixos)
+      action "Detected NixOS — Node.js must be installed via nix-shell"
+      warn "Run the following, then re-run this installer:"
+      warn "  nix-shell -p nodejs python3 jq gh git"
+      warn "  node cli/provision.mjs"
+      exit 0
+      ;;
+    void)
+      action "Installing Node.js via xbps..."
+      dry $SUDO xbps-install -S nodejs
+      ;;
     *)
       err "Unsupported distro: $ID"
       err "Install Node.js 18+ manually: https://nodejs.org/"
@@ -168,6 +189,29 @@ check_deps() {
   fi
 }
 
+install_lightrag() {
+  # LightRAG is optional but recommended. Install via uv tool.
+  # uv tools install to ~/.local/bin/ — ensure that's on PATH.
+  if [ -d "$HOME/.local/bin" ] && [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
+    export PATH="$HOME/.local/bin:$PATH"
+  fi
+  if have_cmd lightrag-server; then
+    note "LightRAG $(lightrag-server --version 2>/dev/null || echo 'server') present"
+    return 0
+  fi
+  action "Installing LightRAG via uv tool..."
+  if dry uv tool install "lightrag-hku[api]" 2>&1; then
+    note "LightRAG installed"
+    # Verify reachable
+    if [ -f "$HOME/.local/bin/lightrag-server" ]; then
+      note "LightRAG binary found at ~/.local/bin/"
+    fi
+  else
+    warn "LightRAG install failed — the memory graph will not be available"
+    warn "    Install later: uv tool install \"lightrag-hku[api]\""
+  fi
+}
+
 install_missing_deps_linux() {
   . /etc/os-release 2>/dev/null || return 0
   sudo_if_needed
@@ -206,7 +250,32 @@ install_missing_deps_linux() {
         note "uv installed via astral.sh"
       fi
       ;;
+    alpine)
+      action "Installing uv, python3, jq, gh via apk..."
+      dry $SUDO apk add --no-cache python3 py3-pip jq git curl
+      if ! have_cmd uv; then
+        dry curl -LsSf https://astral.sh/uv/install.sh | sh
+        note "uv installed via astral.sh"
+      fi
+      ;;
+    void)
+      action "Installing uv, python3, jq, gh via xbps..."
+      dry $SUDO xbps-install -S python3 python3-pip jq git curl
+      if ! have_cmd uv; then
+        dry curl -LsSf https://astral.sh/uv/install.sh | sh
+        note "uv installed via astral.sh"
+      fi
+      ;;
+    nixos)
+      warn "NixOS detected — LightRAG and other uv tools require manual setup"
+      warn "  After nix-shell: nix-shell -p nodejs python3 jq gh git"
+      warn "  Then run: uv tool install \"lightrag-hku[api]\""
+      warn "  And re-run this installer: node cli/provision.mjs"
+      return 0
+      ;;
   esac
+  # LightRAG via uv tool (requires uv to be on PATH)
+  install_lightrag
 }
 
 install_missing_deps_macos() {
@@ -222,6 +291,8 @@ install_missing_deps_macos() {
   fi
   action "Installing uv, python3.12, jq, gh via brew..."
   dry brew install uv jq gh 2>/dev/null || true
+  # LightRAG via uv tool (requires uv to be on PATH)
+  install_lightrag
 }
 
 # ── Service registration (delegated to Node) ────────────────────────────────
@@ -230,6 +301,12 @@ install_service() {
   # The unified provisioner does this via `cli/service-controller.mjs`.
   # We still call it from here because the bash script may run standalone
   # (e.g. for first-boot provisioning before the npm package is set up).
+  #
+  # v5.x — issue #7: On first install, register the service so the
+  # dashboard auto-starts at login. On update, the running service is
+  # stopped by the provisioner before files are replaced, then restarted
+  # by the provisioner after — see cli/provision.mjs. This function
+  # covers the FIRST install path only.
   local bin="$REPO_DIR/cli/bin.mjs"
   if [ ! -f "$bin" ]; then
     warn "cli/bin.mjs not found — service registration deferred"
@@ -240,6 +317,10 @@ install_service() {
     dim "  would run: node $bin service install"
     return 0
   fi
+  if [ "$UPDATE_MODE" -eq 1 ]; then
+    dim "  update mode: service restart is handled by the Node provisioner"
+    return 0
+  fi
   if ! node "$bin" service install 2>&1; then
     warn "service registration had issues — see output above"
     dim "    manual command: node $bin service install"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polderlabs/bizar",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "Norse-pantheon multi-agent system for opencode — 13 agents across 4 cost tiers with cost-aware routing, plans, and a configurable agent harness. v4 ships as a single npm package bundling the dashboard server, opencode plugin, and typed SDK.",
   "type": "module",
   "bin": {

package/plugins/bizar/index.ts

@@ -119,8 +119,18 @@ import { createBgSpawnTool } from "./src/tools/bg-spawn.js";
 import { createBgStatusTool } from "./src/tools/bg-status.js";
 import { createBgCollectTool } from "./src/tools/bg-collect.js";
 import { createBgKillTool } from "./src/tools/bg-kill.js";
+import { createBgPauseTool } from "./src/tools/bg-pause.js";
+import { createBgResumeTool } from "./src/tools/bg-resume.js";
+import { createBgReportProgressTool } from "./src/tools/bg-report-progress.js";
+import { createBgSendMessageTool } from "./src/tools/bg-send-message.js";
 import { createBgGetCommentsTool } from "./src/tools/bg-get-comments.js";
 import { createOpenKbTool } from "./src/tools/open-kb.js";
+import { createMemorySearchTool } from "./src/tools/memory-search.js";
+import { createMemoryReadTool } from "./src/tools/memory-read.js";
+import { createMemoryWriteTool } from "./src/tools/memory-write.js";
+import { createMemoryListTool } from "./src/tools/memory-list.js";
+import { createMemoryInject, popMemoryContext } from "./src/hooks/memory-inject.js";
+import { createMemoryWriteOnEnd } from "./src/hooks/memory-write-on-end.js";
 
 // v0.4.0 — visual plan flow: settings, slash commands, plan tools
 import { SettingsStore } from "./src/settings.js";
@@ -360,10 +370,25 @@ interface RuntimeContext {
   seenMessageIds: Map<string, Set<string>>;
   /** sessionID → pending system-transform message, set at warn/escalate. */
   pendingInjections: Map<string, string>;
+  /** §Memory — sessionIDs that have already received memory context. */
+  injectedSessions: Set<string>;
   /** v0.7.0-alpha.1 — Dashboard publisher (or null if disabled/not started).
    *  Used by the `event` hook to forward opencode session lifecycle
    *  events to the v2 dashboard via the @polderlabs/bizar-sdk. */
   dashboardPublisher: DashboardPublisher | null;
+  /** §Memory — injects relevant memory context at session start. */
+  memoryInject: (sessionID: string, firstMessage: string) => Promise<void>;
+  /** §Memory — writes session summary to memory vault on session end. */
+  memoryWriteOnEnd: (sessionID: string, info: {
+    sessionID: string;
+    agent: string;
+    startedAt: number;
+    endedAt: number;
+    status: "idle" | "error" | "killed";
+    error?: string;
+  }, conversationPreview: string) => Promise<void>;
+  /** §Memory — session start timestamps for duration calculation on session end. */
+  sessionStartTimes: Map<string, number>;
 }
 
 /**
@@ -652,6 +677,22 @@ let bgAvailable = false;
 
   installSignalHandlers(logger, instanceManager, serve, stream, options.stateDir);
 
+  // §Memory — compute injectedSessions and memoryInject early so they can
+  // be embedded directly in the ctx object literal (avoids TS2741).
+  const injectedSessions = new Set<string>();
+  const sessionStartTimes = new Map<string, number>();
+  const { memoryInject } = createMemoryInject({
+    injectedSessions,
+    worktree: input.worktree,
+    logger,
+    enabled: true, // TODO: gate on settings.memory.injectOnSessionStart
+  });
+  const { memoryWriteOnEnd } = createMemoryWriteOnEnd({
+    worktree: input.worktree,
+    logger,
+    enabled: true, // TODO: gate on settings.memory.writeOnSessionEnd
+  });
+
   const ctx: RuntimeContext = {
     logger,
     options,
@@ -663,7 +704,11 @@ let bgAvailable = false;
     directory: input.directory,
     seenMessageIds: new Map(),
     pendingInjections: new Map(),
+    injectedSessions,
     dashboardPublisher,
+    memoryInject,
+    memoryWriteOnEnd,
+    sessionStartTimes,
   };
 
   return buildHooks(ctx, { instanceManager, bgAvailable });
@@ -983,6 +1028,25 @@ function buildHooks(ctx: RuntimeContext, bg: BgDeps): Hooks {
       worktree: ctx.worktree,
       logger: ctx.logger,
     }),
+
+    // §Memory — Bizar Memory tools. Available to all agents; no serve
+    // child required. Worktree is passed for context (vault discovery).
+    bizar_memory_search: createMemorySearchTool({
+      worktree: ctx.worktree,
+      logger: ctx.logger,
+    }),
+    bizar_memory_read: createMemoryReadTool({
+      worktree: ctx.worktree,
+      logger: ctx.logger,
+    }),
+    bizar_memory_write: createMemoryWriteTool({
+      worktree: ctx.worktree,
+      logger: ctx.logger,
+    }),
+    bizar_memory_list: createMemoryListTool({
+      worktree: ctx.worktree,
+      logger: ctx.logger,
+    }),
   };
   const tools = bg.instanceManager
     ? {
@@ -992,6 +1056,10 @@ function buildHooks(ctx: RuntimeContext, bg: BgDeps): Hooks {
         // src/opencode-runner.ts). The serve child is still
         // available for the dashboard's v2 protocol and for any
         // TUI/web client that wants to attach to it.
+        //
+        // v5.x — added pause/resume/steer/progress tools for
+        // dashboard integration. See tools/bg-{pause,resume,
+        // report-progress,send-message}.ts.
         bizar_spawn_background: createBgSpawnTool({
           instanceManager: bg.instanceManager,
           worktree: ctx.worktree,
@@ -1009,6 +1077,23 @@ function buildHooks(ctx: RuntimeContext, bg: BgDeps): Hooks {
           instanceManager: bg.instanceManager,
           logger: ctx.logger,
         }),
+        bizar_pause: createBgPauseTool({
+          instanceManager: bg.instanceManager,
+          logger: ctx.logger,
+        }),
+        bizar_resume: createBgResumeTool({
+          instanceManager: bg.instanceManager,
+          logger: ctx.logger,
+        }),
+        bizar_send_message: createBgSendMessageTool({
+          instanceManager: bg.instanceManager,
+          logger: ctx.logger,
+        }),
+        // Available to ALL agents (the body of a bg agent calls it).
+        bizar_report_progress: createBgReportProgressTool({
+          instanceManager: bg.instanceManager,
+          logger: ctx.logger,
+        }),
       }
     : {
         ...basePlanTools,
@@ -1040,6 +1125,14 @@ function buildHooks(ctx: RuntimeContext, bg: BgDeps): Hooks {
         output.system.push(pending);
         ctx.pendingInjections.delete(sessionID);
       }
+
+      // §Memory — inject relevant memory context at the start of the
+      // session (first turn only). `popMemoryContext` is idempotent
+      // (marks session as injected on first call).
+      const memCtx = popMemoryContext(sessionID);
+      if (memCtx) {
+        output.system.push(memCtx);
+      }
     },
 
     // Before the model is called, strip `` blocks from
@@ -1150,7 +1243,61 @@ function buildHooks(ctx: RuntimeContext, bg: BgDeps): Hooks {
           });
           ctx.pendingInjections.delete(sessionID);
           ctx.seenMessageIds.delete(sessionID);
+          ctx.injectedSessions.delete(sessionID);
+          ctx.sessionStartTimes.delete(sessionID);
+        }
+
+        // §Memory — on session start, fetch relevant memory context and
+        // queue it for injection via `popMemoryContext` in the transform hook.
+        if (type === "session.created") {
+          const ev2 = ev as {
+            properties?: {
+              sessionID?: string;
+              startedAt?: number;
+              [k: string]: unknown;
+            };
+            messageText?: string;
+            firstMessage?: string;
+          };
+          // Record start time for session-end duration calculation.
+          const startedAt = typeof ev2.properties?.startedAt === "number"
+            ? ev2.properties.startedAt
+            : Date.now();
+          ctx.sessionStartTimes.set(sessionID, startedAt);
+          // Extract the first user message text — different opencode versions
+          // surface this in different places; try several keys.
+          const firstMessage =
+            typeof ev2.messageText === "string"
+              ? ev2.messageText
+              : typeof ev2.firstMessage === "string"
+                ? ev2.firstMessage
+                : typeof ev.properties?.messageText === "string"
+                  ? ev.properties.messageText
+                  : "";
+          void ctx.memoryInject(sessionID, firstMessage);
         }
+
+        // §Memory — on session end, write an automated session summary to the
+        // memory vault. Fire-and-forget — failures are logged but never throw.
+        if (type === "session.idle" || type === "session.error") {
+          const startedAt = ctx.sessionStartTimes.get(sessionID) ?? Date.now();
+          const endedAt = Date.now();
+          const errorProp = (ev as { properties?: { error?: string } }).properties?.error;
+          void ctx.memoryWriteOnEnd(
+            sessionID,
+            {
+              sessionID,
+              agent: (ev as { properties?: { agent?: string } }).properties?.agent ?? "unknown",
+              startedAt,
+              endedAt,
+              status: type === "session.idle" ? "idle" : "error",
+              error: type === "session.error" ? (errorProp ?? "unknown") : undefined,
+            },
+            "",
+          );
+          ctx.sessionStartTimes.delete(sessionID);
+        }
+
         // Other event types are no-ops on the hook side. The state file
         // is updated by `chat.message` and `tool.execute.before/after`.
       } catch (err) {