loreli 0.0.0 → 1.0.0

package/packages/workflow/src/index.js

@@ -0,0 +1,481 @@
+import { readFile } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import Mustache from 'mustache';
+import { mark, has, parse } from 'loreli/marker';
+
+export { responder } from './proof-of-life.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to the shared autonomous-mode preamble prepended to
+ * every agent prompt. Lives in the workflow package because render()
+ * is the single funnel all prompts flow through.
+ *
+ * @type {string}
+ */
+const PREAMBLE = join(__dirname, '..', 'prompts', 'preamble.md');
+
+/** @type {string|null} Cached preamble text — loaded once, reused. */
+let _preamble = null;
+
+/**
+ * Load the shared preamble, caching after the first read.
+ *
+ * @returns {Promise<string>}
+ */
+async function preamble() {
+  if (_preamble === null) _preamble = await readFile(PREAMBLE, 'utf8');
+  return _preamble;
+}
+
+/**
+ * Abstract base class for role-specific workflow packages.
+ *
+ * Subclasses must define `static role` (the agent role name) and
+ * `static template` (absolute path to the Mustache prompt file).
+ * They implement `reactor()` and `events()` to register handlers
+ * with the orchestrator's tick loop and EventEmitter respectively.
+ *
+ * This class absorbs the template rendering responsibility from the
+ * deleted `Role` class, adds agent filtering by role, and provides
+ * the `renderFrom()` method for cross-role rendering (e.g. the
+ * review package rendering the action prompt for `forward()`).
+ */
+export class Workflow {
+  /**
+   * @param {object} orchestrator - Orchestrator instance with agents Map and identityRegistry.
+   * @param {object} hub - GitHub hub instance for API calls.
+   */
+  constructor(orchestrator, hub) {
+    if (!new.target.role) {
+      throw new Error('Workflow subclass must define static role');
+    }
+
+    /** @type {object} The orchestrator for agent coordination. */
+    this.orchestrator = orchestrator;
+
+    /** @type {object} GitHub hub for API calls. */
+    this.hub = hub;
+
+    /** @type {Map<string, string|null>} Per-role cached custom prompt content. */
+    this._custom = new Map();
+  }
+
+  /**
+   * Return reactor handler map for the orchestrator's tick loop.
+   * Subclasses override to register their specific handlers.
+   *
+   * @returns {Record<string, Function>} Handler name to async function.
+   */
+  reactor() {
+    return {};
+  }
+
+  /**
+   * Return event listener map for orchestrator EventEmitter events.
+   * Subclasses override to register their specific listeners.
+   *
+   * @returns {Record<string, Function>} Event name to handler function.
+   */
+  events() {
+    return {};
+  }
+
+  /**
+   * Filter orchestrator agents to those matching this workflow's role.
+   *
+   * @returns {object[]} Agents whose role matches this workflow's static role.
+   */
+  agents() {
+    const role = this.constructor.role;
+    return [...this.orchestrator.agents.values()]
+      .filter(function byRole(a) { return a.role === role; });
+  }
+
+  /**
+   * Report the current demand signal for this workflow's role.
+   *
+   * Returns a structured object so the orchestrator can make informed
+   * scaling decisions — spawn decisions use `deficit`, cross-role
+   * prioritization uses `workload`, and logging uses all three.
+   *
+   * Subclasses override to compute real values from their hydrated
+   * state. The base implementation reports zero demand.
+   *
+   * @param {string} _repo - Repository in "owner/name" format.
+   * @returns {Promise<{workload: number, supply: number, deficit: number}>}
+   */
+  async demand(_repo) {
+    return { workload: 0, supply: 0, deficit: 0 };
+  }
+
+  /**
+   * Find the opposing-provider match for yin/yang review pairing.
+   * Delegates to the orchestrator's identity registry.
+   *
+   * @param {object} identity - The identity to find an opposite for.
+   * @param {object[]} candidates - Objects with an identity property.
+   * @returns {object|null} The matching candidate, or null.
+   */
+  pair(identity, candidates) {
+    return this.orchestrator.identityRegistry.pair(identity, candidates);
+  }
+
+  /**
+   * Create and spawn a new agent via the orchestrator's factory.
+   *
+   * @param {string} provider - AI provider.
+   * @param {string} role - Agent role.
+   * @param {object} [opts] - Additional factory options.
+   * @returns {Promise<object>} The spawned agent.
+   */
+  async enlist(provider, role, opts) {
+    return this.orchestrator.enlist(provider, role, opts);
+  }
+
+  /**
+   * Load the project-specific custom prompt for this workflow's role.
+   *
+   * Resolves `prompts.{role}` from config (e.g. `prompts.action`,
+   * `prompts.reviewer`, `prompts.planner`), reads the file once from
+   * the target repo via the hub, and caches the result on this
+   * instance. Returns an empty string when the config key is unset,
+   * the hub is unavailable, or the file cannot be read — prompt
+   * rendering never fails due to a missing custom prompt.
+   *
+   * @param {object} [opts] - Options.
+   * @param {string} [opts.role] - Role to resolve `prompts.{role}` for.
+   * @returns {Promise<string>} Custom prompt text, or empty string.
+   */
+  async custom(opts = {}) {
+    const role = opts.role ?? this.constructor.role;
+    if (this._custom.has(role)) return this._custom.get(role) ?? '';
+
+    const path = this.orchestrator.cfg?.get?.(`prompts.${role}`);
+    if (!path || !this.hub?.read || !this.orchestrator.repo) {
+      this._custom.set(role, null);
+      return '';
+    }
+
+    try {
+      const result = await this.hub.read(this.orchestrator.repo, path);
+      this._custom.set(role, result?.content ?? null);
+    } catch {
+      this._custom.set(role, null);
+    }
+
+    return this._custom.get(role) ?? '';
+  }
+
+  /**
+   * Load and render this workflow's prompt template.
+   *
+   * Automatically injects the workflow's `role` into the template
+   * variables so subclasses don't need to pass it explicitly.
+   * Prepends the shared autonomous-mode preamble and any project-
+   * specific custom prompt from `prompts.{role}` so every agent
+   * prompt carries the headless operation directive and project rules.
+   *
+   * @param {object} vars - Mustache template variables.
+   * @returns {Promise<string>} Rendered prompt text.
+   */
+  async render(vars) {
+    const [pre, ext, template] = await Promise.all([
+      preamble(),
+      this.custom({ role: this.constructor.role }),
+      readFile(this.constructor.template, 'utf8')
+    ]);
+    const body = Mustache.render(template, { ...vars, role: this.constructor.role });
+    const prefix = ext ? `${pre}\n${ext}\n` : `${pre}\n`;
+    return `${prefix}${body}`;
+  }
+
+  /**
+   * Load and render an arbitrary Mustache template by path.
+   *
+   * Used for cross-role rendering where one workflow needs another
+   * role's prompt (e.g. review rendering the action prompt for forward).
+   * Prepends the shared autonomous-mode preamble and any project-
+   * specific custom prompt from `prompts.{role}`.
+   *
+   * @param {string} path - Absolute path to a .md template file.
+   * @param {object} vars - Mustache template variables.
+   * @param {object} [opts] - Options.
+   * @param {string} [opts.role] - Role to resolve `prompts.{role}` for.
+   * @returns {Promise<string>} Rendered prompt text.
+   */
+  async renderFrom(path, vars, opts = {}) {
+    const role = opts.role ?? this.constructor.role;
+    const [pre, ext, template] = await Promise.all([
+      preamble(),
+      this.custom({ role }),
+      readFile(path, 'utf8')
+    ]);
+    const body = Mustache.render(template, vars);
+    const prefix = ext ? `${pre}\n${ext}\n` : `${pre}\n`;
+    return `${prefix}${body}`;
+  }
+
+  /**
+   * Write task context to the agent's session in storage.
+   *
+   * Called by workflows before dispatching an agent so the agent's
+   * MCP server can read the task context (discussion ID, PR number,
+   * etc.) without the agent needing to pass it as a parameter.
+   *
+   * No-op when sessionId or storage is not available (e.g. tests
+   * without persistent storage).
+   *
+   * @param {string} agentName - Agent identity name.
+   * @param {object} task - Task context object (e.g. { type: 'review_pr', pr: 42 }).
+   * @returns {Promise<void>}
+   */
+  async saveTask(agentName, task) {
+    const { storage, sessionId } = this.orchestrator;
+    if (!sessionId || !storage) return;
+
+    const data = await storage.load(sessionId, agentName);
+    if (!data) return;
+
+    data.task = task;
+    await storage.save(sessionId, agentName, data);
+  }
+
+  /**
+   * Render this workflow's template and send to an agent.
+   *
+   * @param {object} agent - Target agent with a send() method.
+   * @param {object} vars - Mustache template variables.
+   * @returns {Promise<void>}
+   */
+  async dispatch(agent, vars) {
+    const prompt = await this.render(vars);
+    await agent.send(prompt);
+  }
+
+  // ── Proof of Life ───────────────────────────────────
+
+  /**
+   * Post a themed proof-of-life request on an issue/PR.
+   *
+   * Uses the orchestrator's client identity for scoping and the
+   * council-level themed message from the identity's theme. Falls
+   * back to an unscoped invisible marker when no client identity
+   * is available (e.g. in tests with bare stubs).
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {string} agent - Name of the agent being checked.
+   * @returns {Promise<void>}
+   */
+  async requestProofOfLife(repo, number, agent) {
+    const orch = this.orchestrator.sessionId;
+    const payload = { agent, ts: String(Date.now()) };
+    if (orch) payload.orch = orch;
+    const marker = mark('proof-of-life', payload);
+    const identity = this.orchestrator.clientIdentity;
+    if (!identity) {
+      await this.hub.comment(repo, number, marker);
+      return;
+    }
+    const visible = identity.proofOfLife(agent);
+    const body = `${visible}\n\n${marker}`;
+    const scoped = this.hub.as(identity, 'orchestrator');
+    await scoped.comment(repo, number, body);
+  }
+
+  /**
+   * Post a themed alive response with an embedded machine-readable marker.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {object} identity - Agent identity for hub scoping.
+   * @param {string} role - Agent role for hub scoping.
+   * @param {{alive: boolean, status: string, details: string, outputLength?: number}} verdict - Health check result.
+   * @returns {Promise<void>}
+   */
+  async respondProofOfLife(repo, number, identity, role, verdict) {
+    const marker = mark('alive', {
+      agent: identity.name,
+      ts: String(Date.now()),
+      status: verdict.status
+    });
+    const visible = `**${identity.name}** is **${verdict.status}** — ${verdict.details}`;
+    const body = `${visible}\n\n${marker}`;
+    const scoped = this.hub.as(identity, role);
+    await scoped.comment(repo, number, body);
+  }
+
+  /**
+   * Find a pending proof-of-life request for a specific agent.
+   *
+   * When `orch` is provided, only matches requests posted by that
+   * orchestrator session. When omitted, matches any request — used
+   * by the responder which answers regardless of who asked.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {string} agent - Agent name to search for.
+   * @param {string} [orch] - Orchestrator session ID filter.
+   * @returns {Promise<{agent: string, ts: string, orch?: string}|null>} Parsed request data, or null.
+   */
+  async findProofOfLifeRequest(repo, number, agent, orch) {
+    const comments = await this.hub.comments(repo, number);
+    for (const c of comments) {
+      if (!has(c.body, 'proof-of-life')) continue;
+      const data = parse(c.body, 'proof-of-life');
+      if (data?.agent !== agent) continue;
+      if (orch && data.orch !== orch) continue;
+      return data;
+    }
+    return null;
+  }
+
+  /**
+   * Find an alive response for a specific agent posted after a given timestamp.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {string} agent - Agent name to search for.
+   * @param {number} after - Only match responses with ts greater than this epoch ms.
+   * @returns {Promise<{agent: string, ts: string, status: string}|null>} Parsed response, or null.
+   */
+  async findAliveResponse(repo, number, agent, after) {
+    const comments = await this.hub.comments(repo, number);
+    for (const c of comments) {
+      if (!has(c.body, 'alive')) continue;
+      const data = parse(c.body, 'alive');
+      if (data?.agent !== agent) continue;
+      if (Number(data.ts) > after) return data;
+    }
+    return null;
+  }
+
+  /**
+   * Check whether an issue/PR has any GitHub comment within the timeout window.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {number} timeout - Maximum age in ms for activity to be considered recent.
+   * @returns {Promise<boolean>}
+   */
+  async hasRecentActivity(repo, number, timeout) {
+    const comments = await this.hub.comments(repo, number);
+    const cutoff = Date.now() - timeout;
+    return comments.some(function recent(c) {
+      return new Date(c.created_at).getTime() > cutoff;
+    });
+  }
+
+  /**
+   * Evaluate an agent through the proof-of-life protocol.
+   *
+   * Unified gate for ALL eviction decisions — foreign agents, local
+   * idle agents, and any future workflow that needs to verify liveness
+   * before releasing a claim. Posts a PoL request if none exists,
+   * checks for alive responses, and considers the response status
+   * (healthy vs unhealthy) when making the verdict.
+   *
+   * Status-aware: an alive response with `status: 'unhealthy'` means
+   * the agent's own orchestrator confirmed it is stalled, so the gate
+   * returns `'release'` instead of `'active'`.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {string} agent - Agent identity name to check.
+   * @returns {Promise<string>} 'active'|'requested'|'pending'|'release'.
+   */
+  async check(repo, number, agent) {
+    const timeout = this.orchestrator.cfg?.get?.('proofOfLife.timeout') ?? 300000;
+    const orch = this.orchestrator.sessionId;
+
+    const ours = await this.findProofOfLifeRequest(repo, number, agent, orch);
+    if (ours) {
+      const response = await this.findAliveResponse(repo, number, agent, Number(ours.ts));
+      if (response) return response.status === 'unhealthy' ? 'release' : 'active';
+      if (Date.now() - Number(ours.ts) > timeout) return 'release';
+      return 'pending';
+    }
+
+    const any = await this.findProofOfLifeRequest(repo, number, agent);
+    if (any) {
+      const response = await this.findAliveResponse(repo, number, agent, Number(any.ts));
+      if (response) return response.status === 'unhealthy' ? 'release' : 'active';
+      if (Date.now() - Number(any.ts) > timeout) {
+        await this.requestProofOfLife(repo, number, agent);
+        return 'requested';
+      }
+      return 'pending';
+    }
+
+    const recent = await this.hasRecentActivity(repo, number, timeout);
+    if (recent) return 'active';
+
+    await this.requestProofOfLife(repo, number, agent);
+    return 'requested';
+  }
+
+  // ── Optimistic Claim ─────────────────────────────────
+
+  /**
+   * Optimistic claim on an issue or PR: post a marker comment, then
+   * re-read comments to verify this agent was first.
+   *
+   * This eliminates the TOCTOU race in the check-then-claim pattern.
+   * By claiming first and verifying after, two participants racing on
+   * the same item will both post, but only the first poster wins.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Issue or PR number.
+   * @param {string} type - Marker type (e.g. 'claim', 'review-claim', 'risk-claim').
+   * @param {object} identity - Agent identity.
+   * @param {string} role - Agent role for hub scoping.
+   * @param {string} [visible] - Optional visible text appended after the marker.
+   * @returns {Promise<boolean>} True if this agent was the first claimant.
+   */
+  async claimFirst(repo, number, type, identity, role, visible) {
+    const scoped = this.hub.as(identity, role);
+    const marker = mark(type, { agent: identity.name });
+    const body = visible ? `${marker}\n${visible}` : marker;
+    await scoped.comment(repo, number, body);
+
+    // Re-read all comments and find the first with this marker type.
+    // The first poster wins — all others back off.
+    const comments = await this.hub.comments(repo, number);
+    const first = comments.find(function isClaim(c) { return has(c.body, type); });
+    return parse(first?.body, type)?.agent === identity.name;
+  }
+
+  /**
+   * Optimistic claim on a discussion: post a marker comment, then
+   * re-read discussion comments to verify this agent was first.
+   *
+   * Identical pattern to {@link claimFirst} but uses the discussion
+   * comment API (node IDs, GraphQL) instead of issue/PR comments.
+   *
+   * @param {string} repo - Repository in "owner/name" format.
+   * @param {number} number - Discussion number (for reading).
+   * @param {string} discId - Discussion node ID (for posting).
+   * @param {string} type - Marker type (e.g. 'review-claim').
+   * @param {object} identity - Agent identity.
+   * @param {string} role - Agent role for hub scoping.
+   * @param {string} [visible] - Optional visible text appended after the marker.
+   * @returns {Promise<boolean>} True if this agent was the first claimant.
+   */
+  async claimFirstDiscussion(repo, number, discId, type, identity, role, visible) {
+    const scoped = this.hub.as(identity, role);
+    const marker = mark(type, { agent: identity.name });
+    const body = visible ? `${marker}\n${visible}` : marker;
+    await scoped.discussionComment(discId, body);
+
+    // Use the LAST claim comment to determine the winner. Discussions
+    // that go through revise/re-review cycles accumulate old claim
+    // comments from previous cycles — checking the first would always
+    // match the stale claim and block re-dispatch.
+    const full = await this.hub.discussion(repo, number);
+    const last = full.comments?.findLast(function isClaim(c) { return has(c.body, type); });
+    return parse(last?.body, type)?.agent === identity.name;
+  }
+}

