stagent 0.9.6 → 0.11.0

package/src/lib/filters/__tests__/parse.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from "vitest";
+import { parseFilterInput, matchesClauses } from "../parse";
+
+describe("parseFilterInput", () => {
+  it("returns empty result for empty input", () => {
+    expect(parseFilterInput("")).toEqual({ clauses: [], rawQuery: "" });
+  });
+
+  it("returns input as rawQuery when no clauses present", () => {
+    const out = parseFilterInput("hello world");
+    expect(out.clauses).toEqual([]);
+    expect(out.rawQuery).toBe("hello world");
+  });
+
+  it("parses a single clause and strips it from rawQuery", () => {
+    const out = parseFilterInput("#status:blocked");
+    expect(out.clauses).toEqual([{ key: "status", value: "blocked" }]);
+    expect(out.rawQuery).toBe("");
+  });
+
+  it("parses multiple clauses with AND semantics", () => {
+    const out = parseFilterInput("#status:blocked #priority:high");
+    expect(out.clauses).toEqual([
+      { key: "status", value: "blocked" },
+      { key: "priority", value: "high" },
+    ]);
+    expect(out.rawQuery).toBe("");
+  });
+
+  it("preserves raw text between and around clauses", () => {
+    const out = parseFilterInput("auth #status:blocked service #priority:high");
+    expect(out.clauses).toEqual([
+      { key: "status", value: "blocked" },
+      { key: "priority", value: "high" },
+    ]);
+    expect(out.rawQuery).toBe("auth service");
+  });
+
+  it("treats `#123` as raw-query text, not a clause (no colon)", () => {
+    const out = parseFilterInput("see #123 for context");
+    expect(out.clauses).toEqual([]);
+    expect(out.rawQuery).toBe("see #123 for context");
+  });
+
+  it("treats `#1abc:val` as raw-query text (key must start with a letter)", () => {
+    const out = parseFilterInput("#1abc:val");
+    expect(out.clauses).toEqual([]);
+    expect(out.rawQuery).toBe("#1abc:val");
+  });
+
+  it("accepts hyphens and underscores in keys", () => {
+    const out = parseFilterInput("#created-by:me #user_id:42");
+    expect(out.clauses).toEqual([
+      { key: "created-by", value: "me" },
+      { key: "user_id", value: "42" },
+    ]);
+  });
+
+  it("preserves case of values verbatim (keys keep case too)", () => {
+    const out = parseFilterInput("#Status:Blocked");
+    expect(out.clauses).toEqual([{ key: "Status", value: "Blocked" }]);
+  });
+
+  it("accepts back-to-back clauses without space between them", () => {
+    const out = parseFilterInput("#a:1#b:2");
+    expect(out.clauses).toEqual([
+      { key: "a", value: "1" },
+      { key: "b", value: "2" },
+    ]);
+    expect(out.rawQuery).toBe("");
+  });
+
+  it("collapses extra whitespace in rawQuery", () => {
+    const out = parseFilterInput("  foo   bar  ");
+    expect(out.rawQuery).toBe("foo bar");
+  });
+
+  it("handles values with special chars except whitespace", () => {
+    const out = parseFilterInput("#path:src/lib/filters.ts");
+    expect(out.clauses).toEqual([{ key: "path", value: "src/lib/filters.ts" }]);
+  });
+});
+
+describe("matchesClauses", () => {
+  const task = { id: "t1", status: "blocked", priority: "high", type: "task" };
+
+  it("returns true when clauses list is empty", () => {
+    expect(matchesClauses(task, [], {})).toBe(true);
+  });
+
+  it("returns true when all clauses match via predicates", () => {
+    const out = matchesClauses(
+      task,
+      [{ key: "status", value: "blocked" }],
+      { status: (t, v) => t.status === v }
+    );
+    expect(out).toBe(true);
+  });
+
+  it("returns false when any clause fails", () => {
+    const out = matchesClauses(
+      task,
+      [
+        { key: "status", value: "blocked" },
+        { key: "priority", value: "low" },
+      ],
+      {
+        status: (t, v) => t.status === v,
+        priority: (t, v) => t.priority === v,
+      }
+    );
+    expect(out).toBe(false);
+  });
+
+  it("silently skips unknown keys (does not fail the match)", () => {
+    const out = matchesClauses(
+      task,
+      [
+        { key: "status", value: "blocked" },
+        { key: "totally-unknown", value: "xyz" },
+      ],
+      { status: (t, v) => t.status === v }
+    );
+    expect(out).toBe(true);
+  });
+
+  it("normalizes key lookup to lowercase", () => {
+    const out = matchesClauses(
+      task,
+      [{ key: "Status", value: "blocked" }],
+      { status: (t, v) => t.status === v }
+    );
+    expect(out).toBe(true);
+  });
+});

