@ikunin/sprintpilot 2.2.13 → 2.2.15

package/_Sprintpilot/bin/autopilot.js

@@ -702,6 +702,10 @@ function composeRuntimeState(persisted, profile, projectRoot) {
     // not lifetime). Persisted across in-session resumes so a `pause` mid-flow
     // doesn't reset progress against the limit.
     session_stories_completed: persisted.session_stories_completed || 0,
+    // .autopilot.lock holder ID, persisted so subsequent cmdStart calls
+    // recognize their own lock and refresh in place. Cleared by
+    // sprint-autopilot-off (which calls `lock.js release`).
+    lock_session_id: persisted.lock_session_id || null,
     // halt_requested is intentionally NOT carried forward here: cmdStart
     // clears it on each new session (a `pause` cleanly halts THIS session
     // and the next /sprint-autopilot-on resumes normally).
@@ -731,6 +735,7 @@ function persistRuntimeState(runtime, profile, projectRoot) {
     land_pending: runtime.land_pending,
     pending_alternative: runtime.pending_alternative || null,
     session_stories_completed: runtime.session_stories_completed || 0,
+    lock_session_id: runtime.lock_session_id || null,
   };
   return persistState(updates, profile, projectRoot, runtime.story_key || 'sprint');
 }
@@ -1066,6 +1071,186 @@ function lockUserBranchIfNeeded(runtime, profile, projectRoot) {
   return null;
 }
 