package/packages/workflow/src/proof-of-life.js

@@ -0,0 +1,74 @@
+/**
+ * Proof-of-life reactor handler factory.
+ *
+ * Creates a handler that scans open issues and PRs for proof-of-life
+ * requests targeting agents in the local agents map, runs health
+ * checks, and posts themed responses.
+ *
+ * Registered once at start and runs on every reactor tick.
+ *
+ * @module loreli/workflow/proof-of-life
+ */
+import { has, parse, mark } from 'loreli/marker';
+import { logger } from 'loreli/log';
+
+const log = logger('proof-of-life');
+
+/**
+ * Create the proof-of-life reactor handler.
+ *
+ * @param {object} orchestrator - Orchestrator with agents map and health().
+ * @param {object} hub - GitHub hub for reading/posting comments.
+ * @returns {function(string): Promise<void>} Reactor handler receiving repo.
+ */
+export function responder(orchestrator, hub) {
+  return async function proofOfLife(repo) {
+    const [issues, prs] = await Promise.all([
+      hub.issues(repo, { state: 'open', labels: ['loreli'] }).catch(function noop() { return []; }),
+      hub.pulls(repo, { state: 'open' }).catch(function noop() { return []; })
+    ]);
+
+    const items = [
+      ...issues.map(function toItem(i) { return { number: i.number }; }),
+      ...prs.map(function toItem(p) { return { number: p.number }; })
+    ];
+
+    for (const item of items) {
+      const comments = await hub.comments(repo, item.number);
+
+      for (const c of comments) {
+        if (!has(c.body, 'proof-of-life')) continue;
+
+        const data = parse(c.body, 'proof-of-life');
+        if (!data?.agent) continue;
+
+        const agent = orchestrator.agents.get(data.agent);
+        if (!agent) continue;
+
+        const responded = comments.some(function alreadyAlive(r) {
+          if (!has(r.body, 'alive')) return false;
+          const alive = parse(r.body, 'alive');
+          return alive?.agent === data.agent && Number(alive.ts) > Number(data.ts);
+        });
+        if (responded) continue;
+
+        const verdict = await orchestrator.health(data.agent);
+        const aliveMarker = mark('alive', {
+          agent: agent.identity.name,
+          ts: String(Date.now()),
+          status: verdict.status
+        });
+        const visible = `**${agent.identity.name}** is **${verdict.status}** — ${verdict.details}`;
+        const body = `${visible}\n\n${aliveMarker}`;
+
+        try {
+          const scoped = hub.as(agent.identity, agent.role);
+          await scoped.comment(repo, item.number, body);
+          log.info(`proof-of-life: responded for ${data.agent} on #${item.number} — ${verdict.status}`);
+        } catch (err) {
+          log.warn(`proof-of-life: failed to respond for ${data.agent} on #${item.number}: ${err.message}`);
+        }
+      }
+    }
+  };
+}

