maxsimcli 4.0.2 → 4.2.0

package/dist/assets/templates/workflows/sdd.md

@@ -0,0 +1,426 @@
+<sanity_check>
+Before executing any step in this workflow, verify:
+1. The current directory contains a `.planning/` folder — if not, stop and tell the user to run `/maxsim:new-project` first.
+2. `.planning/ROADMAP.md` exists — if not, stop and tell the user to initialize the project.
+</sanity_check>
+
+<purpose>
+Execute phase plans sequentially using fresh-context subagents with mandatory 2-stage review between every task. Each task agent receives only the minimum context it needs. Review is a hard gate — no task starts until the previous task passes both review stages.
+</purpose>
+
+<core_principle>
+Fresh context per task. No context bleeding between tasks. Review is mandatory, never skippable. Previous task's full diff and conversation are NEVER passed to the next task agent.
+</core_principle>
+
+<required_reading>
+Read STATE.md before any operation to load project context.
+
+@./references/dashboard-bridge.md
+</required_reading>
+
+<process>
+
+<step name="initialize" priority="first">
+Reuse the execute-phase init to load phase directory, plans, and model configuration:
+
+```bash
+INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init execute-phase "${PHASE_ARG}")
+```
+
+Parse JSON for: `executor_model`, `verifier_model`, `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `plans`, `incomplete_plans`, `plan_count`, `incomplete_count`, `state_exists`, `roadmap_exists`, `phase_req_ids`.
+
+**If `phase_found` is false:** Error — phase directory not found.
+**If `plan_count` is 0:** Error — no plans found in phase.
+</step>
+
+<step name="discover_plans">
+Find incomplete plans — skip any plan that already has a matching SUMMARY.md:
+
+```bash
+PLAN_INDEX=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs phase-plan-index "${PHASE_NUMBER}")
+```
+
+Parse JSON for: `plans[]` (each with `id`, `objective`, `files_modified`, `task_count`, `has_summary`), `incomplete`.
+
+**Filtering:** Skip plans where `has_summary: true`. If all plans complete: "All plans in phase already have summaries" — exit.
+
+Report:
+```
+## SDD Execution Plan
+
+**Phase {X}: {Name}** — {incomplete_count} plans to execute
+
+| Plan | Tasks | Objective |
+|------|-------|-----------|
+| 01-01 | 5 | {from plan objective, 5-10 words} |
+| 01-02 | 3 | ... |
+
+**Mode:** Spec-Driven Dispatch — fresh agent per task, 2-stage review between tasks
+```
+</step>
+
+<step name="load_plan">
+For each incomplete plan, read the plan file and extract the ordered task list:
+
+```bash
+cat ${PHASE_DIR}/${PLAN_FILE}
+```
+
+Extract for each task:
+- **Task number** (sequential order in plan)
+- **Task name**
+- **Description** (what to implement)
+- **Acceptance criteria** (done criteria from plan)
+- **Relevant files** (files to read and/or modify)
+- **Done criteria** (verification steps)
+
+Store as structured task list for the dispatch loop.
+</step>
+
+<step name="dispatch_loop">
+For each task in order within the current plan:
+
+**4a — Assemble Context**
+
+Build minimal context for the task agent. Include ONLY:
+- Task description and acceptance criteria
+- Relevant files list (files to read and modify)
+- Previous task commit hashes and files modified (NOT full diffs, NOT previous agent conversations)
+- Project CLAUDE.md (if exists) for coding conventions
+- .skills/ SKILL.md files (if exist) for relevant project rules
+
+Context table (SDD principle):
+| Item | Include? |
+|------|----------|
+| Task description + acceptance criteria | ALWAYS |
+| Relevant files list | ALWAYS |
+| Project CLAUDE.md | ALWAYS (if exists) |
+| Previous task commit hash + files modified | YES (minimal summary only) |
+| Previous task full diff | NEVER |
+| Previous agent conversation | NEVER |
+| Full plan file | NO (only current task extracted) |
+
+**4b — Spawn Executor**
+
+Fresh `maxsim-executor` agent with minimal context:
+
+```
+Task(
+  subagent_type="maxsim-executor",
+  model="{executor_model}",
+  prompt="
+    <objective>
+    Execute task {task_number} of plan {plan_id} in phase {phase_number}-{phase_name}.
+    Commit atomically when done.
+    </objective>
+
+    <task>
+    Name: {task_name}
+    Description: {task_description}
+    Acceptance criteria: {acceptance_criteria}
+    Done criteria: {done_criteria}
+    </task>
+
+    <files_to_read>
+    Read these files at execution start using the Read tool:
+    - {relevant_files list}
+    - ./CLAUDE.md (Project instructions, if exists — follow coding conventions)
+    - .skills/ (Project skills, if exists — read SKILL.md for each, follow relevant rules)
+    </files_to_read>
+
+    <previous_task_context>
+    {If first task: 'This is the first task in the plan.'}
+    {If not first: 'Previous task committed as {commit_hash}. Files modified: {file_list}. Do NOT re-read or re-implement previous work.'}
+    </previous_task_context>
+
+    <commit_protocol>
+    After implementation:
+    1. Run tests relevant to changed files
+    2. Stage files individually (NEVER git add . or git add -A)
+    3. Commit: {type}({phase}-{plan}): {description}
+    4. Report: commit hash, files modified, tests run
+    </commit_protocol>
+
+    <success_criteria>
+    - [ ] All acceptance criteria met
+    - [ ] Done criteria verified
+    - [ ] Tests pass
+    - [ ] Atomic commit created
+    </success_criteria>
+  "
+)
+```
+
+Record the commit hash from the executor's output.
+
+**4c — Review Stage 1: Spec Compliance**
+
+Spawn `maxsim-spec-reviewer` to verify implementation matches task spec:
+
+```
+Task(
+  subagent_type="maxsim-spec-reviewer",
+  model="{executor_model}",
+  prompt="
+    <objective>
+    Review task {task_number} of plan {plan_id} for spec compliance.
+    </objective>
+
+    <task_spec>
+    Name: {task_name}
+    Description: {task_description}
+    Acceptance criteria: {acceptance_criteria}
+    Done criteria: {done_criteria}
+    Relevant files: {relevant_files}
+    </task_spec>
+
+    <commit>
+    Commit hash: {task_commit_hash}
+    </commit>
+
+    <instructions>
+    1. Read each file in the relevant files list
+    2. Verify every acceptance criterion is met in the implementation
+    3. Verify done criteria pass
+    4. Check that ONLY specified files were modified (run: git diff --name-only {task_commit_hash}^..{task_commit_hash})
+    5. Report verdict: PASS or FAIL
+    6. If FAIL: list each unmet criterion with specific details
+    </instructions>
+  "
+)
+```
+
+**4d — Review Stage 2: Code Quality**
+
+Spawn `maxsim-code-reviewer` to check for bugs, edge cases, and conventions:
+
+```
+Task(
+  subagent_type="maxsim-code-reviewer",
+  model="{executor_model}",
+  prompt="
+    <objective>
+    Review task {task_number} of plan {plan_id} for code quality.
+    Spec compliance already verified.
+    </objective>
+
+    <commit>
+    Commit hash: {task_commit_hash}
+    Files modified: {files_from_commit}
+    </commit>
+
+    <instructions>
+    1. Read CLAUDE.md for project conventions
+    2. Read each modified file
+    3. Check for: bugs, unhandled edge cases, missing error handling, convention violations, security issues
+    4. Categorize: BLOCKER (must fix) or ADVISORY (note for later)
+    5. Report verdict: PASS (no blockers) or FAIL (list blocking issues)
+    </instructions>
+  "
+)
+```
+
+**4e — Handle Failure**
+
+If EITHER review stage returns FAIL:
+
+1. Spawn a NEW fresh executor agent with:
+   - Original task spec (description + acceptance criteria)
+   - Review feedback (specific failures from reviewer)
+   - Current file state (files to read, NOT previous agent conversation)
+   - Instruction: fix ONLY the review issues, do NOT add new features
+
+```
+Task(
+  subagent_type="maxsim-executor",
+  model="{executor_model}",
+  prompt="
+    <objective>
+    Fix review failures for task {task_number} of plan {plan_id}.
+    Fix ONLY the issues listed below. Do NOT add new features or refactor beyond what is required.
+    </objective>
+
+    <original_task>
+    Name: {task_name}
+    Description: {task_description}
+    Acceptance criteria: {acceptance_criteria}
+    </original_task>
+
+    <review_failures>
+    {spec_review_failures if any}
+    {code_review_failures if any}
+    </review_failures>
+
+    <files_to_read>
+    {files modified by previous attempt — read current state}
+    </files_to_read>
+
+    <commit_protocol>
+    Stage and commit fixes: fix({phase}-{plan}): address review feedback for task {task_number}
+    </commit_protocol>
+  "
+)
+```
+
+2. Re-run BOTH review stages (4c and 4d) on the fix commit
+3. **Cap at 3 fix attempts.** If still failing after 3 attempts: STOP and escalate to user.
+
+```
+## TASK BLOCKED — Review Failed After 3 Fix Attempts
+
+**Task:** {task_number} - {task_name}
+**Plan:** {plan_id}
+**Phase:** {phase_number} - {phase_name}
+
+### Unresolved Review Failures
+{remaining failures from last review}
+
+### Fix Attempt History
+| Attempt | Spec Review | Code Review | Commit |
+|---------|-------------|-------------|--------|
+| 1 | {PASS/FAIL} | {PASS/FAIL} | {hash} |
+| 2 | {PASS/FAIL} | {PASS/FAIL} | {hash} |
+| 3 | {PASS/FAIL} | {PASS/FAIL} | {hash} |
+
+Options:
+- "fix manually" — You fix the issues, then resume
+- "skip task" — Mark incomplete, continue to next task
+- "stop" — Halt SDD execution
+```
+
+**4f — Advance**
+
+After both reviews PASS, record task completion:
+- Commit hash
+- Files modified
+
+Pass ONLY this minimal summary to the next task context. Do NOT pass:
+- Full diff output
+- Review conversation content
+- Previous agent's reasoning or approach
+
+**4g — Report Task**
+
+Display task completion:
+
+```
+---
+## Task {N}/{total}: {task_name} — COMPLETE
+
+**Commit:** {commit_hash}
+**Files:** {files_modified_count} modified
+**Spec Review:** PASS
+**Code Review:** PASS
+{If fix iterations > 0: **Fix Iterations:** {count}}
+
+{If more tasks: Dispatching next task...}
+---
+```
+</step>
+
+<step name="create_summary">
+After all tasks in a plan complete, create SUMMARY.md:
+
+```bash
+# Get the summary template
+cat ~/.claude/maxsim/templates/summary.md
+```
+
+Create `{phase}-{plan}-SUMMARY.md` in the phase directory. Include:
+
+**Frontmatter:** phase, plan, subsystem, tags, requires/provides/affects, tech-stack, key-files.created/modified, key-decisions, requirements-completed (copy from PLAN.md frontmatter), duration, completed date.
+
+**Body:**
+- One-liner: substantive description of what was built
+- Per-task status table:
+
+```markdown
+## Task Execution (SDD)
+
+| Task | Name | Status | Commit | Fix Iterations |
+|------|------|--------|--------|----------------|
+| 1 | {name} | PASS | {hash} | 0 |
+| 2 | {name} | PASS | {hash} | 1 |
+| 3 | {name} | PASS | {hash} | 0 |
+
+**Execution mode:** Spec-Driven Dispatch (fresh agent per task, 2-stage review)
+```
+
+- Review summary per task
+- Deviations (if any)
+- Issues encountered
+
+Use `node ~/.claude/maxsim/bin/maxsim-tools.cjs` for template operations as needed.
+
+Self-check:
+- Verify first 2 files from `key-files.created` exist on disk
+- Check `git log --oneline --all --grep="{phase}-{plan}"` returns commits
+- Append `## Self-Check: PASSED` or `## Self-Check: FAILED`
+</step>
+
+<step name="update_state">
+Standard state updates after plan completion:
+
+```bash
+# Advance plan counter
+node ~/.claude/maxsim/bin/maxsim-tools.cjs state advance-plan
+
+# Recalculate progress
+node ~/.claude/maxsim/bin/maxsim-tools.cjs state update-progress
+
+# Record execution metrics
+node ~/.claude/maxsim/bin/maxsim-tools.cjs state record-metric \
+  --phase "${PHASE}" --plan "${PLAN}" --duration "${DURATION}" \
+  --tasks "${TASK_COUNT}" --files "${FILE_COUNT}"
+
+# Record session
+node ~/.claude/maxsim/bin/maxsim-tools.cjs state record-session \
+  --stopped-at "Completed ${PHASE}-${PLAN}-PLAN.md (SDD)" \
+  --resume-file "None"
+
+# Update roadmap progress
+node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap update-plan-progress "${PHASE}"
+
+# Mark requirements complete (if plan has requirements field)
+node ~/.claude/maxsim/bin/maxsim-tools.cjs requirements mark-complete ${REQ_IDS}
+```
+</step>
+
+<step name="git_commit_metadata">
+Task code already committed per-task. Commit planning artifacts:
+
+```bash
+node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs({phase}-{plan}): complete SDD execution" --files .planning/phases/${PHASE_DIR_NAME}/${PHASE}-${PLAN}-SUMMARY.md .planning/STATE.md .planning/ROADMAP.md .planning/REQUIREMENTS.md
+```
+</step>
+
+<step name="offer_next">
+After all plans in the phase are processed:
+
+```bash
+ls -1 .planning/phases/${PHASE_DIR_NAME}/*-PLAN.md 2>/dev/null | wc -l
+ls -1 .planning/phases/${PHASE_DIR_NAME}/*-SUMMARY.md 2>/dev/null | wc -l
+```
+
+| Condition | Route | Action |
+|-----------|-------|--------|
+| summaries < plans | **A: More plans** | Find next incomplete plan. Show next plan, suggest `/maxsim:sdd {phase}` to continue. |
+| summaries = plans, more phases exist | **B: Phase done** | Show completion, suggest `/maxsim:verify-work {phase}` then `/maxsim:plan-phase {next}`. |
+| summaries = plans, last phase | **C: Milestone done** | Show banner, suggest `/maxsim:complete-milestone` + `/maxsim:verify-work`. |
+
+All routes: recommend `/clear` first for fresh context.
+</step>
+
+</process>
+
+<failure_handling>
+- **Task agent fails (no commit):** Report failure, ask user: retry task or skip
+- **Review agent fails to return verdict:** Treat as FAIL, re-run review
+- **3 fix attempts exhausted:** Hard stop on task, escalate to user with full history
+- **classifyHandoffIfNeeded bug:** If agent reports "failed" with `classifyHandoffIfNeeded is not defined` — Claude Code runtime bug. Spot-check (commit exists, files modified) — if pass, treat as success
+- **All tasks in plan blocked:** Stop plan, report to user, suggest manual intervention
+</failure_handling>
+
+<resumption>
+Re-run `/maxsim:sdd {phase}` — discover_plans finds completed SUMMARYs, skips them, resumes from first incomplete plan. Within a plan, completed tasks (those with commits matching the plan pattern) can be detected and skipped.
+</resumption>