+// .autopilot.lock: prevent concurrent autopilot sessions on the same
+// project. Lockfile contract documented in modules/git/config.yaml
+// ("Lock file (.autopilot.lock — prevents concurrent autopilot sessions)")
+// and implemented in scripts/lock.js. cmdStart wires it in here.
+//
+// Idempotency: a /sprint-autopilot-on mid-flow (e.g. after a halt) must
+// not refuse to resume just because the prior cmdStart left a lock. We
+// store the lock's session_id in autopilot-state.yaml on first acquire and
+// treat a matching id on subsequent cmdStart calls as "my lock; refresh".
+//
+// Return shape:
+//   { acquired: true,  id, refreshed?: true }  — proceed
+//   { acquired: false, holder, ageMin }        — halt; caller emits user_prompt
+//   { acquired: true,  id, takeover: 'stale' } — stale takeover; proceed
+function acquireAutopilotLock(persisted, profile, projectRoot) {
+  const { execFileSync: runFile } = require('node:child_process');
+  const lockScript = path.join(projectRoot, '_Sprintpilot', 'scripts', 'lock.js');
+  if (!fs.existsSync(lockScript)) {
+    return { acquired: true, id: null, skipped: true };
+  }
+  const lockFile = path.join(projectRoot, '.autopilot.lock');
+  const stale = typeof profile.lock_stale_timeout_minutes === 'number'
+    ? profile.lock_stale_timeout_minutes
+    : 30;
+  // stale_timeout_minutes <= 0 means "never auto-take-over". Pass a very
+  // large value to lock.js so it never deems anything STALE.
+  const staleArg = stale > 0 ? String(stale) : '999999';
+
+  const callLock = (action) => {
+    try {
+      const out = runFile(
+        'node',
+        [lockScript, action, '--file', lockFile, '--stale-minutes', staleArg],
+        { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] },
+      ).trim();
+      return { ok: true, out };
+    } catch (e) {
+      return { ok: false, out: (e.stdout && e.stdout.toString().trim()) || '', code: e.status };
+    }
+  };
+
+  const checkResult = callLock('check');
+  const checkOut = checkResult.out || 'FREE';
+
+  if (checkOut === 'FREE') {
+    const acq = callLock('acquire');
+    if (acq.ok && acq.out.startsWith('ACQUIRED:')) {
+      return { acquired: true, id: acq.out.slice('ACQUIRED:'.length) };
+    }
+    // Race: another acquirer just created the lock. Fall through to retry.
+  }
+
+  const match = /^(LOCKED|STALE):([^:]+):(\d+)m$/.exec(checkOut);
+  if (match) {
+    const state = match[1];
+    const holderId = match[2];
+    const ageMin = parseInt(match[3], 10);
+
+    // My own lock? Refresh (rewrite ts + same id) and proceed.
+    if (state === 'LOCKED' && persisted.lock_session_id && persisted.lock_session_id === holderId) {
+      try {
+        const ts = Math.floor(Date.now() / 1000);
+        fs.writeFileSync(lockFile, `${ts}\n${holderId}\n`, { encoding: 'utf8', mode: 0o644 });
+        return { acquired: true, id: holderId, refreshed: true };
+      } catch (e) {
+        return { acquired: false, holder: holderId, ageMin, error: `lock refresh failed: ${e.message}` };
+      }
+    }
+
+    if (state === 'STALE') {
+      const acq = callLock('acquire');
+      if (acq.ok && acq.out.startsWith('ACQUIRED_STALE:')) {
+        return { acquired: true, id: acq.out.slice('ACQUIRED_STALE:'.length), takeover: 'stale' };
+      }
+      if (acq.ok && acq.out.startsWith('ACQUIRED:')) {
+        return { acquired: true, id: acq.out.slice('ACQUIRED:'.length) };
+      }
+      const reMatch = /^LOCKED:([^:]+):(\d+)m$/.exec(acq.out);
+      if (reMatch) {
+        return { acquired: false, holder: reMatch[1], ageMin: parseInt(reMatch[2], 10) };
+      }
+      return { acquired: false, holder: holderId, ageMin };
+    }
+
+    return { acquired: false, holder: holderId, ageMin };
+  }
+
+  return { acquired: true, id: null, warning: `unrecognized lock state: ${checkOut}` };
+}
+
+// Worktree health check on boot. Documented in modules/git/config.yaml
+// as "check for orphaned worktrees from crashed sessions". The script
+// (scripts/health-check.js) categorizes worktrees as CLEAN_DONE /
+// COMMITTED / STALE / DIRTY / ORPHAN and writes a SUMMARY line.
+//
+// We treat ORPHAN as halt-worthy (a worktree directory exists but
+// `git rev-parse --git-dir` fails or no branch is checked out — almost
+// certainly leftover from a crashed session that needs cleanup). DIRTY
+// is logged but doesn't halt (user may be actively working in it).
+//
+// Returns one of:
+//   { ok: true, summary }                — no orphans; proceed
+//   { ok: false, prompt, orphans, summary } — halt; caller emits user_prompt
+//   { ok: true, skipped: true }          — script missing / no worktrees dir / disabled
+function runWorktreeHealthCheck(profile, projectRoot) {
+  if (!profile.worktree_health_check_on_boot) {
+    return { ok: true, skipped: true, reason: 'disabled' };
+  }
+  if (!profile.worktree_enabled) {
+    return { ok: true, skipped: true, reason: 'worktrees_disabled' };
+  }
+  const script = path.join(projectRoot, '_Sprintpilot', 'scripts', 'health-check.js');
+  if (!fs.existsSync(script)) {
+    return { ok: true, skipped: true, reason: 'script_missing' };
+  }
+  const worktreesDir = path.join(projectRoot, '.worktrees');
+  if (!fs.existsSync(worktreesDir)) {
+    return { ok: true, skipped: true, reason: 'no_worktrees_dir' };
+  }
+
+  const { execFileSync: runFile } = require('node:child_process');
+  let stdout = '';
+  try {
+    stdout = runFile(
+      'node',
+      [
+        script,
+        '--worktrees-dir',
+        worktreesDir,
+        '--base-branch',
+        profile.base_branch || 'main',
+      ],
+      {
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        cwd: projectRoot,
+        timeout: 60_000,
+      },
+    );
+  } catch (e) {
+    // Health check failure isn't fatal — log and proceed. A broken
+    // script shouldn't gate the autopilot.
+    return {
+      ok: true,
+      skipped: true,
+      reason: 'health_check_error',
+      error: e.message || String(e),
+    };
+  }
+
+  const lines = stdout.split(/\r?\n/).filter(Boolean);
+  const summaryLine = lines.find((l) => l.startsWith('SUMMARY:')) || '';
+  // SUMMARY:total:cleanDone:committed:stale:dirty:orphan
+  const parts = summaryLine.split(':');
+  const summary = {
+    total: parseInt(parts[1] || '0', 10),
+    clean_done: parseInt(parts[2] || '0', 10),
+    committed: parseInt(parts[3] || '0', 10),
+    stale: parseInt(parts[4] || '0', 10),
+    dirty: parseInt(parts[5] || '0', 10),
+    orphan: parseInt(parts[6] || '0', 10),
+  };
+  const orphans = lines
+    .filter((l) => l.startsWith('ORPHAN:'))
+    .map((l) => l.slice('ORPHAN:'.length));
+
+  if (summary.orphan > 0) {
+    return {
+      ok: false,
+      summary,
+      orphans,
+      prompt:
+        `Found ${summary.orphan} orphaned worktree(s) under .worktrees/ from a previous (possibly crashed) session: ${orphans.join(', ')}. ` +
+        `Run \`git worktree prune\` and remove the leftover directories before resuming, or run \`node _Sprintpilot/scripts/health-check.js --worktrees-dir .worktrees\` to see all categories.`,
+    };
+  }
+
+  return { ok: true, summary };
+}
+
 function cmdStart(opts) {
   const projectRoot = resolveProjectRoot(opts);
   const { typed: profile } = resolveProfile(projectRoot, opts.profile);
@@ -1118,6 +1303,83 @@ function cmdStart(opts) {
     }
   }
 