package/packages/workspace/README.md

@@ -0,0 +1,143 @@
+# loreli/workspace
+
+Local workspace lifecycle for Loreli agents.
+
+This package prepares agent directories, scaffolds local MCP configs and safety hooks, manages clone-based workspaces, and provides git helpers used by action/review/context flows.
+
+## API Reference
+
+### Constants
+
+| Name | Type | Description |
+|------|------|-------------|
+| `ENTRY` | `{ command: string, args: string[] }` | Loreli MCP entry used in JSON-based configs. |
+| `MCP_JSON` | `string` | Default JSON config body for `.mcp.json` and `.cursor/mcp.json`. |
+| `CODEX_TOML` | `string` | Default TOML config body for `.codex/config.toml`. |
+
+### Config Generators
+
+#### `codexToml(context?)` → `string`
+
+Generate Codex TOML config content with optional agent context env keys.
+
+#### `mcpJson(context?, opts?)` → `string`
+
+Generate JSON MCP config content with optional agent context, token reference (`tokenRef`), and env file path (`envFile`).
+
+### Security/Hook Generators
+
+#### `denyScript(denied)` → `string`
+
+Generate the shared deny hook script used by Claude/Cursor shell hooks.
+
+#### `protectScript()` → `string`
+
+Generate the file-write protection hook script for protected paths.
+
+#### `claudeHooks()` → `string`
+
+Generate `.claude/settings.local.json` hook config content.
+
+#### `cursorMatcher(denied)` → `string`
+
+Build Cursor `beforeShellExecution` matcher regex from denied commands.
+
+#### `cursorHooks(denied)` → `string`
+
+Generate `.cursor/hooks.json` hook config content.
+
+### Workspace Lifecycle
+
+#### `pathFor(name, root?)` → `string`
+
+Resolve deterministic workspace path: `<root>/loreli-<name>`.
+
+- Default `root`: `~/.loreli/workspaces` (or `LORELI_HOME/workspaces`).
+
+#### `prepare(cwd, context?, descriptors?)` → `Promise<void>`
+
+Prepare a workspace directory by writing MCP configs, safety files, deny/protect scripts, and merged hook entries.
+
+When `context` is provided, session/agent/repo env values are embedded into generated configs. When `descriptors` are provided (from backend scaffolding), descriptor-driven config/hook/file generation is used.
+
+This example demonstrates preparing a workspace with context and denied commands. This matters because agents must boot with MCP connectivity and command guardrails. Expected result: config files and hook scripts are created/updated in place.
+
+```js
+import { prepare } from 'loreli/workspace';
+
+await prepare('/tmp/loreli-optimus-0', {
+  session: 's1',
+  agent: 'optimus-0',
+  repo: 'owner/repo',
+  denied: ['gh', 'curl']
+});
+```
+
+#### `mirror(url, opts?)` → `Promise<string>`
+
+Ensure a local bare mirror exists under `<home>/repos`. Fetches if mirror exists, clones if not.
+
+#### `create(repo, branch, name, root?, context?, descriptors?)` → `Promise<string>`
+
+Create or reuse an agent workspace. Current behavior is clone-based workspace creation (not git worktree-based execution) with branch initialization, optional remote auth setup, and preparation/scaffolding.
+
+This example demonstrates provisioning an agent workspace for branch work. This matters because action agents need an isolated git directory with local `.git` state. Expected result: returned `cwd` contains a prepared clone with agent branch checked out.
+
+```js
+import { create } from 'loreli/workspace';
+
+const cwd = await create('/path/to/bare-or-local-repo', 'main', 'optimus-0');
+```
+
+#### `clean(name, root?)` → `Promise<void>`
+
+Delete an agent workspace directory (best effort). Attempts worktree remove first, then force-removes directory.
+
+#### `prune(sessionId, root?)` → `Promise<string[]>`
+
+Remove stale `loreli-*` workspaces not owned by `sessionId`.
+
+#### `reset(cwd, name, issue?, base?, opts?)` → `Promise<void>`
+
+Reset workspace to a clean issue branch from remote `base` (default `main`).
+
+When `opts.context` and `opts.descriptors` are provided, `reset()` re-applies
+workspace scaffolding after the branch switch so MCP CLI config files remain
+available for shell-based Loreli tool commands.
+
+#### `checkout(cwd, branch, base?, opts?)` → `Promise<void>`
+
+Fetch and check out a remote branch in an existing workspace, also syncing local base ref.
+
+When `opts.context` and `opts.descriptors` are provided, `checkout()` re-applies
+workspace scaffolding after branch switch for the same reason as `reset()`.
+
+#### `hasChanges(cwd)` → `Promise<boolean>`
+
+Return whether workspace has uncommitted/untracked changes (`git status --porcelain`).
+
+#### `commitAndPush(cwd, message)` → `Promise<{ pushed: boolean, sha: string }>`
+
+Stage, commit, and attempt push. Returns commit SHA and whether push succeeded.
+
+### Git Context Helpers
+
+#### `blame(cwd, file, line)` → `Promise<{ sha: string, author: string, date: string, summary: string }>`
+
+Run porcelain git blame for a single line and return parsed metadata.
+
+#### `gitlog(cwd, file, opts?)` → `Promise<Array<{ sha: string, date: string, message: string }>>`
+
+Run git log for a file and return parsed commit entries.
+
+## Scope Boundary
+
+In scope:
+- local workspace preparation and cleanup
+- local MCP config/hook generation
+- clone/branch/reset/checkout helper operations
+- git context lookup helpers
+
+Out of scope:
+- remote GitHub scaffolding and repository writes (`loreli/hub`)
+- agent process lifecycle (`loreli/agent`, `loreli/orchestrator`)