@dyzsasd/dev-loop 0.22.0

package/dist/mcp-merge.js

@@ -0,0 +1,145 @@
+// DL-61 (design U2) — merge (never clobber) the `dev-loop-hub` MCP server into a PRODUCT repo's `.mcp.json`,
+// so init's `service` auto-wiring registers the hub server WITHOUT destroying any other MCP servers the
+// product already declares. Composes onto DL-60's init-service seam (c). §16: env-NAME-only — the entry
+// carries only `${VAR:-default}` env references (copied from the committed template), never a literal secret;
+// the hub DB path is intentionally omitted (the server defaults to ~/.dev-loop/hub.db). §17: this is a
+// data-file utility — it can only ever write the product `.mcp.json`, never a SKILL/conventions/code file.
+import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+const SERVER_NAME = "dev-loop-hub";
+// The published npm package packs only hub/dist + README — config/ lives OUTSIDE the packed dir, so the repo
+// template is absent when installed (Codex review 2026-06-27). This embedded default is the fallback: the
+// canonical dev-loop-hub entry shape (env NAME-only; an args slot ending in server.ts that buildEntry rewrites
+// to the real absolute path). Keep it in sync with config/mcp.example.json's dev-loop-hub entry.
+const DEFAULT_TEMPLATE = {
+    mcpServers: {
+        [SERVER_NAME]: {
+            command: "node",
+            args: ["server.ts"],
+            env: { DEVLOOP_ACTOR: "${DEVLOOP_ACTOR:-operator}" },
+        },
+    },
+};
+// Resolve the template object: an EXPLICIT path (tests) must read it (throw if unreadable — preserves the §15
+// suite's behavior); otherwise prefer the repo template file and fall back to the embedded default when it's
+// absent (the installed-package path, where config/ wasn't packed).
+function resolveTemplate(explicitPath, repoPath) {
+    if (explicitPath)
+        return JSON.parse(readFileSync(explicitPath, "utf8"));
+    if (existsSync(repoPath)) {
+        try {
+            return JSON.parse(readFileSync(repoPath, "utf8"));
+        }
+        catch { /* corrupt repo template → embedded default */ }
+    }
+    return DEFAULT_TEMPLATE;
+}
+// Build the dev-loop-hub entry FROM the resolved template (the single source of truth for its shape — so a
+// future template change propagates), filling the absolute hub server path into `args` and pinning the
+// DEVLOOP_PROJECT default to the project key (matches the dogfood `.mcp.json` `${DEVLOOP_PROJECT:-<key>}`).
+function buildEntry(tmpl, hubServerPath, projectKey) {
+    const src = tmpl.mcpServers?.[SERVER_NAME];
+    if (!src || typeof src !== "object")
+        throw new Error(`template has no mcpServers["${SERVER_NAME}"] entry`);
+    // §16/DL-44: the key becomes the `${DEVLOOP_PROJECT:-<key>}` default; a key carrying `$`/`{`/`}` would
+    // produce a NESTED ${...} (the DL-44 SoR-fork footgun) in the product .mcp.json — reject it loudly rather
+    // than write a malformed config. Real project keys are plain identifiers, so this never bites in practice.
+    if (/[${}]/.test(projectKey))
+        throw new Error(`project key ${JSON.stringify(projectKey)} contains '$', '{', or '}', which would break the .mcp.json \${VAR:-default} interpolation (DL-44) — use a plain identifier key`);
+    // DL-66: the hub server path lands verbatim in the entry's `args` (line below) — another interpolated
+    // .mcp.json string position — so a path carrying `$`/`{`/`}` would nest a `${...}` that Claude Code
+    // mis-expands at parse-time interpolation, corrupting the resolved hub path and breaking the launch in that
+    // pane. Guard it symmetrically with projectKey above; a real absolute checkout path never contains these
+    // (same defense-in-depth bar the team set for the projectKey side in DL-44).
+    if (/[${}]/.test(hubServerPath))
+        throw new Error(`hub server path ${JSON.stringify(hubServerPath)} contains '$', '{', or '}', which would nest a \${...} in the .mcp.json args that Claude Code mis-expands at parse-time interpolation, corrupting the resolved hub path (DL-66) — use a path without those characters`);
+    const e = structuredClone(src);
+    const args = (e.args ?? []);
+    const idx = args.findIndex((a) => typeof a === "string" && a.endsWith("server.ts"));
+    if (idx < 0)
+        throw new Error(`template ${SERVER_NAME} entry has no server.ts arg to fill`);
+    args[idx] = hubServerPath; // the real absolute path, replacing the <ABS-PATH-TO-dev-loop>/... placeholder
+    e.args = args;
+    // env stays NAME-only; pin the project key as the DEVLOOP_PROJECT default (single-level, no nested ${...} — DL-44)
+    e.env = { ...(e.env ?? {}), DEVLOOP_PROJECT: `\${DEVLOOP_PROJECT:-${projectKey}}` };
+    return e;
+}
+function writeAtomic(path, obj) {
+    const tmp = `${path}.tmp-${process.pid}`; // same dir → rename is atomic on one filesystem (never a half-written .mcp.json)
+    try {
+        writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n");
+        renameSync(tmp, path);
+    }
+    catch (e) {
+        try {
+            if (existsSync(tmp))
+                unlinkSync(tmp);
+        }
+        catch { /* best-effort — never leave a stray temp in the product repo */ }
+        throw e; // caller maps this to a clean {ok:false}, so a write failure warns rather than crashing the bootstrap
+    }
+}
+export function mergeMcpServer(opts) {
+    const { mcpJsonPath, hubServerPath, projectKey } = opts;
+    const here = dirname(fileURLToPath(import.meta.url)); // hub/src (dev) | dist (published)
+    let entry;
+    try {
+        const tmpl = resolveTemplate(opts.templatePath, join(here, "..", "..", "config", "mcp.example.json"));
+        entry = buildEntry(tmpl, hubServerPath, projectKey);
+    }
+    catch (e) {
+        return { ok: false, error: `could not build the ${SERVER_NAME} entry: ${e.message}` };
+    }
+    // No existing file → create a fresh `.mcp.json` carrying just our server.
+    if (!existsSync(mcpJsonPath)) {
+        try {
+            writeAtomic(mcpJsonPath, { mcpServers: { [SERVER_NAME]: entry } });
+        }
+        catch (e) {
+            return { ok: false, error: `could not write ${mcpJsonPath}: ${e.message}` };
+        }
+        return { ok: true, action: "created", servers: [SERVER_NAME] };
+    }
+    // Existing file → MERGE, never clobber. A malformed / partial file is an ERROR, left UNTOUCHED (never destroyed).
+    let cfg;
+    try {
+        cfg = JSON.parse(readFileSync(mcpJsonPath, "utf8"));
+    }
+    catch (e) {
+        return { ok: false, error: `${mcpJsonPath} is malformed JSON — left untouched (${e.message})` };
+    }
+    if (typeof cfg !== "object" || cfg === null || Array.isArray(cfg))
+        return { ok: false, error: `${mcpJsonPath} is not a JSON object — left untouched` };
+    const existingServers = cfg.mcpServers;
+    if ("mcpServers" in cfg && (typeof existingServers !== "object" || existingServers === null || Array.isArray(existingServers)))
+        return { ok: false, error: `${mcpJsonPath} has a non-object "mcpServers" — left untouched (partial/malformed)` };
+    const servers = (existingServers ?? {});
+    const existed = SERVER_NAME in servers;
+    if (existed && JSON.stringify(servers[SERVER_NAME]) === JSON.stringify(entry))
+        return { ok: true, action: "unchanged", servers: Object.keys(servers) }; // idempotent: identical → no write
+    servers[SERVER_NAME] = entry; // add or update IN PLACE — never a duplicate key; other servers untouched
+    cfg.mcpServers = servers;
+    try {
+        writeAtomic(mcpJsonPath, cfg);
+    } // re-serializes the WHOLE cfg → preserves every other server + top-level key
+    catch (e) {
+        return { ok: false, error: `could not write ${mcpJsonPath}: ${e.message}` };
+    }
+    return { ok: true, action: existed ? "updated" : "merged", servers: Object.keys(servers) };
+}
+// CLI: `node src/mcp-merge.ts <.mcp.json path> <abs hub/src/server.ts> <project-key> [template]`
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    const [mcpJsonPath, hubServerPath, projectKey, templatePath] = process.argv.slice(2);
+    if (!mcpJsonPath || !hubServerPath || !projectKey) {
+        console.error(`[hub] usage: node src/mcp-merge.ts <.mcp.json path> <abs hub/src/server.ts> <project-key> [template]`);
+        process.exit(2);
+    }
+    const r = mergeMcpServer({ mcpJsonPath, hubServerPath, projectKey, templatePath });
+    if (r.ok) {
+        console.log(`✅ ${SERVER_NAME} ${r.action} in ${mcpJsonPath} (servers: ${r.servers.join(", ")})`);
+        process.exit(0);
+    }
+    console.error(`❌ ${r.error}`);
+    process.exit(1);
+}

