loreli 1.0.0 → 2.0.0

package/packages/mcp/README.md

@@ -15,6 +15,8 @@ Before using the CLI tool commands below, configure an MCP server entry named `l
 ```bash
 loreli tools list
 loreli tools start --repo owner/repo
+# or rely on repo fallback from loreli.yml / LORELI_REPO
+loreli tools start
 loreli tools team_status
 loreli tools agents --action check
 ```
@@ -58,7 +60,7 @@ All tools are visible at all times. No progressive disclosure — every tool is
 
 | Tool | Description |
 |------|-------------|
-| `start` | Initialize orchestration for a target GitHub repo. Validates access, discovers/scaffolds templates, creates project board. Idempotent — safe to re-run. |
+| `start` | Initialize orchestration for a target GitHub repo. Accepts `--repo`, or falls back to configured `repo` from `loreli.yml` / `LORELI_REPO`. Validates access, discovers/scaffolds templates, creates project board. Idempotent — safe to re-run. |
 | `environment` | Report detected environment: tmux, backends, providers, review strategy. |
 
 ### Team Management
@@ -67,17 +69,59 @@ All tools are visible at all times. No progressive disclosure — every tool is
 |------|-------------|
 | `add_agent` | Add an agent. Params: `provider` (`openai`, `anthropic`, `cursor-openai`, `cursor-anthropic`), `role` (`planner`, `action`, `reviewer`), `model`, `theme`. |
 | `agents` | Query agent team state. Actions: `list` (show all agents with state, identity, role, and terminal output; optional `lines` param, default 40), `check` (liveness check for one or all agents). |
-| `start_planning` | Activate planner agents to analyze the repo and create draft work items. Accepts an `objective` to guide the planner. |
-| `start_work` | Begin action/review cycle. Action agents claim issues, do work, create PRs. Review agents are auto-assigned via yin/yang pairing. |
-| `team_status` | Dashboard: issues, PRs, agent states with terminal snapshots (last 20 lines), review loops, PRs awaiting human review, and GitHub API rate limits. |
-| `escalate` | Signal a concern or feature idea to the planner queue. Creates a draft on the project board. |
+| `start_planning` | Activate planner agents to analyze the repo and create draft work items. Accepts an `objective` to guide the planner. Uses explicit `repo` argument when provided, otherwise falls back to configured `repo`. |
+| `start_work` | Begin action/review cycle. Action agents claim issues, do work, create PRs. Review agents are auto-assigned via yin/yang pairing. Uses explicit `repo` argument when provided, otherwise falls back to configured `repo`. |
+| `team_status` | Dashboard: issues, PRs, agent states with terminal snapshots (last 20 lines), review loops, PRs awaiting human review, and GitHub API rate limits. Uses explicit `repo` argument when provided, otherwise falls back to configured `repo`. |
+
+### Agent Tools (Agent-Only)
+
+| Tool | Description |
+|------|-------------|
+| `plan` | Plan lifecycle management. Actions: `create` (new discussion), `revise` (update after feedback), `verdict` (approve/reject as reviewer), `escalate` (flag process or architecture concerns). |
+| `pr` | Pull request lifecycle. Actions: `create` (open PR from branch), `review` (submit adversarial review). |
+| `comment` | Post a comment on the agent's current work item. Set `claim: true` to claim an issue, `abandon: true` to abandon. |
+| `read` | Read any issue, PR, or discussion by number. |
+| `refactor` | Flag a bug, code smell, or tech debt discovered during implementation. Action agents only. Creates a deduplicated Loreli discussion labeled `loreli:refactor` that enters the standard review/promote pipeline. |
+| `context` | Resolve code context. Actions: `blame`, `history`, `search`, `patterns`. |
+| `environment` | Report detected environment: tmux, backends, providers, review strategy. |
+
+#### `refactor` Tool
+
+Enables [opportunistic refactoring](https://martinfowler.com/bliki/OpportunisticRefactoring.html) — action agents report improvements they discover without leaving their assigned scope.
+
+**Parameters:**
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `kind` | `string` | yes | Category: `bug`, `refactor`, `smell`, or `debt` |
+| `title` | `string` | yes | Concise improvement title |
+| `description` | `string` | yes | Problem statement with stable identifiers (function names, class names, error messages) |
+| `files` | `string[]` | no | Affected file paths, optionally with line range hints |
+| `impact` | `string` | no | `low`, `medium` (default), or `high` |
+
+**File path format:**
+
+File entries accept plain paths or paths with GitHub-style line range hints:
+
+- `src/hub.js` — plain path
+- `packages/hub/src/github.js#R40-R50` — path with line range hint (lines 40–50)
+
+Line ranges are advisory hints; they may drift between commits. Always include stable identifiers (function names, error patterns) in the `description`.
+
+**Dedup behavior:**
+
+Before creating a discussion, the tool searches existing issues and `loreli:refactor`-labeled discussions by normalized title. If a match is found, it returns an "Already tracked" reference instead of creating a duplicate. Dedup is best-effort — parallel reports can race.
+
+**Pipeline integration:**
+
+Created discussions enter the existing planner review/revise/promote pipeline. When promoted to issues, the `loreli:refactor` label is carried to the new issue for tracking.
 
 ### Human In The Loop (HITL)
 
 | Tool | Description |
 |------|-------------|