package/dist/backend/index.d.ts

@@ -0,0 +1,4 @@
+export type { BackendConfig, BackendStatus, BackendLockFile, WSMessage, BackendServer, PendingQuestion, LifecycleEvent, } from './types.js';
+export { createBackendServer } from './server.js';
+export { startBackend, stopBackend, getBackendStatus, isBackendRunning, findBackendPort, } from './lifecycle.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/backend/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,SAAS,EACT,aAAa,EACb,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EACL,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,gBAAgB,CAAC"}

package/dist/backend/index.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findBackendPort = exports.isBackendRunning = exports.getBackendStatus = exports.stopBackend = exports.startBackend = exports.createBackendServer = void 0;
+var server_js_1 = require("./server.js");
+Object.defineProperty(exports, "createBackendServer", { enumerable: true, get: function () { return server_js_1.createBackendServer; } });
+var lifecycle_js_1 = require("./lifecycle.js");
+Object.defineProperty(exports, "startBackend", { enumerable: true, get: function () { return lifecycle_js_1.startBackend; } });
+Object.defineProperty(exports, "stopBackend", { enumerable: true, get: function () { return lifecycle_js_1.stopBackend; } });
+Object.defineProperty(exports, "getBackendStatus", { enumerable: true, get: function () { return lifecycle_js_1.getBackendStatus; } });
+Object.defineProperty(exports, "isBackendRunning", { enumerable: true, get: function () { return lifecycle_js_1.isBackendRunning; } });
+Object.defineProperty(exports, "findBackendPort", { enumerable: true, get: function () { return lifecycle_js_1.findBackendPort; } });
+//# sourceMappingURL=index.js.map