package/src/lib/filters/parse.ts

@@ -0,0 +1,86 @@
+/**
+ * `#key:value` filter namespace parser.
+ *
+ * Pure function that extracts filter clauses from free-text input and returns
+ * the non-filter remainder as `rawQuery`. Designed to be reused across chat
+ * popovers (entity filtering) and list pages (URL state, FilterBar input).
+ *
+ * Syntax (v2):
+ *   - `#key:value` — single clause. Keys are `[A-Za-z][\w-]*`, values are
+ *     double-quoted strings `"..."` (may contain spaces or `#`) OR a whitespace/`#`-terminated bare run.
+ *   - Multiple clauses may chain: `#status:blocked #priority:high` → two clauses.
+ *   - Clauses may appear anywhere in the input; everything else becomes rawQuery.
+ *   - Unknown keys pass through unchanged — the consumer decides what to do.
+ *   - Tokens like `#123` (no colon) are treated as raw-query text, not clauses.
+ *
+ * Design notes:
+ *   - AND-only. NOT/OR deferred to v2.
+ *   - Case of keys is preserved; consumer normalizes if needed. Values are
+ *     preserved verbatim (including case) — status codes are commonly lowercase.
+ *   - rawQuery whitespace is collapsed to single spaces and trimmed so callers
+ *     can feed it directly to a search input without extra cleanup.
+ */
+
+export interface FilterClause {
+  key: string;
+  value: string;
+}
+
+export interface ParsedFilterInput {
+  clauses: FilterClause[];
+  rawQuery: string;
+}
+
+// Clause pattern: `#<key>:<value>`. Key must start with a letter to avoid
+// eating `#123` hash references. Value may be either:
+//   - a double-quoted run of any non-quote chars: `"..."`  (captured in group 2)
+//   - OR an unquoted whitespace/`#`-terminated run   (captured in group 3)
+// Exactly one of group 2 / group 3 will be defined per match.
+const CLAUSE_PATTERN = /#([A-Za-z][\w-]*):(?:"([^"]*)"|([^\s#]+))/g;
+
+export function parseFilterInput(input: string): ParsedFilterInput {
+  if (!input) return { clauses: [], rawQuery: "" };
+
+  const clauses: FilterClause[] = [];
+  let rawQuery = input;
+
+  // Replace each match with a single space to preserve word boundaries, then
+  // collapse whitespace. This is simpler than maintaining offsets and survives
+  // back-to-back clauses like `#a:1#b:2` (which we don't officially support
+  // but shouldn't crash on — the regex with `g` flag matches both).
+  rawQuery = rawQuery.replace(
+    CLAUSE_PATTERN,
+    (_match, key: string, quoted: string | undefined, bare: string | undefined) => {
+      const value = quoted !== undefined ? quoted : bare ?? "";
+      clauses.push({ key, value });
+      return " ";
+    }
+  );
+
+  rawQuery = rawQuery.replace(/\s+/g, " ").trim();
+
+  return { clauses, rawQuery };
+}
+
+/**
+ * Evaluate an object against a list of clauses using a caller-supplied
+ * predicate per key. Returns true if ALL clauses match (AND semantics) or
+ * the clauses list is empty.
+ *
+ * `predicates` maps known filter keys to value-checkers. Unknown keys are
+ * silently skipped (not considered a mismatch) so callers can layer their
+ * own matching logic without breaking on typos.
+ */
+export function matchesClauses<T>(
+  item: T,
+  clauses: FilterClause[],
+  predicates: Record<string, (item: T, value: string) => boolean>
+): boolean {
+  if (clauses.length === 0) return true;
+  for (const clause of clauses) {
+    const predicate = predicates[clause.key.toLowerCase()];
+    if (!predicate) continue; // unknown key → skip, per spec
+    if (!predicate(item, clause.value)) return false;
+  }
+  return true;
+}

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.
+});