package/dist/mirrorstore.js

@@ -0,0 +1,128 @@
+// Shared P7 mirror store (DL-68) — the `mirror.push` HANDLER logic (ticket-fetch → content-hash skip →
+// mapping-row-FIRST → reconcile-by-marker → create/update/skip/fail orchestration, the DL-11 side-effect-free
+// DRYRUN) + `mirror.status`, used by BOTH the MCP server (server.ts) and the daemon op-API (agentops.ts). The
+// Linear TRANSPORT (issueCreate/issueUpdate/findByMarker/the §16 token-never-thrown gql) stays in linear.ts and
+// is reused AS-IS; this module is the handler layer linear.ts's transport serves — the docstore/topicstore/
+// channelstore precedent that lets the stdio server and the daemon op-API share ONE implementation and never
+// drift (the DL-11 DRYRUN invariant + the reconcile-by-marker idempotency live in exactly one place).
+//
+// SIDE-EFFECT-FREE entrypoint (no top-level db; identity (actor) + scope (projectId) are passed in by the
+// caller — the daemon resolves the actor from X-Devloop-Actor, the stdio server passes its ACTOR — so every
+// mirror.push/mirror.error event is attributed to the REAL caller on both paths). `fetchImpl` is injectable
+// (default = the global fetch) so the adapter units can drive it; the live endpoint is env-overridable inside
+// linear.ts (DEVLOOP_LINEAR_API_URL), exactly as before — the MIRROR_OK suite relies on that, unchanged.
+//
+// §16: the Linear token is read SERVER-SIDE from env[tokenEnv]; the caller passes only the NAME (validated by
+// isEnvName, reused from channelstore — one definition, no drift). A literal token → a clean error, never
+// persisted/echoed; a failed Linear call throws only a scrubbed status/message (linear.ts) which the catch
+// records via scrubErr — the token never appears in any mirror.* response or event (the DL-52 invariant). §17
+// firewall (structural): every write here is an INSERT/UPDATE on the `mirror_map` DB table — there is NO
+// filesystem path anywhere in this module; the only external effect is the one-way network write via linear.ts
+// (the hub NEVER reads Linear as truth — findByMarker only reconciles its own mapping).
+import { randomUUID, createHash } from "node:crypto";
+import { nowIso, logEvent } from "./db.js";
+import { findByMarker, createIssue, updateIssue } from "./linear.js";
+import { scrubErr } from "./channel.js";
+import { isEnvName } from "./channelstore.js";
+// Read at module load (a const, byte-identical to server.ts's MIRROR_DRYRUN) — DEVLOOP_MIRROR_DRYRUN=1 makes
+// mirror.push side-effect-free: it previews the would-push `ops`, hits NO network, and persists NO mirror_map
+// row (DL-11). Set it in the spawned process env (the MIRROR_OK suite + the agent-api/shim npm scripts do).
+const MIRROR_DRYRUN = process.env.DEVLOOP_MIRROR_DRYRUN === "1";
+const MIRROR_BANNER = "> 🤖 Mirrored from the dev-loop hub — edits here are IGNORED and overwritten on the next push. Give direction via the Director (conventions §25).";
+const toTicket = (r) => ({
+    id: r.id, project_id: r.project_id, title: r.title, description: r.description, type: r.type,
+    state: r.state, assignee: r.assignee, priority: r.priority,
+    labels: JSON.parse(r.labels),
+    duplicateOf: r.duplicate_of, relatedTo: JSON.parse(r.related_to),
+    created_by: r.created_by, created_at: r.created_at, updated_at: r.updated_at,
+});
+const mirrorTitle = (t) => `${t.title} [hub:${t.id}]`;
+const mirrorBody = (t) => [
+    MIRROR_BANNER, "",
+    `**hub:** ${t.id} · **type:** ${t.type} · **state:** ${t.state} · **priority:** ${t.priority} · **owner:** ${t.assignee ?? "—"}`,
+    t.labels.length ? `**labels:** ${t.labels.join(", ")}` : "",
+    t.relatedTo.length ? `**related:** ${t.relatedTo.join(", ")}` : "",
+    t.duplicateOf ? `**duplicate of:** ${t.duplicateOf}` : "",
+    "", t.description || "_(no description)_",
+].filter((l) => l !== "").join("\n");
+const mirrorHash = (t, stateId) => createHash("sha256").update(JSON.stringify({ title: mirrorTitle(t), body: mirrorBody(t), stateId: stateId ?? null })).digest("hex");
+// ONE-WAY push: project hub tickets → Linear issues (create-or-update, idempotent + incremental). Verbatim
+// from server.ts (ACTOR → the passed `actor`, the global fetch → the injectable `fetchImpl`), so server.ts's
+// externally-observable behavior is unchanged. `db` MUST be a WRITABLE connection for a live push.
+export async function mirrorPush(db, projectId, actor, a, fetchImpl = fetch) {
+    if (!isEnvName(a.tokenEnv))
+        return { ok: false, error: `tokenEnv must be an ENV-VAR NAME (e.g. DEVLOOP_LINEAR_TOKEN), not the secret value itself` };
+    const token = process.env[a.tokenEnv];
+    if (!token && !MIRROR_DRYRUN)
+        return { ok: false, error: `mirror token env '${a.tokenEnv}' is unset` };
+    const rows = db.prepare("SELECT * FROM tickets WHERE project_id=? ORDER BY updated_at DESC LIMIT ?").all(projectId, a.limit ?? 500);
+    const tickets = rows.map(toTicket);
+    let created = 0, updated = 0, skipped = 0, failed = 0;
+    const ops = [];
+    for (const t of tickets) {
+        const stateId = a.stateMap?.[t.state]; // missing ⇒ undefined ⇒ no stateId (fallback: state is in the body)
+        const issue = { title: mirrorTitle(t), description: mirrorBody(t), stateId };
+        const hash = mirrorHash(t, stateId);
+        let row = db.prepare("SELECT id,hub_id,linear_id,last_pushed_hash FROM mirror_map WHERE project_id=? AND hub_kind='ticket' AND hub_id=?").get(projectId, t.id);
+        if (row && row.linear_id && row.last_pushed_hash === hash) {
+            skipped++;
+            continue;
+        } // incremental skip (unchanged)
+        if (!row) {
+            // mapping-row-FIRST: record intent BEFORE the remote create → a crash never orphans a Linear
+            // issue (a NULL-id row on the next fire reconciles by marker). The UNIQUE(project,kind,hub_id)
+            // makes two concurrent pushers' INSERTs serialize — the loser throws + retries (no dup row).
+            const rid = randomUUID();
+            // DRYRUN is side-effect-free (§12, DL-11): keep the mapping row IN MEMORY only. Persisting it
+            // poisons a later live push — an unchanged ticket is skipped (never created) and a changed one
+            // gets stuck updating a non-existent `dry-<id>`. The in-memory row still drives the logic + ops.
+            if (!MIRROR_DRYRUN)
+                db.prepare("INSERT INTO mirror_map(id,project_id,hub_kind,hub_id,created_at) VALUES (?,?,'ticket',?,?)").run(rid, projectId, t.id, nowIso());
+            row = { id: rid, hub_id: t.id, linear_id: null, last_pushed_hash: null };
+        }
+        try {
+            if (!row.linear_id) {
+                // ALWAYS reconcile-by-marker before creating (Codex review): closes the concurrent-create
+                // window (a racing pusher's issue is found, not duplicated), and on a crashed-create retry
+                // the existing issue is ADOPTED + UPDATED to current content (never left stale). A genuinely
+                // new ticket: findByMarker returns null → create. (Full concurrency-safety still assumes the
+                // single-Sweep-per-project model; a lease is over-engineering for one writer.)
+                const found = MIRROR_DRYRUN ? null : await findByMarker(fetchImpl, token, `[hub:${t.id}]`);
+                let linearId;
+                if (found) {
+                    await updateIssue(fetchImpl, token, found, issue);
+                    linearId = found;
+                } // adopt + push current content (fixes stale-reconcile)
+                else {
+                    linearId = MIRROR_DRYRUN ? `dry-${t.id}` : await createIssue(fetchImpl, token, a.teamId, a.projectId ?? null, issue);
+                }
+                if (!MIRROR_DRYRUN)
+                    db.prepare("UPDATE mirror_map SET linear_id=?, last_pushed_hash=?, last_pushed_at=? WHERE id=?").run(linearId, hash, nowIso(), row.id); // DRYRUN: never persist the dry-<id> sentinel/hash (DL-11)
+                created++;
+                ops.push({ op: found ? "reconcile" : "create", hubId: t.id, title: issue.title, body: issue.description, stateId: stateId ?? null });
+            }
+            else {
+                if (!MIRROR_DRYRUN)
+                    await updateIssue(fetchImpl, token, row.linear_id, issue);
+                if (!MIRROR_DRYRUN)
+                    db.prepare("UPDATE mirror_map SET last_pushed_hash=?, last_pushed_at=? WHERE id=?").run(hash, nowIso(), row.id); // DRYRUN: don't advance the persisted hash (DL-11)
+                updated++;
+                ops.push({ op: "update", hubId: t.id, title: issue.title, body: issue.description, stateId: stateId ?? null });
+            }
+        }
+        catch (e) {
+            // leave the row (linear_id as-is, hash NOT advanced) → next push retries; never persist the token
+            failed++;
+            logEvent(db, { project_id: projectId, actor, kind: "mirror.error", data: { hubId: t.id, error: scrubErr(e.message) } });
+        }
+    }
+    logEvent(db, { project_id: projectId, actor, kind: "mirror.push", data: { created, updated, skipped, failed } });
+    return { ok: true, data: { created, updated, skipped, failed, dryrun: MIRROR_DRYRUN, ...(MIRROR_DRYRUN ? { ops } : {}) } };
+}
+// mirror.status — coverage counts; no secret, no Linear read. Shared so server.ts + the op-API are byte-identical.
+export function mirrorStatus(db, projectId) {
+    const mapped = db.prepare("SELECT count(*) c FROM mirror_map WHERE project_id=? AND hub_kind='ticket'").get(projectId).c;
+    const tickets = db.prepare("SELECT count(*) c FROM tickets WHERE project_id=?").get(projectId).c;
+    const last = db.prepare("SELECT max(last_pushed_at) m FROM mirror_map WHERE project_id=?").get(projectId).m;
+    return { mapped, tickets, lastPush: last };
+}