package/dist/backend/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/backend/index.ts"],"names":[],"mappings":";;;AASA,yCAAkD;AAAzC,gHAAA,mBAAmB,OAAA;AAC5B,+CAMwB;AALtB,4GAAA,YAAY,OAAA;AACZ,2GAAA,WAAW,OAAA;AACX,gHAAA,gBAAgB,OAAA;AAChB,gHAAA,gBAAgB,OAAA;AAChB,+GAAA,eAAe,OAAA"}

package/dist/backend/lifecycle.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Backend Lifecycle — Start, stop, health check, discovery
+ */
+import type { BackendLockFile, BackendStatus } from './types.js';
+export declare function startBackend(projectCwd: string, opts?: {
+    port?: number;
+    background?: boolean;
+}): Promise<BackendLockFile>;
+export declare function stopBackend(projectCwd: string): Promise<boolean>;
+export declare function getBackendStatus(projectCwd: string): Promise<BackendStatus | null>;
+export declare function isBackendRunning(projectCwd: string): Promise<boolean>;
+export declare function findBackendPort(projectCwd: string): number | null;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/backend/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/backend/lifecycle.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAgEjE,wBAAsB,YAAY,CAChC,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,GAC7C,OAAO,CAAC,eAAe,CAAC,CA6D1B;AAED,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAoBtE;AAED,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAYxF;AAED,wBAAsB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAG3E;AAED,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGjE"}

