stagent 0.9.5 → 0.10.0

package/src/lib/db/schema.ts

@@ -40,6 +40,21 @@ export const tasks = sqliteTable(
     workflowRunNumber: integer("workflow_run_number"),
     /** Resolved per-task budget cap in USD — set by workflow engine for child tasks */
     maxBudgetUsd: real("max_budget_usd"),
+    /** When the slot for this task was atomically claimed */
+    slotClaimedAt: integer("slot_claimed_at", { mode: "timestamp" }),
+    /** Wall-clock expiry; reaper aborts tasks whose lease has passed */
+    leaseExpiresAt: integer("lease_expires_at", { mode: "timestamp" }),
+    /**
+     * Explicit terminal-state reason written by the runtime adapter at
+     * failure/abort transitions (e.g. 'turn_limit_exceeded', 'lease_expired',
+     * 'aborted', 'sdk_error'). Distinct from `result` — `result` holds the
+     * agent's final output text, while `failureReason` holds a machine-readable
+     * classifier that drives scheduler failure-streak logic without re-parsing
+     * error prose.
+     */
+    failureReason: text("failure_reason"),
+    /** Per-task turn budget copied from schedules.maxTurns at firing time */
+    maxTurns: integer("max_turns"),
     createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
     updatedAt: integer("updated_at", { mode: "timestamp" }).notNull(),
   },
@@ -49,6 +64,7 @@ export const tasks = sqliteTable(
     index("idx_tasks_workflow_id").on(table.workflowId),
     index("idx_tasks_schedule_id").on(table.scheduleId),
     index("idx_tasks_agent_profile").on(table.agentProfile),
+    index("idx_tasks_running_scheduled").on(table.status, table.sourceType, table.leaseExpiresAt),
   ]
 );
 
@@ -65,6 +81,13 @@ export const workflows = sqliteTable("workflows", {
   runNumber: integer("run_number").default(0).notNull(),
   /** Runtime to use for all steps (nullable — falls back to system default) */
   runtimeId: text("runtime_id"),
+  /**
+   * Epoch millisecond timestamp at which a paused (delayed) workflow is due to resume.
+   * Null for workflows that are not waiting on a delay step. Indexed via
+   * idx_workflows_resume_at (partial index on non-null values) so the scheduler tick
+   * can efficiently find due workflows. See features/workflow-step-delays.md.
+   */
+  resumeAt: integer("resume_at"),
   createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
   updatedAt: integer("updated_at", { mode: "timestamp" }).notNull(),
 });
@@ -210,6 +233,20 @@ export const schedules = sqliteTable(
     failureStreak: integer("failure_streak").default(0).notNull(),
     /** Detected reason for the most recent failure (turn_limit_exceeded, timeout, etc.) */
     lastFailureReason: text("last_failure_reason"),
+    /** Hard cap on turns per firing; NULL inherits the global MAX_TURNS setting */
+    maxTurns: integer("max_turns"),
+    /** Timestamp when maxTurns was last edited — drives first-breach grace */
+    maxTurnsSetAt: integer("max_turns_set_at", { mode: "timestamp" }),
+    /** Wall-clock lease override in seconds; NULL inherits global default (1200s) */
+    maxRunDurationSec: integer("max_run_duration_sec"),
+    /**
+     * Counter separate from failureStreak — increments only on maxTurns breach.
+     * Reset to 0 on any non-breach outcome (successful run, generic failure, or
+     * first-breach grace window after maxTurnsSetAt). Auto-pause at 5. This
+     * higher threshold + grace window protects users from tripping auto-pause
+     * via a misconfigured maxTurns edit.
+     */
+    turnBudgetBreachStreak: integer("turn_budget_breach_streak").default(0).notNull(),
     createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
     updatedAt: integer("updated_at", { mode: "timestamp" }).notNull(),
   },
@@ -307,6 +344,7 @@ export const usageLedger = sqliteTable(
         "context_summarization",
         "chat_turn",
         "profile_assist",
+        "manual_force_bypass",
       ],
     }).notNull(),
     runtimeId: text("runtime_id").notNull(),