package/dist/release-version.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+// `dev-loop release-version <semver>` — the SINGLE-VERSION stamp (P4, design daemon-multicli §6).
+// Writes ONE version into the three manifests that MUST ship in lockstep, so a release can never drift
+// (the marketplace-cache class of bug: a bumped plugin.json with a stale marketplace.json serves the old
+// cached SKILLs): hub/package.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json
+// (plugins[0].version). Surgical single-line text replace per file ⇒ a 1-line diff, formatting preserved.
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..", ".."); // hub/src → repo root
+const version = process.argv[2];
+if (!version || !/^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(version)) {
+    console.error(`usage: dev-loop release-version <semver>   (e.g. 0.21.0)\n  got: ${version ?? "(none)"}`);
+    process.exit(2);
+}
+const files = [
+    { rel: "hub/package.json", cur: (j) => j.version },
+    { rel: ".claude-plugin/plugin.json", cur: (j) => j.version },
+    { rel: ".claude-plugin/marketplace.json", cur: (j) => j.plugins[0].version },
+];
+let changed = 0;
+for (const f of files) {
+    const path = join(repoRoot, f.rel);
+    const txt = readFileSync(path, "utf8");
+    const cur = f.cur(JSON.parse(txt)); // validate it parses + locate the current value
+    if (cur === version) {
+        console.log(`= ${f.rel}: already ${version}`);
+        continue;
+    }
+    const needle = `"version": "${cur}"`; // the only version field in each file (plugins[0] in marketplace)
+    if (!txt.includes(needle)) {
+        console.error(`✗ ${f.rel}: could not find ${needle} to replace`);
+        process.exit(1);
+    }
+    writeFileSync(path, txt.replace(needle, `"version": "${version}"`));
+    console.log(`✓ ${f.rel}: ${cur} → ${version}`);
+    changed++;
+}
+console.log(`\nstamped ${version} into ${changed} manifest(s) (lockstep — package.json + plugin.json + marketplace.json).`);