package/dist/backend/lifecycle.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Backend Lifecycle — Start, stop, health check, discovery
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startBackend = startBackend;
+exports.stopBackend = stopBackend;
+exports.getBackendStatus = getBackendStatus;
+exports.isBackendRunning = isBackendRunning;
+exports.findBackendPort = findBackendPort;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const LOCK_FILE = '.planning/.backend-lock';
+/**
+ * Derive a deterministic port for a project path (range 3100-3199).
+ * Simple hash mapped to 100-port range.
+ */
+function projectPort(projectCwd) {
+    let hash = 0;
+    for (const ch of projectCwd) {
+        hash = ((hash << 5) - hash + ch.charCodeAt(0)) | 0;
+    }
+    return 3100 + (Math.abs(hash) % 100);
+}
+function lockFilePath(projectCwd) {
+    return node_path_1.default.join(projectCwd, LOCK_FILE);
+}
+function readLockFile(projectCwd) {
+    try {
+        return JSON.parse(node_fs_1.default.readFileSync(lockFilePath(projectCwd), 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+function writeLockFile(projectCwd, data) {
+    const lockPath = lockFilePath(projectCwd);
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(lockPath), { recursive: true });
+    node_fs_1.default.writeFileSync(lockPath, JSON.stringify(data, null, 2), 'utf-8');
+}
+function removeLockFile(projectCwd) {
+    const lockPath = lockFilePath(projectCwd);
+    try {
+        node_fs_1.default.unlinkSync(lockPath);
+    }
+    catch {
+        // may not exist
+    }
+}
+/**
+ * Make an HTTP request and return the parsed JSON body.
+ * Uses native fetch (Node 22+).
+ */
+async function httpJson(method, url, timeoutMs = 5000) {
+    try {
+        const res = await fetch(url, {
+            method,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        if (!res.ok)
+            return null;
+        return await res.json();
+    }
+    catch {
+        return null;
+    }
+}
+async function startBackend(projectCwd, opts) {
+    // 1. Check if already running
+    const existing = await getBackendStatus(projectCwd);
+    if (existing && existing.status === 'ok') {
+        return readLockFile(projectCwd);
+    }
+    // 2. Choose port
+    const port = opts?.port ?? projectPort(projectCwd);
+    const background = opts?.background ?? true;
+    if (background) {
+        // Spawn detached child process running backend-server.cjs
+        const serverScript = node_path_1.default.join(__dirname, 'backend-server.cjs');
+        const child = (0, node_child_process_1.spawn)(process.execPath, [serverScript], {
+            cwd: projectCwd,
+            detached: true,
+            stdio: 'ignore',
+            env: {
+                ...process.env,
+                MAXSIM_PORT: String(port),
+                MAXSIM_PROJECT_CWD: projectCwd,
+            },
+            ...(process.platform === 'win32' ? { shell: true } : {}),
+        });
+        child.unref();
+        const lockData = {
+            pid: child.pid ?? 0,
+            port,
+            startedAt: Date.now(),
+            cwd: projectCwd,
+        };
+        writeLockFile(projectCwd, lockData);
+        return lockData;
+    }
+    else {
+        // Foreground mode — import and start directly
+        const { createBackendServer } = await import('./server.js');
+        const server = createBackendServer({
+            port,
+            host: '127.0.0.1',
+            projectCwd,
+            enableTerminal: true,
+            enableFileWatcher: true,
+            enableMcp: true,
+            logDir: node_path_1.default.join(projectCwd, '.planning', 'logs'),
+        });
+        await server.start();
+        const lockData = {
+            pid: process.pid,
+            port: server.getPort(),
+            startedAt: Date.now(),
+            cwd: projectCwd,
+        };
+        writeLockFile(projectCwd, lockData);
+        return lockData;
+    }
+}
+async function stopBackend(projectCwd) {
+    const lock = readLockFile(projectCwd);
+    if (!lock)
+        return false;
+    // Try graceful shutdown via HTTP
+    const result = await httpJson('POST', `http://127.0.0.1:${lock.port}/api/shutdown`);
+    if (result) {
+        removeLockFile(projectCwd);
+        return true;
+    }
+    // Fallback: kill by PID
+    try {
+        process.kill(lock.pid, 'SIGTERM');
+    }
+    catch {
+        // Process may already be dead
+    }
+    removeLockFile(projectCwd);
+    return true;
+}
+async function getBackendStatus(projectCwd) {
+    const lock = readLockFile(projectCwd);
+    if (!lock)
+        return null;
+    const data = await httpJson('GET', `http://127.0.0.1:${lock.port}/api/health`);
+    if (!data || data.status !== 'ok') {
+        // Stale lock file — clean up
+        removeLockFile(projectCwd);
+        return null;
+    }
+    return data;
+}
+async function isBackendRunning(projectCwd) {
+    const status = await getBackendStatus(projectCwd);
+    return status !== null && status.status === 'ok';
+}
+function findBackendPort(projectCwd) {
+    const lock = readLockFile(projectCwd);
+    return lock ? lock.port : null;
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/backend/lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/backend/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/backend/server.d.ts

@@ -0,0 +1,13 @@
+/**
+ * MAXSIM Backend Server — Unified persistent backend service
+ *
+ * Consolidates HTTP API, WebSocket, MCP endpoint, terminal management,
+ * and file watching into a single per-project process.
+ *
+ * CRITICAL: Never import output() or error() from core — they call process.exit().
+ * CRITICAL: Never write to stdout directly — stdout may be reserved for protocol use.
+ * All logging must go to stderr via console.error().
+ */
+import type { BackendConfig, BackendServer } from './types.js';
+export declare function createBackendServer(config: BackendConfig): BackendServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/backend/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/backend/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAkCH,OAAO,KAAK,EACV,aAAa,EAEb,aAAa,EAEd,MAAM,YAAY,CAAC;AAmYpB,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAqsBxE"}