-| `hitl` | Hand off a PR to human reviewers (Human In The Loop). Requests review, assigns users, posts summary comment tagging reviewers. Kills agents to conserve resources. |
-| `watch` | Check an HITL PR for new human feedback. Filters out agent comments. Returns comments posted after the HITL timestamp. |
+| `hitl` | Hand off a PR to human reviewers (Human In The Loop). Requests review, assigns users, posts summary comment tagging reviewers. Kills agents to conserve resources. Uses explicit `repo` argument when provided, otherwise falls back to configured `repo`. |
+| `watch` | Check an HITL PR for new human feedback. Filters out agent comments. Returns comments posted after the HITL timestamp. Uses explicit `repo` argument when provided, otherwise falls back to configured `repo`. |
 
 ### Agent Lifecycle
 

package/packages/mcp/instructions.md

@@ -67,7 +67,10 @@ When you are a spawned agent (planner, action, or reviewer), use the Loreli MCP
 | **plan** | `create`, `revise`, `verdict`, `escalate` | Planner creates/revises; Reviewer renders verdict; Any role escalates |
 | **pr** | `create`, `review` | Action creates PRs; Reviewer submits reviews |
 | **comment** | (none) | Any role posts comments on their current work item |
+| **read** | (none) | Any role reads issues, PRs, or discussions by number |
+| **refactor** | (none) | Action flags bugs, smells, debt for planning |
 | **context** | `blame`, `history`, `search`, `patterns` | Any role looks up code context, decision history, and feedback patterns |
+| **environment** | (none) | Any role checks available backends |
 
 ### Context Resolution
 
@@ -89,8 +92,9 @@ Tools enforce role boundaries server-side:
 | `plan/verdict` | reviewer | planner, action |
 | `pr/create` | action | planner, reviewer |
 | `pr/review` | reviewer | planner, action |
+| `refactor` | action | planner, reviewer |
 | `plan/escalate`, `comment` | any | — |
-| `context/*` | any | — |
+| `context/*`, `read`, `environment` | any | — |
 
 An action agent cannot approve its own PR. A planner cannot approve its own plan. The antagonist (opposing-provider reviewer) is always mandatory and auto-enlisted when missing.
 