package/dist/resolve-project.js

@@ -0,0 +1,82 @@
+// DL-13: resolve a project KEY from a cwd by matching it against the configured projects' repo paths, so
+// an agent launched inside a project folder auto-pins that project with no manual DEVLOOP_PROJECT. Pure +
+// side-effect-light so it is trivially unit-testable AND the launcher can reuse the SAME matcher via the
+// `dev-loop-hub resolve-project` subcommand (one rule, no prose/code drift). Backward-compatible: an
+// explicit DEVLOOP_PROJECT always wins (the caller checks that first); this runs only when it is unset.
+import { realpathSync, readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { relative, isAbsolute, join } from "node:path";
+// The candidate repo paths for a project (§19): repos[].path if present, else [repoPath].
+function projectPaths(p) {
+    if (p.repos?.length)
+        return p.repos.map((r) => r.path).filter((x) => !!x);
+    return p.repoPath ? [p.repoPath] : [];
+}
+// Is `child` the same as, or a descendant of, `parent` on a SEGMENT boundary — so `/work/repo` does NOT
+// match `/work/repo-2`? Both must be realpath-canonical absolute paths.
+function isWithin(child, parent) {
+    if (child === parent)
+        return true;
+    const rel = relative(parent, child);
+    return rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+}
+const canon = (p) => { try {
+    return realpathSync(p);
+}
+catch {
+    return null;
+} };
+// Resolve at most ONE project key whose repo path is the NEAREST ancestor of cwd. A tie between two
+// DISTINCT projects at the same longest depth → null (never guess); cwd outside every repo → null.
+export function resolveProjectFromCwd(cwd, config) {
+    const c = canon(cwd);
+    if (!c)
+        return null;
+    let best = null;
+    let tie = false;
+    for (const [key, proj] of Object.entries(config.projects ?? {})) {
+        for (const raw of projectPaths(proj)) {
+            const P = canon(raw);
+            if (!P || !isWithin(c, P))
+                continue;
+            const depth = P.length; // a longer canonical ancestor path = a nearer ancestor
+            if (!best || depth > best.depth) {
+                best = { key, depth };
+                tie = false;
+            }
+            else if (depth === best.depth && key !== best.key) {
+                tie = true;
+            }
+        }
+    }
+    return best && !tie ? best.key : null;
+}
+// DL-85: the ONE DEVLOOP_ACTOR + DEVLOOP_PROJECT/cwd identity resolution (was re-derived in server.ts:21-32
+// AND shim.ts:38-46). An EXPLICIT DEVLOOP_PROJECT wins; else resolve from cwd (DL-13); else the "demo" default.
+// `projectFromCwd` is true only on the cwd-resolved branch (server.ts uses it for a clearer not-seeded error).
+export function resolveIdentity() {
+    const actor = process.env.DEVLOOP_ACTOR ?? "operator"; // who this MCP client IS (the attribution win)
+    const explicit = process.env.DEVLOOP_PROJECT?.trim(); // a present-but-empty "" must NOT become the literal key
+    if (explicit)
+        return { actor, projectKey: explicit, projectFromCwd: false };
+    const cfg = loadProjectsConfig();
+    const resolved = cfg ? resolveProjectFromCwd(process.cwd(), cfg) : null;
+    return resolved ? { actor, projectKey: resolved, projectFromCwd: true } : { actor, projectKey: "demo", projectFromCwd: false };
+}
+// Locate + parse projects.json the way the skills do (§11): DEVLOOP_PROJECTS_JSON, then CLAUDE_PLUGIN_DATA,
+// then the canonical dev-loop data dir. Returns null when not found/parseable (caller keeps its default).
+export function loadProjectsConfig() {
+    const candidates = [
+        process.env.DEVLOOP_PROJECTS_JSON,
+        process.env.CLAUDE_PLUGIN_DATA ? join(process.env.CLAUDE_PLUGIN_DATA, "projects.json") : undefined,
+        join(homedir(), ".claude", "plugins", "data", "dev-loop", "projects.json"),
+    ].filter((x) => !!x);
+    for (const p of candidates) {
+        try {
+            if (existsSync(p))
+                return JSON.parse(readFileSync(p, "utf8"));
+        }
+        catch { /* try next */ }
+    }
+    return null;
+}

package/dist/seed.js

@@ -0,0 +1,76 @@
+// Idempotent bootstrap: a project, the agent/operator actors, and the §4 label taxonomy.
+// Run directly (`node src/seed.ts <key> <name>`) or called by the server on first run.
+import { randomUUID } from "node:crypto";
+import { openDb, nowIso } from "./db.js";
+// The live dev-loop agents + the human operator. P5 repurposed `signal` → `director`.
+// DL split (senior/junior dev): `senior-dev` + `junior-dev` join as ACTIVE actors; the legacy single
+// `dev` STAYS ACTIVE (NOT retired) — it remains the canonical single-pane fallback for non-split
+// projects (e.g. monpick on Linear), so adding the two-tier model breaks no existing project.
+const AGENT_HANDLES = ["pm", "qa", "dev", "senior-dev", "junior-dev", "sweep", "reflect", "ops", "architect", "director"];
+// `signal` retired into `director` (P5): kept as an INACTIVE actor so its historical comment/event
+// attribution stays readable, but refused for NEW writes (actorExists/G1 filter active=1).
+const RETIRED_HANDLES = ["signal"];
+// §4 label taxonomy (+ the `notified` workflow label from §9 notify).
+const LABELS = [
+    { name: "dev-loop", kind: "marker" },
+    { name: "Feature", kind: "type" }, { name: "Bug", kind: "type" }, { name: "Improvement", kind: "type" },
+    { name: "pm", kind: "owner" }, { name: "qa", kind: "owner" },
+    // DL split: dev-tier ROUTING labels (per-backend §18 encoding — the label distinguishes the dev tier
+    // on shared-identity backends where `assignee` cannot). Distinct from the pm/qa VERIFIER owner labels;
+    // ride this INSERT-OR-IGNORE backfill, no migration (plain strings, like the §4 labels).
+    { name: "senior-dev", kind: "owner" }, { name: "junior-dev", kind: "owner" },
+    { name: "edge-case", kind: "subtype" }, { name: "incident", kind: "subtype" },
+    { name: "tech-debt", kind: "subtype" }, { name: "signal", kind: "subtype" }, { name: "coverage", kind: "subtype" },
+    { name: "blocked", kind: "workflow" }, { name: "needs-pm", kind: "workflow" },
+    { name: "needs-qa", kind: "workflow" }, { name: "notified", kind: "workflow" },
+    // DL-32 (design §7): release/env labels — no new state, no schema ALTER. They ride this ensureLabels
+    // backfill (INSERT OR IGNORE, idempotent), not a dedicated migration.
+    { name: "env:dev", kind: "workflow" }, { name: "env:prod", kind: "workflow" },
+];
+export function ensureActors(db) {
+    const ins = db.prepare("INSERT OR IGNORE INTO actors(id,handle,kind,display_name,active,created_at) VALUES (?,?,?,?,?,?)");
+    for (const h of AGENT_HANDLES)
+        ins.run(randomUUID(), h, "agent", h.toUpperCase(), 1, nowIso());
+    for (const h of RETIRED_HANDLES)
+        ins.run(randomUUID(), h, "agent", h.toUpperCase(), 0, nowIso());
+    ins.run(randomUUID(), "operator", "human", "Operator", 1, nowIso());
+}
+export function findProject(db, key) {
+    const r = db.prepare("SELECT id FROM projects WHERE key=?").get(key);
+    return r?.id ?? null;
+}
+export function ensureProject(db, key, name, prefix = "DL") {
+    const existing = db.prepare("SELECT id FROM projects WHERE key=?").get(key);
+    if (existing)
+        return existing.id;
+    // ticket ids are a GLOBAL primary key, so two projects sharing one hub.db MUST have distinct
+    // prefixes or their tickets collide on insert (the real multi-project bug P3 closes).
+    const clash = db.prepare("SELECT key FROM projects WHERE ticket_prefix=?").get(prefix);
+    if (clash)
+        throw new Error(`ticket prefix '${prefix}' already used by project '${clash.key}'; pick a unique prefix for '${key}'`);
+    const id = randomUUID();
+    db.prepare("INSERT INTO projects(id,key,name,ticket_prefix,ticket_seq,created_at) VALUES (?,?,?,?,0,?)").run(id, key, name, prefix, nowIso());
+    const insL = db.prepare("INSERT OR IGNORE INTO labels(id,project_id,name,kind) VALUES (?,?,?,?)");
+    for (const l of LABELS)
+        insL.run(randomUUID(), id, l.name, l.kind);
+    return id;
+}
+export function ensureSeed(db, key, name, prefix = "DL") {
+    ensureActors(db);
+    return ensureProject(db, key, name, prefix);
+}
+// CLI: node src/seed.ts <key> <name> [prefix] [dbpath]
+if (import.meta.url === `file://${process.argv[1]}`) {
+    const args = process.argv.slice(2);
+    // --help/-h is the near-universal convention; guard it BEFORE binding argv[0] to `key`, or it
+    // silently seeds a junk project literally keyed `--help` + its actors + labels (DL-88).
+    if (args[0] === "--help" || args[0] === "-h") {
+        console.log("Usage: seed <key> <name> [PREFIX] [DBPATH]  — seed a project + actors + labels into the hub db");
+        process.exit(0);
+    }
+    const [key = "demo", name = "Demo Project", prefix = "DL", dbPath = process.env.DEVLOOP_HUB_DB ?? "./hub.db"] = args;
+    const db = openDb(dbPath);
+    const id = ensureSeed(db, key, name, prefix);
+    console.log(`seeded project ${key} (${id}) + actors + labels in ${dbPath}`);
+    db.close();
+}

package/dist/server.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+// dev-loop hub — stdio MCP server. The loop's system of record for ONE project.
+// Identity rides DEVLOOP_ACTOR (launcher-set per pane); project rides DEVLOOP_PROJECT; db DEVLOOP_HUB_DB.
+// Tools mirror the Linear MCP op-shapes 1:1 so the agent SKILLs port unchanged (conventions §18).
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { homedir } from "node:os";
+import { openDb, actorExists, listActorHandles } from "./db.js";
+import { ensureActors, ensureProject, findProject } from "./seed.js";
+import { createLabel } from "./labelstore.js"; // DL-69: create_issue_label stays a native handler (see agentops.ts opCreateLabel — the only op server.ts does NOT dispatch through, to keep the stdio path byte-identical)
+import { resolveProjectFromCwd, loadProjectsConfig, resolveIdentity } from "./resolve-project.js";
+import { agentOp } from "./agentops.js"; // DL-69: the SINGLE definition of every ticket/read policy — every op-backed handler below dispatches through agentOp()
+import { ok, err, registerTools } from "./tooldefs.js"; // DL-85: the ONE {name,description,inputSchema} registry + the shared ok()/err()
+// ─── Environment / identity ──────────────────────────────────────────────────
+const DB_PATH = process.env.DEVLOOP_HUB_DB ?? `${homedir()}/.dev-loop/hub.db`;
+// DL-85: the DEVLOOP_ACTOR + DEVLOOP_PROJECT/cwd resolution lives ONCE in resolve-project.ts (was re-derived
+// here AND in shim.ts). An EXPLICIT DEVLOOP_PROJECT wins; else cwd-resolve (DL-13: an agent launched inside a
+// project folder auto-pins it); else the "demo" default. projectFromCwd drives the clearer not-seeded error below.
+const { actor: ACTOR, projectKey: PROJECT_KEY, projectFromCwd } = resolveIdentity();
+// `dev-loop-hub resolve-project [--cwd <path>]` (DL-13) — print the project KEY whose repo CONTAINS the
+// cwd (default: process.cwd()), or exit non-zero with no output. The launcher reuses THIS matcher so the
+// launcher, the hub fallback, and any prose agree on exactly ONE rule.
+if (process.argv[2] === "resolve-project") {
+    const cwd = process.argv[3] === "--cwd" && process.argv[4] ? process.argv[4] : process.cwd();
+    const cfg = loadProjectsConfig();
+    const key = cfg ? resolveProjectFromCwd(cwd, cfg) : null;
+    if (key) {
+        console.log(key);
+        process.exit(0);
+    }
+    process.exit(1); // no match → empty stdout, non-zero → the launcher leaves DEVLOOP_PROJECT unset
+}
+// `dev-loop-hub doctor` — read-only health check (no server, no auto-create).
+if (process.argv[2] === "doctor") {
+    const { runDoctor } = await import("./doctor.js");
+    process.exit((await runDoctor(DB_PATH, { reconcile: true })) ? 0 : 1);
+}
+// `dev-loop-hub identity-check [--expect <actor>[/<project>]]` — P8 portability helper: print what THIS
+// process's env resolves to (the per-agent identity the hub would attribute writes to) + whether the
+// server would start. NOTE: this reflects the CURRENT process env; the REAL per-CLI gate is calling
+// `whoami` THROUGH the CLI's MCP spawn (docs/PORTABILITY.md) — only that proves the CLI propagates env
+// to the spawned subprocess. With `--expect` (or DEVLOOP_EXPECT_ACTOR / DEVLOOP_EXPECT_PROJECT) it ALSO
+// catches MIS-attribution: a wrong-but-valid actor (Codex review) fails, not just an unknown one. Exit 1
+// if the actor would be REFUSED (db present + unknown actor → the G1 guard) OR mismatches the expectation.
+if (process.argv[2] === "identity-check") {
+    const { existsSync } = await import("node:fs");
+    const expFlag = process.argv[3] === "--expect" ? process.argv[4] : undefined;
+    const expectActor = (expFlag?.split("/")[0]) || process.env.DEVLOOP_EXPECT_ACTOR || undefined;
+    const expectProject = (expFlag?.split("/")[1]) || process.env.DEVLOOP_EXPECT_PROJECT || undefined;
+    const dbPresent = existsSync(DB_PATH);
+    let actorKnown = null;
+    if (dbPresent) {
+        try {
+            const d = openDb(DB_PATH);
+            actorKnown = actorExists(d, ACTOR);
+            d.close();
+        }
+        catch {
+            actorKnown = null;
+        }
+    }
+    const matchesExpectation = (!expectActor || expectActor === ACTOR) && (!expectProject || expectProject === PROJECT_KEY);
+    const wouldStart = !dbPresent || actorKnown === true; // db absent ⇒ would be seeded; else the actor must be known
+    const pass = wouldStart && matchesExpectation;
+    console.log(JSON.stringify({ actor: ACTOR, project: PROJECT_KEY, db: DB_PATH, dbPresent, actorKnown, wouldStart, expectActor: expectActor ?? null, expectProject: expectProject ?? null, matchesExpectation, pass }));
+    process.exit(pass ? 0 : 1);
+}
+// `dev-loop-hub daemon <up|down|status>` — DL-41 per-project daemon lifecycle (the named command the
+// DL-42 auto-start hook invokes). Delegated to daemon-lifecycle.ts (DL-74 extracted it from daemon.ts);
+// importing it is side-effect-free here (that module is pure declarations — no top-level boot), so the
+// MCP boot path below is 100% untouched — the bare `dev-loop-hub` (argv[2] undefined) skips this block.
+if (process.argv[2] === "daemon") {
+    const { daemonLifecycle, LIFECYCLE_SUBS } = await import("./daemon-lifecycle.js");
+    const sub = process.argv[3] ?? "";
+    if (!LIFECYCLE_SUBS.includes(sub)) {
+        console.error(`[hub] usage: dev-loop-hub daemon <${LIFECYCLE_SUBS.join("|")}> (got '${sub || "—"}')`);
+        process.exit(2);
+    }
+    await daemonLifecycle(sub); // resolves project from env/cwd; calls process.exit
+}
+const db = openDb(DB_PATH);
+ensureActors(db); // the 8 agents + operator are always present (needed for attribution + the guard below)
+// P3/G1 — phantom-actor guard: a typo'd DEVLOOP_ACTOR would silently write an unattributable
+// author into created_by / events.actor / comments.author. Refuse to start instead (exit non-zero
+// ⇒ the MCP client can't connect ⇒ the failure is visible to the launching pane).
+if (!actorExists(db, ACTOR)) {
+    console.error(`[hub] DEVLOOP_ACTOR='${ACTOR}' is not a known actor. Valid: ${listActorHandles(db).join(", ")}. Fix DEVLOOP_ACTOR in the launcher.`);
+    process.exit(1);
+}
+// P3/G2 — phantom-project guard: a typo'd DEVLOOP_PROJECT must NOT silently auto-create an empty
+// board the agent then works in by mistake. The project must already exist; create it deliberately
+// once (`node src/seed.ts <key> <name> <UNIQUE_PREFIX>`) or opt in with DEVLOOP_CREATE_PROJECT=1.
+const projectId = process.env.DEVLOOP_CREATE_PROJECT === "1"
+    ? ensureProject(db, PROJECT_KEY, process.env.DEVLOOP_PROJECT_NAME ?? PROJECT_KEY, process.env.DEVLOOP_TICKET_PREFIX ?? "DL")
+    : findProject(db, PROJECT_KEY);
+if (!projectId) {
+    // DL-13: a cwd-RESOLVED project that isn't seeded errors LOUDLY here (clear source) — it must not have
+    // silently fallen through to `demo` (it didn't: a cwd match returns the real key, which lands here).
+    const src = projectFromCwd ? `resolved from cwd '${process.cwd()}'` : `from DEVLOOP_PROJECT='${PROJECT_KEY}'`;
+    console.error(`[hub] project '${PROJECT_KEY}' (${src}) is not seeded in the hub DB. Create it once: \`node ${import.meta.dirname}/seed.ts ${PROJECT_KEY} "<name>" <UNIQUE_PREFIX>\` (or set DEVLOOP_CREATE_PROJECT=1). Refusing to auto-create a phantom board.`);
+    process.exit(1);
+}
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+// ok()/err() (the MCP result shape) are imported from tooldefs.ts (DL-85) — one definition, shared with shim.ts.
+// ─── DL-69 dispatch-sharing: every op-backed handler is a thin call-through to the shared agentOp() ──────
+// Each ticket/read policy lives ONCE in agentops.ts; dispatch() forwards the zod-validated args to agentOp()
+// and maps the returned { status, body } to the MCP ok()/err() shape via toMcp() — the SAME mapping the DL-55
+// stdio shim applies to the op-API HTTP response (200 → ok(body); non-200 → err(body.error)), so a dispatched
+// handler is BYTE-IDENTICAL to the pre-refactor native one (the differential-parity suite, shim ≡ stdio for all
+// 29 tools, is the structural guard). agentOp reads NO env/mode/transport (the agentops.ts contract): server.ts
+// owns the DEVLOOP_ACTOR identity + the G1 guard (above) and passes ACTOR in; the daemon op-API owns its own
+// pipeline around the SAME ops. whoami + create_issue_label stay native below (see the makeHandler overrides).
+const toMcp = (r) => (r.status === 200 ? ok(r.body) : err(r.body.error));
+const dispatch = async (op, a) => toMcp(await agentOp(op, db, projectId, PROJECT_KEY, ACTOR, (a ?? {})));
+const server = new McpServer({ name: "dev-loop-hub", version: "0.1.0" });
+// ─── register the 29 tools from the ONE shared registry (DL-85) ────────────────────────────────────────────
+// tooldefs.ts owns every tool's { name, description, inputSchema }; this server supplies only the per-name
+// handler. The DEFAULT handler dispatches the op through agentOp() (above). Two tools are NATIVE (not ops):
+//   • whoami — answered locally from THIS process's resolved identity ({actor, project, db}).
+//   • create_issue_label — DL-69 kept native (a direct createLabel call) so the stdio path stays byte-identical
+//     and does NOT emit the op-API-only label.create event; every other tool dispatches through agentOp().
+registerTools(server, (name) => {
+    if (name === "whoami")
+        return () => ok({ actor: ACTOR, project: PROJECT_KEY, db: DB_PATH });
+    if (name === "create_issue_label") {
+        return (a) => {
+            const { name: labelName, kind } = a;
+            const r = createLabel(db, projectId, { name: labelName, kind });
+            return r.ok ? ok(r.data) : err(r.error);
+        };
+    }
+    return (a) => dispatch(name, a);
+});
+await server.connect(new StdioServerTransport());