+  // .autopilot.lock — acquire before any state mutation. If another
+  // session holds the lock (and it isn't ours and isn't stale), bail out
+  // with a user_prompt action so the LLM/user knows to either wait or
+  // run `sprint-autopilot-off` in the other session.
+  const lockOutcome = acquireAutopilotLock(persisted, profile, projectRoot);
+  if (!lockOutcome.acquired) {
+    const haltAction = {
+      type: 'user_prompt',
+      reason: 'autopilot_lock_held',
+      prompt:
+        `Another autopilot session holds .autopilot.lock (session ${lockOutcome.holder}, age ${lockOutcome.ageMin}m). ` +
+        `Wait for it to finish, run \`/sprint-autopilot-off\` in the other session, or delete .autopilot.lock if you're sure the holder crashed.`,
+      holder: lockOutcome.holder,
+      age_minutes: lockOutcome.ageMin,
+    };
+    ledger.append(
+      { kind: 'action_emitted', phase: persisted.current_bmad_step || null, action: haltAction },
+      { projectRoot },
+    );
+    process.stdout.write(`${JSON.stringify({ action: haltAction, phase: persisted.current_bmad_step || null }, null, 2)}\n`);
+    return 0;
+  }
+  if (lockOutcome.id) {
+    persisted.lock_session_id = lockOutcome.id;
+    // Eagerly persist lock_session_id so a crash between here and the
+    // final persistRuntimeState below doesn't leave the lockfile owned
+    // by an ID that nothing knows about. Without this, a mid-cmdStart
+    // crash would brick the project until the lock goes stale.
+    persistState({ lock_session_id: lockOutcome.id }, profile, projectRoot, 'sprint');
+    if (profile.coalesce_state_writes) stateStore.flush(profile, { projectRoot, story: 'sprint' });
+    ledger.append(
+      {
+        kind: 'lock_acquired',
+        detail: {
+          session_id: lockOutcome.id,
+          takeover: lockOutcome.takeover || null,
+          refreshed: !!lockOutcome.refreshed,
+        },
+      },
+      { projectRoot },
+    );
+  }
+
+  // Worktree health check — once per session, after lock acquire so we
+  // don't compete with another active session for the same .worktrees
+  // directory.
+  const healthOutcome = runWorktreeHealthCheck(profile, projectRoot);
+  ledger.append(
+    {
+      kind: 'worktree_health_check',
+      detail: {
+        ok: healthOutcome.ok,
+        skipped: !!healthOutcome.skipped,
+        reason: healthOutcome.reason || null,
+        summary: healthOutcome.summary || null,
+      },
+    },
+    { projectRoot },
+  );
+  if (!healthOutcome.ok) {
+    const haltAction = {
+      type: 'user_prompt',
+      reason: 'worktree_orphans_detected',
+      prompt: healthOutcome.prompt,
+      orphans: healthOutcome.orphans,
+      summary: healthOutcome.summary,
+    };
+    ledger.append(
+      { kind: 'action_emitted', phase: persisted.current_bmad_step || null, action: haltAction },
+      { projectRoot },
+    );
+    process.stdout.write(
+      `${JSON.stringify({ action: haltAction, phase: persisted.current_bmad_step || null }, null, 2)}\n`,
+    );
+    return 0;
+  }
+
   // Persist the new queue BEFORE composing runtime state so the queue
   // head is visible to composeRuntimeState's resolver.
   if (explicitQueue.length > 0) {
@@ -1419,4 +1681,12 @@ if (require.main === module) {
   process.exit(main(process.argv.slice(2)));
 }
 
-module.exports = { main, SUBCOMMANDS, decorateGitOp, decorateRunScript, composeRuntimeState };
+module.exports = {
+  main,
+  SUBCOMMANDS,
+  decorateGitOp,
+  decorateRunScript,
+  composeRuntimeState,
+  acquireAutopilotLock,
+  runWorktreeHealthCheck,
+};

package/_Sprintpilot/lib/orchestrator/action-ledger.js

@@ -39,6 +39,11 @@ const VALID_KINDS = [
   // `--epic`. Logged once per start invocation so resume/audit can see
   // why a queue head differs from sprint-status's natural order.
   'story_queue_set',
+  // Worktree health check result, logged once per cmdStart when
+  // git.worktree.health_check_on_boot is true (the default). Detail
+  // includes `summary` (counts) or `reason` ('disabled' / 'no_worktrees_dir'
+  // / 'script_missing' / 'health_check_error' / 'worktrees_disabled').
+  'worktree_health_check',
 ];
 
 function isPlainObject(v) {

package/_Sprintpilot/lib/orchestrator/profile-rules.js

@@ -96,6 +96,15 @@ function flatToProfile(resolved, profileName) {
     conditional_boot_work: coerceBool(get(resolved, 'autopilot.conditional_boot_work'), false),
     granularity: coerceEnum(get(resolved, 'git.granularity'), VALID_GRANULARITIES, 'story'),
     worktree_enabled: coerceBool(get(resolved, 'git.worktree.enabled'), true),
+    // git.worktree.health_check_on_boot — when true, cmdStart runs
+    // scripts/health-check.js once per session and halts if it finds
+    // ORPHAN worktrees (left over from crashed sessions). Documented in
+    // modules/git/config.yaml ("check for orphaned worktrees from
+    // crashed sessions").
+    worktree_health_check_on_boot: coerceBool(
+      get(resolved, 'git.worktree.health_check_on_boot'),
+      true,
+    ),
     squash_on_merge: coerceBool(get(resolved, 'git.squash_on_merge'), false),
     reuse_user_branch: coerceBool(get(resolved, 'git.reuse_user_branch'), false),
     merge_strategy: coerceEnum(
@@ -148,6 +157,12 @@ function flatToProfile(resolved, profileName) {
     // (story keys + prefix) to this length with a 6-char hash suffix to
     // keep the name unique. Honors the contract advertised in config.yaml.
     max_branch_length: coerceInt(get(resolved, 'git.max_branch_length'), 60),
+    // git.lock.stale_timeout_minutes — .autopilot.lock is auto-taken-over
+    // by cmdStart when older than this. Documented in modules/git/config.yaml
+    // ("auto-remove locks older than this"). Forwarded to lock.js via
+    // --stale-minutes. 0 disables the auto-takeover entirely (locks are
+    // never considered stale; manual `autopilot off` required).
+    lock_stale_timeout_minutes: coerceInt(get(resolved, 'git.lock.stale_timeout_minutes'), 30),
     // git.platform.provider + base_url — forwarded to create-pr.js when
     // the orchestrator opens or polls PRs. 'auto' delegates platform
     // detection to create-pr.js (currently defaults to github).

package/_Sprintpilot/manifest.yaml

@@ -1,6 +1,6 @@
 addon:
   name: sprintpilot
-  version: 2.2.13
+  version: 2.2.15
   description: Sprintpilot — autopilot and multi-agent addon for BMad Method (git workflow, parallel agents, autonomous story execution)
   bmad_compatibility: ">=6.2.0"
   modules:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikunin/sprintpilot",
-  "version": "2.2.13",
+  "version": "2.2.15",
   "description": "Sprintpilot — autopilot and multi-agent addon for BMad Method v6: git workflow, parallel agents, autonomous story execution",
   "license": "Apache-2.0",
   "repository": {