@@ -117,5 +121,6 @@ Also available via CLI: `loreli tools context --action blame --file <path> --lin
 4. **Respect your role**: Only use actions permitted for your role. Attempting unauthorized actions wastes tokens and time.
 5. **Honor repository policy files**: If `AGENTS.md` exists in the repository root, treat it as authoritative repository policy input.
 6. **Follow role prompt quality gates**: Testing and style-quality requirements are enforced in role-specific prompts and review flows; do not bypass them.
+7. **Flag improvements opportunistically**: When you encounter bugs, code smells, or tech debt during your work, use the `refactor` tool immediately. Do not fix out-of-scope issues yourself — flag them and continue your task. The dedup gate prevents duplicate reports. Use `plan` (action: `escalate`) for process or architecture concerns, not code-level findings.
 
 </rules>

package/packages/mcp/scaffolding/loreli.yml

@@ -24,6 +24,13 @@ theme: transformers          # string or list: transformers | pokemon | marvel |
 # Change when: You want a global quality/cost baseline shift for all agents.
 model: balanced              # fast | balanced | powerful | exact model string
 
+# repo
+# What: Optional repository slug fallback for standalone tool contexts before start runs.
+# Impact: Enables tools like `loreli tools context`, `start_work`, and `hitl` to resolve repository scope without session hydration.
+# Signal: CLI tools report "No repository configured" outside agent/start sessions.
+# Change when: You regularly run Loreli tools directly from a shell and want a persistent repo default.
+# repo: owner/repo
+
 # --- Merge gate ---
 # reviewers
 # What: GitHub usernames for HITL review requests.
@@ -114,6 +121,14 @@ timeouts:
   # Change when: Startup failures are missed (increase) or false positives occur (decrease).
   rapidDeath: 15s
 
+  # timeouts.proxyDiscovery
+  # What: HTTP timeout for proxy model discovery calls used by claude/codex.
+  # Impact: Lower values fail fast on unhealthy proxies; higher values tolerate slower proxy endpoints.
+  # Signal: Discovery frequently times out on healthy but slow networks (increase),
+  #         or startup blocks too long on unreachable proxy endpoints (decrease).
+  # Change when: Proxy-backed environments need slower/faster discovery behavior.
+  proxyDiscovery: 5s
+
   # timeouts.nudge
   # What: Enables/disables tier-1 "you appear stalled" message.
   # Impact: true may interrupt deep work; false keeps escalation signals without message interruption.
@@ -144,15 +159,6 @@ watch:
   # Change when: Agents are underutilized (increase) or overloaded (decrease).
   maxClaims: 3
 
-# --- Review policy ---
-review:
-  # review.skipRiskAssessment
-  # What: Skips mandatory risk verdict checks in review flow.
-  # Impact: Faster review path with less explicit risk gating.
-  # Signal: Teams intentionally bypassing risk gates for speed, or conversely incidents from insufficient risk checks (set false).
-  # Change when: You intentionally prefer speed over formal risk signoff.
-  skipRiskAssessment: false
-
 # --- Scaling policy ---
 scaling:
   # scaling.maxAgents
@@ -162,35 +168,6 @@ scaling:
   # Change when: You need more throughput (increase) or tighter resource limits (decrease).
   maxAgents: 8
 
-  maxPerRole:
-    # scaling.maxPerRole.action
-    # What: Max concurrent action agents.
-    # Impact: Controls parallel implementation throughput.
-    # Signal: Large implementation queue with insufficient coding capacity.
-    # Change when: Work backlog is implementation-heavy.
-    action: 3
-
-    # scaling.maxPerRole.reviewer
-    # What: Max concurrent reviewer agents.
-    # Impact: Controls review bottleneck relief.
-    # Signal: PRs are ready but waiting on reviewer assignment/completion.
-    # Change when: PR queue waits on reviews.
-    reviewer: 2
-
-    # scaling.maxPerRole.risk
-    # What: Max concurrent risk agents.
-    # Impact: Controls parallel risk assessment capacity.
-    # Signal: Reviews blocked on risk verdicts.
-    # Change when: Risk checks become the bottleneck.
-    risk: 3
-
-    # scaling.maxPerRole.planner
-    # What: Max concurrent planner agents.
-    # Impact: Limits parallel planning/discussion churn.
-    # Signal: Planning queue grows (increase) or discussion noise overwhelms maintainers (decrease).
-    # Change when: You want more/fewer simultaneous planning threads.
-    planner: 1
-
   # scaling.maxPerTick
   # What: Spawn budget per reactor tick.
   # Impact: Higher values ramp up faster but can spike load.
@@ -301,6 +278,36 @@ agents:
 #         anthropic: opus-4.6-thinking
 #         openai: gpt-5.1-codex-max
 
+# --- Classification ---
+classify:
+  # classify.model
+  # What: Model tier used for non-interactive classification prompts.
+  # Impact: Higher tiers may classify more accurately but cost more and respond slower.
+  # Signal: Misclassified pane states/feedback or excessive latency/cost.
+  # Change when: You want a different speed/accuracy trade-off for classification tasks.
+  model: fast
+
+  # classify.maxLines
+  # What: Max pane lines captured for classifier input.
+  # Impact: Higher values provide more context but increase token usage and prompt size.
+  # Signal: Classifier misses important terminal context (increase), or prompts are noisy/too large (decrease).
+  # Change when: Terminal-state classification needs more or less surrounding context.
+  maxLines: 100
+
+  # classify.timeout
+  # What: Timeout for non-interactive classifier calls.
+  # Impact: Higher values tolerate cold starts; lower values fail fast on stuck backends.
+  # Signal: Frequent classifier timeouts on healthy backends (increase), or long stalls waiting for dead ones (decrease).
+  # Change when: Your classifier backends are slower or faster than the default.
+  timeout: 30s
+
+  # classify.maxRetries
+  # What: Max consecutive classifier failures before the orchestrator gives up and escalates.
+  # Impact: Higher values are more tolerant of transient failures; lower values fail closed sooner.
+  # Signal: Temporary classifier hiccups cause unnecessary kills/escalations (increase), or repeated failures waste time (decrease).
+  # Change when: You need a stricter or more forgiving classifier failure budget.
+  maxRetries: 5
+
 # --- Trace capture ---
 trace:
   # trace.enabled
@@ -324,34 +331,6 @@ trace:
   # Change when: Useful context is being truncated too aggressively.
   maxOutputChars: 8000
 
-  workflows:
-    planner:
-      # trace.workflows.planner.enabled / maxOutputChars
-      # What: Planner-specific trace override.
-      # Impact: Fine-grained planner trace tuning.
-      # Signal: Planner traces need different verbosity than global behavior.
-      # Change when: Planner traces need different verbosity than global default.
-      enabled: true
-      maxOutputChars: 4000
-
-    reviewer:
-      # trace.workflows.reviewer.enabled / maxOutputChars
-      # What: Reviewer-specific trace override.
-      # Impact: Fine-grained reviewer trace tuning.
-      # Signal: Reviewer traces are too sparse for diagnosis or too noisy for signal extraction.
-      # Change when: Reviewer traces are too noisy or too sparse.
-      enabled: true
-      maxOutputChars: 4000
-
-    risk:
-      # trace.workflows.risk.enabled / maxOutputChars
-      # What: Risk-specific trace override.
-      # Impact: Fine-grained risk trace tuning.
-      # Signal: Risk reasoning context is truncated (increase) or over-captured (decrease).
-      # Change when: Risk traces need tighter/looser capture bounds.
-      enabled: true
-      maxOutputChars: 2000
-
 # --- Proof of life ---
 proofOfLife:
   # proofOfLife.timeout
@@ -386,17 +365,69 @@ cleanup:
   # Change when: You want explicit/manual cleanup control (set false).
   autoprune: true
 
-# --- Prompt overrides ---
-# prompts.{role}
-# What: Repo-local prompt file overrides for each role.
-# Impact: Changes agent behavior/instructions without code changes.
-# Signal: Repeated instruction gaps that can be fixed with persistent repo-specific guidance.
-# Change when: You need project-specific guardrails or workflow guidance.
-# prompts:
-#   action: .loreli/action.md
-#   reviewer: .loreli/review.md
-#   planner: .loreli/planner.md
-#   risk: .loreli/risk.md
+# --- Per-workflow configuration ---
+# workflows.{role}
+# What: Per-role settings consolidating model tier, agent cap, prompt override, trace, and skip flags.
+# Impact: Each workflow role can be tuned independently — model quality, parallelism, and observability.
+# Signal: Different roles need different cost/quality trade-offs, scaling limits, or trace verbosity.
+# Change when: You want per-role model tiers, scaling, custom prompts, or trace settings.
+workflows:
+  action:
+    # workflows.action.model
+    # What: Model tier for action agents (implementation work).
+    # Impact: Controls quality/cost of code generation.
+    # Change when: You want stronger/cheaper implementation agents.
+    model: balanced
+
+    # workflows.action.maxAgents
+    # What: Max concurrent action agents.
+    # Impact: Controls parallel implementation throughput.
+    # Change when: Work backlog is implementation-heavy.
+    maxAgents: 3
+
+    # workflows.action.prompt
+    # What: Repo-local prompt file override for action agents.
+    # Impact: Changes agent instructions without code changes.
+    # Change when: You need project-specific coding guardrails.
+    # prompt: .loreli/action.md
+
+  reviewer:
+    # workflows.reviewer.model
+    # What: Model tier for reviewer agents.
+    # Change when: You want stronger/cheaper review agents.
+    model: balanced
+    maxAgents: 2
+    # prompt: .loreli/reviewer.md
+    trace:
+      enabled: true
+      maxOutputChars: 4000
+
+  risk:
+    # workflows.risk.model
+    # What: Model tier for risk assessment agents.
+    # Change when: Risk evaluation needs deeper reasoning (powerful) or is fine with fast triage (fast).
+    model: fast
+    maxAgents: 3
+
+    # workflows.risk.skip
+    # What: Skips mandatory risk verdict checks in review flow.
+    # Impact: Faster review path with less explicit risk gating.
+    # Change when: You intentionally prefer speed over formal risk signoff.
+    skip: false
+    trace:
+      enabled: true
+      maxOutputChars: 2000
+
+  planner:
+    # workflows.planner.model
+    # What: Model tier for planner agents.
+    # Change when: Planning quality needs deeper reasoning.
+    model: powerful
+    maxAgents: 1
+    # prompt: .loreli/planner.md
+    trace:
+      enabled: true
+      maxOutputChars: 4000
 
 # --- Feedback and knowledge capture ---
 feedback:
@@ -427,6 +458,13 @@ feedback:
     - performance
     - security
 
+  # feedback.hitl
+  # What: Controls Human In The Loop escalation for feedback-driven PRs at merge time.
+  # Impact: true gates all feedback PRs on human approval; false allows full automation; array gates only listed categories.
+  # Signal: Feedback-driven changes landing without review (set true or list categories), or unnecessary merge friction (set false).
+  # Change when: You want human oversight on specific feedback categories (e.g. architecture, security) while letting others auto-merge.
+  hitl: false
+
 # --- Tmux ---
 tmux:
   # tmux.session

package/packages/mcp/scaffolding/mcp-configs/.codex/config.toml

@@ -1,3 +1,4 @@
 [mcp_servers.loreli]
 command = "npx"
 args = ["loreli", "mcp"]
+env_vars = ["GITHUB_TOKEN"]

package/packages/mcp/scaffolding/mcp-configs/.cursor/mcp.json

@@ -5,7 +5,10 @@
       "args": [
         "loreli",
         "mcp"
-      ]
+      ],
+      "env": {
+        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
+      }
     }
   }
 }

package/packages/mcp/scaffolding/mcp-configs/.mcp.json

@@ -5,7 +5,10 @@
       "args": [
         "loreli",
         "mcp"
-      ]
+      ],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
     }
   }
 }

package/packages/mcp/src/index.js

@@ -20,6 +20,7 @@ import { PlannerWorkflow } from 'loreli/planner';
 import { ActionWorkflow } from 'loreli/action';
 import { RiskWorkflow } from 'loreli/risk';
 import { ReviewWorkflow } from 'loreli/review';
+import { Config } from 'loreli/config';
 import { logger } from 'loreli/log';
 
 const log = logger('mcp');
@@ -41,12 +42,18 @@ const EMPTY_SCHEMA = { type: 'object', properties: {} };
  * start_work. Exposing those tools leads to confused agents calling
  * them, which destroys workspaces and starts duplicate reactor loops.
  *
- * `start` is included so agents that call it receive a no-op response
- * ("already configured") instead of an error.
+ * `start` was previously included so agents would receive a no-op
+ * response ("already configured") instead of an error. However, when
+ * agent hydration fails or env vars are missing, the no-op guard
+ * (`ctx.sessionId && ctx.agentName`) doesn't fire and the call falls
+ * through to the real implementation — which reaps the tmux session,
+ * killing every running agent. Observed in E2E: a Cursor Agent called
+ * `start` on its own repo, destroying the session it was living in.
+ * Safer to block it entirely and return a clean "not available" error.
  *
  * @type {Set<string>}
  */
-const AGENT_TOOLS = new Set(['plan', 'pr', 'comment', 'read', 'environment', 'context', 'start']);
+const AGENT_TOOLS = new Set(['plan', 'pr', 'comment', 'read', 'environment', 'context', 'refactor']);
 
 /**
  * Loreli MCP server for agentic team orchestration.
@@ -182,7 +189,7 @@ export class Loreli {
         if (ctx.agentName && !AGENT_TOOLS.has(name)) {
           log.warn(`agent ${ctx.agentName} blocked from calling host tool: ${name}`);
           return {
-            content: [{ type: 'text', text: `Tool "${name}" is not available to agents. Use plan, pr, comment, or read.` }],
+            content: [{ type: 'text', text: `Tool "${name}" is not available to agents. Use plan, pr, comment, read, refactor, environment, or context.` }],
             isError: true
           };
         }
@@ -283,11 +290,16 @@ export class Loreli {
    */
   async _prepare() {
     const home = this.config.home ?? process.env.LORELI_HOME ?? join(homedir(), '.loreli');
+    const config = new Config();
+    config.loadLocal('loreli.yml');
+    config.merge(this.config);
+
     const identityRegistry = new Registry();
     const backendRegistry = new BackendRegistry();
     const storage = new Storage({ home });
 
     const orchestrator = new Orchestrator({ hub: null, identityRegistry, backendRegistry, storage });
+    orchestrator.cfg = config;
 
     this.ctx = {
       hub: null,
@@ -302,8 +314,8 @@ export class Loreli {
       clientIdentity: null,
       clientName: null,
       clientVersion: null,
-      config: null,
-      repo: null,
+      config,
+      repo: config.get('repo') ?? null,
       categoryId: null,
       sessionId: null,
       server: this
@@ -354,7 +366,7 @@ export class Loreli {
 
     const data = await storage.load(sessionId, agentName);
     if (data) {
-      this.ctx.repo = data.repo ?? process.env.LORELI_REPO ?? null;
+      this.ctx.repo = data.repo ?? process.env.LORELI_REPO ?? this.ctx.repo ?? null;
       if (data.identity) {
         // Identity.toJSON() stores `name` as full name and `character`
         // as the raw character. The constructor expects `name` = character.
@@ -371,7 +383,7 @@ export class Loreli {
       log.info(`agent context hydrated: ${agentName} (session: ${sessionId}, repo: ${this.ctx.repo})`);
     } else {
       // Fallback to env var when storage has no data yet (first startup)
-      this.ctx.repo = process.env.LORELI_REPO ?? null;
+      this.ctx.repo = process.env.LORELI_REPO ?? this.ctx.repo ?? null;
       log.warn(`agent session data not found for ${agentName} in ${sessionId}, using env fallback`);
     }
 
@@ -397,9 +409,9 @@ export class Loreli {
   async _hydrateHub() {
     let token = process.env.GITHUB_TOKEN;
 
-    // cursor-agent CLI does not support ${env:NAME} interpolation or
-    // reliable envFile loading. Fall back to .git/loreli.env which
-    // create() writes inside .git/ (inherently unstageable by git).
+    // Keep a file-based fallback for startup paths where the host did
+    // not provide GITHUB_TOKEN to this process. create() writes
+    // .git/loreli.env inside .git/ (inherently unstageable by git).
     if (!token) {
       try {
         const { readFileSync } = await import('node:fs');
@@ -434,9 +446,10 @@ export class Loreli {
     // Load config from loreli.yml when repo is known
     if (this.ctx.repo && this.ctx.hub) {
       try {
-        const { Config } = await import('loreli/config');
         const config = new Config();
+        config.merge(this.config);
         await config.load(this.ctx.hub, this.ctx.repo);
+        config.merge(this.config);
         this.ctx.config = config;
         this.ctx.orchestrator.cfg = config;
         log.info(`agent config loaded from ${this.ctx.repo}/loreli.yml`);
@@ -523,12 +536,19 @@ export class Loreli {
     // stub would treat every pane in the session as orphaned and kill
     // all sibling agents. Only the host process owns the real registry.
     const self = this;
-    async function gracefulExit() {
+
+    /**
+     * @param {'SIGINT'|'SIGTERM'|'transport-close'} reason - What triggered shutdown.
+     */
+    async function gracefulExit(reason) {
       if (self.ctx?.agentName) {
+        log.info(`agent ${self.ctx.agentName} MCP server exiting (${reason})`);
         process.exit(0);
         return;
       }
 
+      log.info(`host MCP server exiting (${reason})`);
+
       self.ctx?.orchestrator?.unwatch?.();
       self.ctx?.orchestrator?.stopMonitor?.();
 
@@ -553,16 +573,25 @@ export class Loreli {
       process.exit(0);
     }
 
-    process.on('SIGINT', gracefulExit);
-    process.on('SIGTERM', gracefulExit);
+    process.on('SIGINT', function onSigint() { gracefulExit('SIGINT'); });
+    process.on('SIGTERM', function onSigterm() { gracefulExit('SIGTERM'); });
 
     log.info('loreli MCP server starting');
+
+    transport.onerror = function onTransportError(err) {
+      log.error(`MCP transport error: ${err?.message ?? err}`);
+    };
+
     await this.server.connect(transport);
 
+    this.server.onerror = function onServerError(err) {
+      log.error(`MCP server error: ${err?.message ?? err}`);
+    };
+
     // Transport disconnect (client closed pipe, host exited) bypasses
     // process signals entirely. Wire the SDK's onclose so cleanup runs
     // regardless of how the connection ends.
-    this.server.onclose = gracefulExit;
+    this.server.onclose = function onTransportClose() { gracefulExit('transport-close'); };
 
     log.info('loreli MCP server connected');
 

package/packages/mcp/src/tools/agent-context.js

@@ -0,0 +1,44 @@
+import { Identity } from 'loreli/identity';
+
+/**
+ * Resolve agent context from session storage.
+ *
+ * Reads the agent's persisted session data using the sessionId and
+ * agentName from ctx (hydrated at MCP server startup from env vars).
+ * Reconstructs a live Identity instance so hub stamping and label
+ * methods work correctly. Throws when context is not available — this
+ * means the tool was called from a non-agent MCP client.
+ *
+ * @param {object} ctx - Execution context with sessionId, agentName, storage.
+ * @returns {Promise<{repo: string, identity: Identity, role: string, task: object|null, issue: number|null, paneId: string|null}>}
+ * @throws {Error} When agent context is not available.
+ */
+export async function context(ctx) {
+  if (!ctx.sessionId || !ctx.agentName) {
+    throw new Error('Agent context not available. This tool can only be called by spawned agents.');
+  }
+
+  const data = await ctx.storage.load(ctx.sessionId, ctx.agentName);
+  if (!data) {
+    throw new Error(`Session data not found for agent "${ctx.agentName}" in session "${ctx.sessionId}".`);
+  }
+
+  const raw = data.identity;
+  const identity = new Identity({
+    name: raw.character ?? raw.name,
+    instance: raw.instance ?? 0,
+    faction: raw.faction,
+    provider: raw.provider,
+    model: raw.model,
+    theme: raw.theme
+  });
+
+  return {
+    repo: data.repo,
+    identity,
+    role: data.role,
+    task: data.task ?? null,
+    issue: data.claimedIssue ?? data.task?.issue ?? null,
+    paneId: data.paneId ?? null
+  };
+}