@@ -1162,29 +1200,6 @@ export const snapshots = sqliteTable(
 
 export type SnapshotRow = InferSelectModel<typeof snapshots>;
 
-// ── License ──────────────────────────────────────────────────────────
-
-export const license = sqliteTable("license", {
-  id: text("id").primaryKey(),
-  supabaseUserId: text("supabase_user_id"),
-  tier: text("tier", { enum: ["community", "solo", "operator", "scale"] })
-    .default("community")
-    .notNull(),
-  status: text("status", { enum: ["active", "inactive", "grace"] })
-    .default("inactive")
-    .notNull(),
-  email: text("email"),
-  activatedAt: integer("activated_at", { mode: "timestamp" }),
-  expiresAt: integer("expires_at", { mode: "timestamp" }),
-  lastValidatedAt: integer("last_validated_at", { mode: "timestamp" }),
-  gracePeriodExpiresAt: integer("grace_period_expires_at", { mode: "timestamp" }),
-  encryptedToken: text("encrypted_token"),
-  createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
-  updatedAt: integer("updated_at", { mode: "timestamp" }).notNull(),
-});
-
-export type LicenseRow = InferSelectModel<typeof license>;
-
 // ── Workflow Execution Stats ─────────────────────────────────────────
 
 export const workflowExecutionStats = sqliteTable("workflow_execution_stats", {
@@ -1212,3 +1227,33 @@ export const workflowExecutionStats = sqliteTable("workflow_execution_stats", {
 });
 
 export type WorkflowExecutionStatsRow = InferSelectModel<typeof workflowExecutionStats>;
+
+// ── Schedule Firing Metrics ───────────────────────────────────────────
+
+export const scheduleFiringMetrics = sqliteTable(
+  "schedule_firing_metrics",
+  {
+    id: text("id").primaryKey(),
+    scheduleId: text("schedule_id")
+      .references(() => schedules.id)
+      .notNull(),
+    taskId: text("task_id").references(() => tasks.id),
+    firedAt: integer("fired_at", { mode: "timestamp" }).notNull(),
+    slotClaimedAt: integer("slot_claimed_at", { mode: "timestamp" }),
+    completedAt: integer("completed_at", { mode: "timestamp" }),
+    slotWaitMs: integer("slot_wait_ms"),
+    durationMs: integer("duration_ms"),
+    turnCount: integer("turn_count"),
+    maxTurnsAtFiring: integer("max_turns_at_firing"),
+    eventLoopLagMs: real("event_loop_lag_ms"),
+    peakRssMb: integer("peak_rss_mb"),
+    chatStreamsActive: integer("chat_streams_active"),
+    concurrentSchedules: integer("concurrent_schedules"),
+    failureReason: text("failure_reason"),
+  },
+  (table) => [
+    index("idx_sfm_schedule_time").on(table.scheduleId, table.firedAt),
+  ]
+);
+
+export type ScheduleFiringMetricRow = InferSelectModel<typeof scheduleFiringMetrics>;

package/src/lib/environment/workspace-context.ts

@@ -3,6 +3,8 @@ import { homedir } from "os";
 import { execFileSync } from "child_process";
 import { statSync } from "fs";
 import { join } from "path";
+import { getStagentDataDir } from "@/lib/utils/stagent-paths";
+import { isDevMode, isPrivateInstance } from "@/lib/instance/detect";
 
 /** The directory the user launched stagent from (falls back to process.cwd()). */
 export function getLaunchCwd(): string {
@@ -15,6 +17,8 @@ export interface WorkspaceContext {
   parentPath: string;
   gitBranch: string | null;
   isWorktree: boolean;
+  dataDir: string;
+  dataDirMismatch: boolean;
 }
 
 export function getWorkspaceContext(): WorkspaceContext {
@@ -47,5 +51,13 @@ export function getWorkspaceContext(): WorkspaceContext {
     // no .git at all
   }
 
-  return { cwd, folderName, parentPath, gitBranch, isWorktree };
+  const rawDataDir = getStagentDataDir();
+  const dataDir = rawDataDir.startsWith(home)
+    ? "~" + rawDataDir.slice(home.length)
+    : rawDataDir;
+
+  // Red flag: non-main repo using the default shared DB instead of its own
+  const dataDirMismatch = !isDevMode(cwd) && !isPrivateInstance();
+
+  return { cwd, folderName, parentPath, gitBranch, isWorktree, dataDir, dataDirMismatch };
 }

package/src/lib/import/dedup.ts

@@ -1,10 +1,14 @@
 /**
  * Deduplication engine for profile import.
  * Three-tier matching: exact ID, name match, content similarity.
+ *
+ * Keyword / Jaccard / tag-overlap helpers are shared with the chat workflow
+ * dedup path — see `src/lib/util/similarity.ts`.
  */
 
 import type { ProfileConfig } from "@/lib/validators/profile";
 import type { AgentProfile } from "@/lib/agents/profiles/types";
+import { extractKeywords, jaccard, tagOverlap } from "@/lib/util/similarity";
 
 export interface DedupResult {
   candidate: ProfileConfig;
@@ -15,60 +19,6 @@ export interface DedupResult {
   similarity?: number;
 }
 
-/** Common stop words to exclude from keyword extraction. */
-const STOP_WORDS = new Set([
-  "the", "and", "for", "are", "but", "not", "you", "all", "can", "had",
-  "her", "was", "one", "our", "out", "has", "have", "that", "this", "with",
-  "from", "they", "been", "will", "each", "make", "like", "into", "them",
-  "some", "when", "what", "your", "should", "would", "could", "about",
-  "which", "their", "other", "than", "then", "more", "also", "been",
-  "only", "must", "does", "here", "just", "over", "such", "after",
-  "before", "between", "through", "where", "these", "those", "being",
-  "using", "ensure", "every", "following", "include",
-]);
-
-/** Extract meaningful keywords from text. */
-function extractKeywords(text: string, limit = 20): Set<string> {
-  const words = text
-    .toLowerCase()
-    .replace(/[^a-z0-9\s-]/g, " ")
-    .split(/\s+/)
-    .filter((w) => w.length > 3 && w.length < 30 && !STOP_WORDS.has(w));
-
-  // Count frequency
-  const freq = new Map<string, number>();
-  for (const word of words) {
-    freq.set(word, (freq.get(word) ?? 0) + 1);
-  }
-
-  // Sort by frequency, take top N
-  const sorted = Array.from(freq.entries())
-    .sort((a, b) => b[1] - a[1])
-    .slice(0, limit)
-    .map(([word]) => word);
-
-  return new Set(sorted);
-}
-
-/** Jaccard similarity between two sets. */
-function jaccard(a: Set<string>, b: Set<string>): number {
-  if (a.size === 0 && b.size === 0) return 0;
-  let intersection = 0;
-  for (const item of a) {
-    if (b.has(item)) intersection++;
-  }
-  const union = a.size + b.size - intersection;
-  return union === 0 ? 0 : intersection / union;
-}
-
-/** Tag overlap ratio (how many of candidate's tags match existing). */
-function tagOverlap(candidateTags: string[], existingTags: string[]): number {
-  if (candidateTags.length === 0) return 0;
-  const existingSet = new Set(existingTags.map((t) => t.toLowerCase()));
-  const matches = candidateTags.filter((t) => existingSet.has(t.toLowerCase()));
-  return matches.length / candidateTags.length;
-}
-
 /**
  * Check a batch of candidate profiles against all existing profiles for duplicates.
  */

package/src/lib/instance/__tests__/bootstrap.test.ts

@@ -0,0 +1,362 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { execFileSync } from "child_process";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+
+let tempDir: string;
+let dataDir: string;
+
+function runGit(args: string[], cwd: string) {
+  execFileSync("git", args, { cwd, stdio: "pipe" });
+}
+
+function initRepo(dir: string) {
+  runGit(["init", "-b", "main"], dir);
+  runGit(["config", "user.email", "test@example.com"], dir);
+  runGit(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "# test\n");
+  runGit(["add", "README.md"], dir);
+  runGit(["commit", "-m", "initial"], dir);
+}
+
+beforeEach(() => {
+  tempDir = mkdtempSync(join(tmpdir(), "stagent-bootstrap-repo-"));
+  dataDir = mkdtempSync(join(tmpdir(), "stagent-bootstrap-data-"));
+  initRepo(tempDir);
+  vi.resetModules();
+  vi.unstubAllEnvs();
+  vi.stubEnv("STAGENT_DATA_DIR", dataDir);
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  rmSync(tempDir, { recursive: true, force: true });
+  rmSync(dataDir, { recursive: true, force: true });
+});
+
+describe("ensureInstanceConfig (Phase A)", () => {
+  it("generates a new instanceId on first call", async () => {
+    const { ensureInstanceConfig } = await import("../bootstrap");
+    const result = await ensureInstanceConfig();
+    expect(result.status).toBe("ok");
+    const { getInstanceConfig } = await import("../settings");
+    const config = getInstanceConfig();
+    expect(config).not.toBeNull();
+    expect(config!.instanceId).toMatch(/^[a-f0-9-]{36}$/);
+    expect(config!.branchName).toBe("local");
+    // STAGENT_DATA_DIR is stubbed to a temp dir (non-default), so this clone
+    // correctly registers as a private instance in the test environment.
+    expect(config!.isPrivateInstance).toBe(true);
+    expect(config!.createdAt).toBeGreaterThan(0);
+  });
+
+  it("does not regenerate instanceId on subsequent calls", async () => {
+    const { ensureInstanceConfig } = await import("../bootstrap");
+    await ensureInstanceConfig();
+    const { getInstanceConfig } = await import("../settings");
+    const firstId = getInstanceConfig()!.instanceId;
+    await ensureInstanceConfig();
+    const secondId = getInstanceConfig()!.instanceId;
+    expect(secondId).toBe(firstId);
+  });
+});
+
+describe("ensureLocalBranch (Phase A)", () => {
+  it("creates local branch at current HEAD when it does not exist", async () => {
+    const { createGitOps } = await import("../git-ops");
+    const { ensureLocalBranch } = await import("../bootstrap");
+    const ops = createGitOps(tempDir);
+    const mainSha = execFileSync("git", ["rev-parse", "main"], { cwd: tempDir, encoding: "utf-8" }).trim();
+    const result = ensureLocalBranch(ops);
+    expect(result.status).toBe("ok");
+    expect(ops.branchExists("local")).toBe(true);
+    expect(ops.getCurrentBranch()).toBe("local");
+    const localSha = execFileSync("git", ["rev-parse", "local"], { cwd: tempDir, encoding: "utf-8" }).trim();
+    expect(localSha).toBe(mainSha);
+    const mainShaAfter = execFileSync("git", ["rev-parse", "main"], { cwd: tempDir, encoding: "utf-8" }).trim();
+    expect(mainShaAfter).toBe(mainSha);
+  });
+
+  it("is a no-op when local branch already exists", async () => {
+    const { createGitOps } = await import("../git-ops");
+    const { ensureLocalBranch } = await import("../bootstrap");
+    const ops = createGitOps(tempDir);
+    ops.createAndCheckoutBranch("local");
+    const shaBefore = execFileSync("git", ["rev-parse", "local"], { cwd: tempDir, encoding: "utf-8" }).trim();
+    const result = ensureLocalBranch(ops);
+    expect(result.status).toBe("skipped");
+    expect(result.reason).toBe("branch_exists");
+    const shaAfter = execFileSync("git", ["rev-parse", "local"], { cwd: tempDir, encoding: "utf-8" }).trim();
+    expect(shaAfter).toBe(shaBefore);
+  });
+
+  it("creates local at current HEAD even when user has local commits on main", async () => {
+    writeFileSync(join(tempDir, "custom.txt"), "user work\n");
+    runGit(["add", "custom.txt"], tempDir);
+    runGit(["commit", "-m", "user customization"], tempDir);
+    const mainSha = execFileSync("git", ["rev-parse", "main"], { cwd: tempDir, encoding: "utf-8" }).trim();
+
+    const { createGitOps } = await import("../git-ops");
+    const { ensureLocalBranch } = await import("../bootstrap");
+    const ops = createGitOps(tempDir);
+    const result = ensureLocalBranch(ops);
+
+    expect(result.status).toBe("ok");
+    expect(ops.branchExists("local")).toBe(true);
+    const localSha = execFileSync("git", ["rev-parse", "local"], { cwd: tempDir, encoding: "utf-8" }).trim();
+    expect(localSha).toBe(mainSha);
+    const mainShaAfter = execFileSync("git", ["rev-parse", "main"], { cwd: tempDir, encoding: "utf-8" }).trim();
+    expect(mainShaAfter).toBe(mainSha);
+  });
+});
+
+describe("ensurePrePushHook (Phase B)", () => {
+  it("writes a pre-push hook with the STAGENT_HOOK_VERSION marker", async () => {
+    const { createGitOps } = await import("../git-ops");
+    const { ensurePrePushHook } = await import("../bootstrap");
+    const ops = createGitOps(tempDir);
+    const result = ensurePrePushHook(ops);
+    expect(result.status).toBe("ok");
+    const hookPath = join(tempDir, ".git", "hooks", "pre-push");
+    expect(existsSync(hookPath)).toBe(true);
+    const content = readFileSync(hookPath, "utf-8");
+    expect(content).toContain("STAGENT_HOOK_VERSION=");
+    expect(content).toContain("ALLOW_PRIVATE_PUSH");
+    const mode = statSync(hookPath).mode & 0o777;
+    expect(mode & 0o100).toBeTruthy();
+  });
+
+  it("is a no-op when a hook with matching version already exists", async () => {
+    const { createGitOps } = await import("../git-ops");
+    const { ensurePrePushHook } = await import("../bootstrap");
+    const ops = createGitOps(tempDir);
+    ensurePrePushHook(ops); // first install
+    const firstMtime = statSync(join(tempDir, ".git", "hooks", "pre-push")).mtimeMs;
+    const result = ensurePrePushHook(ops);
+    expect(result.status).toBe("skipped");
+    expect(result.reason).toBe("already_installed");
+    const secondMtime = statSync(join(tempDir, ".git", "hooks", "pre-push")).mtimeMs;
+    expect(secondMtime).toBe(firstMtime);
+  });
+
+  it("backs up a pre-existing non-stagent hook before installing", async () => {
+    const customHook = "#!/bin/sh\necho custom hook\n";
+    writeFileSync(join(tempDir, ".git", "hooks", "pre-push"), customHook);
+    chmodSync(join(tempDir, ".git", "hooks", "pre-push"), 0o755);
+    const { createGitOps } = await import("../git-ops");
+    const { ensurePrePushHook } = await import("../bootstrap");
+    const ops = createGitOps(tempDir);
+    const result = ensurePrePushHook(ops);
+    expect(result.status).toBe("ok");
+    const backupPath = join(tempDir, ".git", "hooks", "pre-push.stagent-backup");
+    expect(existsSync(backupPath)).toBe(true);
+    expect(readFileSync(backupPath, "utf-8")).toBe(customHook);
+    expect(readFileSync(join(tempDir, ".git", "hooks", "pre-push"), "utf-8"))
+      .toContain("STAGENT_HOOK_VERSION=");
+  });
+});
+
+describe("ensureBranchPushConfig (Phase B)", () => {
+  it("sets branch.local.pushRemote=no_push", async () => {
+    const { createGitOps } = await import("../git-ops");
+    const { ensureLocalBranch, ensureBranchPushConfig } = await import("../bootstrap");
+    const ops = createGitOps(tempDir);
+    ensureLocalBranch(ops);
+    const result = ensureBranchPushConfig(ops, ["local"]);
+    expect(result.status).toBe("ok");
+    const value = execFileSync("git", ["config", "--get", "branch.local.pushRemote"], { cwd: tempDir, encoding: "utf-8" }).trim();
+    expect(value).toBe("no_push");
+  });
+
+  it("handles multiple blocked branches", async () => {
+    const { createGitOps } = await import("../git-ops");
+    const { ensureBranchPushConfig } = await import("../bootstrap");
+    const ops = createGitOps(tempDir);
+    ops.createAndCheckoutBranch("wealth-mgr");
+    ops.createAndCheckoutBranch("investor-mgr");
+    const result = ensureBranchPushConfig(ops, ["wealth-mgr", "investor-mgr"]);
+    expect(result.status).toBe("ok");
+    expect(execFileSync("git", ["config", "--get", "branch.wealth-mgr.pushRemote"], { cwd: tempDir, encoding: "utf-8" }).trim()).toBe("no_push");
+    expect(execFileSync("git", ["config", "--get", "branch.investor-mgr.pushRemote"], { cwd: tempDir, encoding: "utf-8" }).trim()).toBe("no_push");
+  });
+});
+
+describe("resolveConsentDecision", () => {
+  it("returns {shouldRunPhaseB: false, reason: 'not_yet'} when consent is not_yet (default)", async () => {
+    const { resolveConsentDecision } = await import("../bootstrap");
+    const decision = await resolveConsentDecision();
+    expect(decision.shouldRunPhaseB).toBe(false);
+    expect(decision.reason).toBe("not_yet");
+  });
+
+  it("returns {shouldRunPhaseB: true} when consent is enabled", async () => {
+    const { setGuardrails } = await import("../settings");
+    await setGuardrails({
+      prePushHookInstalled: false,
+      prePushHookVersion: "",
+      pushRemoteBlocked: [],
+      consentStatus: "enabled",
+      firstBootCompletedAt: null,
+    });
+    const { resolveConsentDecision } = await import("../bootstrap");
+    const decision = await resolveConsentDecision();
+    expect(decision.shouldRunPhaseB).toBe(true);
+    expect(decision.reason).toBe("enabled");
+  });
+
+  it("returns {shouldRunPhaseB: false, reason: 'declined_permanently'}", async () => {
+    const { setGuardrails } = await import("../settings");
+    await setGuardrails({
+      prePushHookInstalled: false,
+      prePushHookVersion: "",
+      pushRemoteBlocked: [],
+      consentStatus: "declined_permanently",
+      firstBootCompletedAt: null,
+    });
+    const { resolveConsentDecision } = await import("../bootstrap");
+    const decision = await resolveConsentDecision();
+    expect(decision.shouldRunPhaseB).toBe(false);
+    expect(decision.reason).toBe("declined_permanently");
+  });
+
+  it("stamps firstBootCompletedAt on first call when it was null", async () => {
+    const { getGuardrails } = await import("../settings");
+    expect(getGuardrails().consentStatus).toBe("not_yet");
+    expect(getGuardrails().firstBootCompletedAt).toBeNull();
+    const { resolveConsentDecision } = await import("../bootstrap");
+    await resolveConsentDecision();
+    const after = getGuardrails();
+    expect(after.consentStatus).toBe("not_yet");
+    expect(after.firstBootCompletedAt).not.toBeNull();
+  });
+});
+
+describe("ensureInstance orchestrator", () => {
+  it("returns skipped with dev_mode_env when STAGENT_DEV_MODE=true", async () => {
+    vi.stubEnv("STAGENT_DEV_MODE", "true");
+    const { ensureInstance } = await import("../bootstrap");
+    const result = await ensureInstance(tempDir);
+    expect(result.skipped).toBe("dev_mode_env");
+    expect(result.steps).toEqual([]);
+    expect(existsSync(join(tempDir, ".git", "hooks", "pre-push"))).toBe(false);
+    const { createGitOps } = await import("../git-ops");
+    expect(createGitOps(tempDir).branchExists("local")).toBe(false);
+  });
+
+  it("returns skipped with dev_mode_sentinel when sentinel file exists", async () => {
+    writeFileSync(join(tempDir, ".git", "stagent-dev-mode"), "");
+    const { ensureInstance } = await import("../bootstrap");
+    const result = await ensureInstance(tempDir);
+    expect(result.skipped).toBe("dev_mode_sentinel");
+    expect(result.steps).toEqual([]);
+  });
+
+  it("returns skipped with no_git when .git directory is absent", async () => {
+    const noGitDir = mkdtempSync(join(tmpdir(), "stagent-nogit-"));
+    try {
+      const { ensureInstance } = await import("../bootstrap");
+      const result = await ensureInstance(noGitDir);
+      expect(result.skipped).toBe("no_git");
+    } finally {
+      rmSync(noGitDir, { recursive: true, force: true });
+    }
+  });
+
+  it("runs Phase A and stamps consent state on fresh clone (consent not_yet)", async () => {
+    const { ensureInstance } = await import("../bootstrap");
+    const result = await ensureInstance(tempDir);
+    expect(result.skipped).toBeUndefined();
+    const steps = result.steps.map((s) => s.step);
+    expect(steps).toContain("instance-config");
+    expect(steps).toContain("local-branch");
+    expect(steps).not.toContain("pre-push-hook");
+    expect(steps).not.toContain("branch-push-config");
+    const { createGitOps } = await import("../git-ops");
+    expect(createGitOps(tempDir).branchExists("local")).toBe(true);
+    expect(existsSync(join(tempDir, ".git", "hooks", "pre-push"))).toBe(false);
+    const { getGuardrails } = await import("../settings");
+    expect(getGuardrails().firstBootCompletedAt).not.toBeNull();
+    expect(getGuardrails().consentStatus).toBe("not_yet");
+  });
+
+  it("runs Phase B when consent is enabled", async () => {
+    const { setGuardrails } = await import("../settings");
+    await setGuardrails({
+      prePushHookInstalled: false,
+      prePushHookVersion: "",
+      pushRemoteBlocked: [],
+      consentStatus: "enabled",
+      firstBootCompletedAt: null,
+    });
+    const { ensureInstance } = await import("../bootstrap");
+    const result = await ensureInstance(tempDir);
+    const steps = result.steps.map((s) => s.step);
+    expect(steps).toContain("pre-push-hook");
+    expect(steps).toContain("branch-push-config");
+    expect(existsSync(join(tempDir, ".git", "hooks", "pre-push"))).toBe(true);
+  });
+
+  it("STAGENT_INSTANCE_MODE=true override beats STAGENT_DEV_MODE=true", async () => {
+    vi.stubEnv("STAGENT_DEV_MODE", "true");
+    vi.stubEnv("STAGENT_INSTANCE_MODE", "true");
+    const { ensureInstance } = await import("../bootstrap");
+    const result = await ensureInstance(tempDir);
+    expect(result.skipped).toBeUndefined();
+    expect(result.steps.length).toBeGreaterThan(0);
+  });
+
+  it("is a full no-op on the second call (idempotent)", async () => {
+    const { ensureInstance } = await import("../bootstrap");
+    await ensureInstance(tempDir);
+    const result = await ensureInstance(tempDir);
+    for (const step of result.steps) {
+      if (step.step === "instance-config" || step.step === "local-branch") {
+        expect(step.status).toBe("skipped");
+      }
+    }
+  });
+
+  it("skips ensureLocalBranch with warning when rebase is in progress", async () => {
+    mkdirSync(join(tempDir, ".git", "rebase-merge"));
+    const { ensureInstance } = await import("../bootstrap");
+    const result = await ensureInstance(tempDir);
+    const branchStep = result.steps.find((s) => s.step === "local-branch");
+    expect(branchStep?.status).toBe("skipped");
+    expect(branchStep?.reason).toBe("rebase_in_progress");
+  });
+
+  it("populates guardrails state after a Phase B run with consent=enabled", async () => {
+    // Regression test for the critical bug where ensureBranchPushConfig() set
+    // the git config values but never wrote the blocked branch list back to
+    // settings.instance.guardrails. The hook's grep would never match and all
+    // pushes would be silently allowed.
+    const { setGuardrails, getGuardrails } = await import("../settings");
+    await setGuardrails({
+      prePushHookInstalled: false,
+      prePushHookVersion: "",
+      pushRemoteBlocked: [],
+      consentStatus: "enabled",
+      firstBootCompletedAt: null,
+    });
+    const { ensureInstance, STAGENT_HOOK_VERSION } = await import("../bootstrap");
+    const result = await ensureInstance(tempDir);
+    expect(result.skipped).toBeUndefined();
+    const guardrails = getGuardrails();
+    expect(guardrails.prePushHookInstalled).toBe(true);
+    expect(guardrails.prePushHookVersion).toBe(STAGENT_HOOK_VERSION);
+    expect(guardrails.pushRemoteBlocked).toContain("local");
+  });
+
+  // NOTE: We do not test "single-clone user (STAGENT_DATA_DIR equals default)" at the
+  // orchestrator level here because vi.spyOn(os, "homedir") is not possible in ESM —
+  // Node's os module exports are non-configurable and cannot be redefined (vitest throws
+  // "Cannot redefine property: homedir"). Stubbing STAGENT_DATA_DIR to the real ~/.stagent
+  // would pollute the developer's live database, which is also unacceptable.
+  //
+  // The single-clone path is fully covered at the unit level by
+  // src/lib/instance/__tests__/detect.test.ts → "isPrivateInstance" describe block,
+  // specifically the test "returns false when STAGENT_DATA_DIR equals default ~/.stagent".
+  // That test directly exercises the detect.isPrivateInstance() function that
+  // ensureInstanceConfig() delegates to, making an orchestrator-level duplicate redundant.
+});