sequant 2.9.0 → 2.10.0

package/dist/src/commands/run-display.js

@@ -61,9 +61,9 @@ export function displayConfig(r) {
     if (r.mergedOptions.chain) {
         console.log(chalk.gray(`  Chain mode: enabled (each issue branches from previous)`));
     }
-    if (r.mergedOptions.qaGate) {
-        console.log(chalk.gray(`  QA gate: enabled (chain waits for QA pass)`));
-    }
+    // #795 deliberately prints nothing for `--qa-gate`: the old
+    // `QA gate: enabled (chain waits for QA pass)` line advertised gating the
+    // flag never performed. `runCommand` prints a deprecation notice instead.
 }
 /**
  * Convert workflow `IssueResult` to renderer `IssueSummary`.
@@ -92,9 +92,12 @@ function toIssueSummary(r) {
         prUrl: r.prUrl,
     };
     if (!r.success) {
+        // #879: a PR-creation failure has no failed phase — fall back to its error
+        // so the summary cell reads the real reason, not the useless "phase failed".
         summary.failureReason =
             failedPhase?.error ??
                 r.abortReason ??
+                r.prCreationError ??
                 `${failedPhase?.phase ?? "phase"} failed`;
         if (failedPhase?.verdict) {
             summary.qaVerdict = String(failedPhase.verdict);
@@ -159,7 +162,12 @@ export function displaySummary(result, renderer) {
     if (results.length === 0)
         return;
     const issueSummaries = results.map(toIssueSummary);
-    const totalSeconds = results.reduce((sum, r) => sum + (r.durationSeconds ?? 0), 0);
+    // #867: run wall clock, computed once by the orchestrator (RunResult), NOT
+    // `results.reduce(sum + durationSeconds)`. Under --parallel that sum
+    // double-counts overlapping issues and over-reports by ~the concurrency
+    // factor (a 36m 18s run printed 1h 12m at concurrency 3). The orchestrator is
+    // the only component that brackets the whole run, so it owns this value.
+    const totalSeconds = result.wallClockDurationSeconds;
     if (renderer) {
         renderer.renderSummary({
             issues: issueSummaries,
@@ -176,6 +184,31 @@ export function displaySummary(result, renderer) {
             dryRun: config.dryRun,
         });
     }
+    // #817: when `--ready-gate` ran, surface each issue's gate outcome (threshold
+    // reached vs guard halt) in the summary the same way `sequant ready` reports
+    // it — the "never merged" contract and stop reason are the human's cue to
+    // review and merge manually. Only issues that actually ran the gate carry it.
+    //
+    // A gate that *failed* is listed here too. It is non-fatal (the PR still
+    // opens), but omitting it would make a run whose gate crashed look exactly
+    // like one that gated cleanly — the user opted into a second look and needs
+    // to know it never happened.
+    const gated = results.filter((r) => r.readyGate || r.readyGateError);
+    if (gated.length > 0) {
+        console.log(colors.muted("  Ready gate (#817) — never merged:"));
+        for (const r of gated) {
+            if (!r.readyGate) {
+                console.log(`     #${r.issueNumber}: ${colors.warning("✗ gate did not run")} · ${r.readyGateError} · PR opened ungated — re-run \`sequant ready ${r.issueNumber}\``);
+                continue;
+            }
+            const g = r.readyGate;
+            const label = g.ready
+                ? colors.success(`✓ ${g.reason}`)
+                : colors.warning(`⚠️  ${g.reason}`);
+            console.log(`     #${r.issueNumber}: ${label} · policy \`${g.policy}\` · ${g.iterations} QA pass(es) · status \`${g.issueStatus}\``);
+        }
+        console.log("");
+    }
     // #760: a chain link whose checkpoint commit failed keeps its own work but
     // loses the recovery point resume depends on, and the per-issue warning has
     // long scrolled past by now on a multi-hour chain. Restate it at the summary,

package/dist/src/commands/run-flags.d.ts

@@ -1,9 +1,10 @@
 /**
  * Run flag normalization (#705) — keeps run.ts thin (#503 AC-2: <200 LOC).
  *
- * Two pure resolvers for the `run` command's flag surface:
+ * Pure resolvers for the `run` command's flag surface:
  *   - `normalizeQualityLoop`: ORs the hidden `-q` alias into `--quality-loop`.
  *   - `resolveTuiEnabled`: decides whether the boxed Ink TUI mounts.
+ *   - `deprecatedFlagNotices`: messages for flags kept only for compatibility.
  *
  * Extracted as pure functions so the flag behavior is unit-testable without
  * driving the full `runCommand` side effects.
@@ -29,3 +30,43 @@ export declare function normalizeQualityLoop(options: RunOptions): boolean;
  *   it, so it is intentionally not consulted here.
  */
 export declare function resolveTuiEnabled(options: RunOptions, isTTY: boolean): boolean;
+/**
+ * #795: notices for flags that still parse but no longer do anything.
+ *
+ * `--qa-gate` promised to "wait for QA pass before starting the next issue in
+ * chain", but the chain loop halts on any failed link unconditionally, so the
+ * flag never changed behavior and no runtime path ever wrote the
+ * `waiting_for_qa_gate` status it advertised. It is kept parseable so existing
+ * scripts do not hard-error — the previous `--qa-gate requires --chain` check
+ * aborted the whole run, which is exactly the breakage a deprecation window
+ * exists to avoid — and it no longer requires `--chain`.
+ *
+ * Returned rather than printed so the wording is unit-testable without driving
+ * `runCommand`'s side effects.
+ */
+export declare function deprecatedFlagNotices(options: RunOptions): string[];
+/**
+ * Prints every notice from {@link deprecatedFlagNotices}.
+ *
+ * Lives here rather than inline in `run.ts` to keep that adapter under the
+ * #503 AC-2 200-LOC budget, alongside the pure resolver it wraps.
+ *
+ * Two deliberate choices, both flagged because a future reader may mistake
+ * them for oversights:
+ *
+ * 1. **stderr, not stdout.** Deprecation notices are warnings, and warnings
+ *    go on stderr (same as `abort.ts`). This keeps a script's piped stdout
+ *    clean while still surfacing the notice on a terminal.
+ * 2. **Not gated on `options.quiet`.** `--quiet` suppresses progress and
+ *    version chatter; it is not a warning switch. The scripts most likely to
+ *    still pass `--qa-gate` are CI scripts, which are also the most likely to
+ *    pass `--quiet` — suppressing there would defeat the deprecation window
+ *    for exactly its target audience. Silencing warnings should be an
+ *    explicit opt-out, not a side effect of asking for less progress output.
+ *
+ * `runCommand` calls this immediately after the header box, ahead of the
+ * manifest and settings checks: a dead flag is a fact about argv, not about
+ * project state, so it should be reported even from an uninitialized
+ * directory where those checks would return early.
+ */
+export declare function warnDeprecatedFlags(options: RunOptions): void;

package/dist/src/commands/run-flags.js

@@ -1,13 +1,15 @@
 /**
  * Run flag normalization (#705) — keeps run.ts thin (#503 AC-2: <200 LOC).
  *
- * Two pure resolvers for the `run` command's flag surface:
+ * Pure resolvers for the `run` command's flag surface:
  *   - `normalizeQualityLoop`: ORs the hidden `-q` alias into `--quality-loop`.
  *   - `resolveTuiEnabled`: decides whether the boxed Ink TUI mounts.
+ *   - `deprecatedFlagNotices`: messages for flags kept only for compatibility.
  *
  * Extracted as pure functions so the flag behavior is unit-testable without
  * driving the full `runCommand` side effects.
  */
+import chalk from "chalk";
 /**
  * #705: `-q` is a hidden alias for the quality loop (it no longer maps to
  * `--quiet`, which moved to `-s`). Returns the effective quality-loop flag so
@@ -32,3 +34,53 @@ export function normalizeQualityLoop(options) {
 export function resolveTuiEnabled(options, isTTY) {
     return options.tui !== false && isTTY && !options.quiet;
 }
+/**
+ * #795: notices for flags that still parse but no longer do anything.
+ *
+ * `--qa-gate` promised to "wait for QA pass before starting the next issue in
+ * chain", but the chain loop halts on any failed link unconditionally, so the
+ * flag never changed behavior and no runtime path ever wrote the
+ * `waiting_for_qa_gate` status it advertised. It is kept parseable so existing
+ * scripts do not hard-error — the previous `--qa-gate requires --chain` check
+ * aborted the whole run, which is exactly the breakage a deprecation window
+ * exists to avoid — and it no longer requires `--chain`.
+ *
+ * Returned rather than printed so the wording is unit-testable without driving
+ * `runCommand`'s side effects.
+ */
+export function deprecatedFlagNotices(options) {
+    const notices = [];
+    if (options.qaGate) {
+        notices.push("--qa-gate is deprecated and has no effect (#795). --chain already halts the chain on any failed issue, QA included. Remove the flag; it will be deleted in a future major release.");
+    }
+    return notices;
+}
+/**
+ * Prints every notice from {@link deprecatedFlagNotices}.
+ *
+ * Lives here rather than inline in `run.ts` to keep that adapter under the
+ * #503 AC-2 200-LOC budget, alongside the pure resolver it wraps.
+ *
+ * Two deliberate choices, both flagged because a future reader may mistake
+ * them for oversights:
+ *
+ * 1. **stderr, not stdout.** Deprecation notices are warnings, and warnings
+ *    go on stderr (same as `abort.ts`). This keeps a script's piped stdout
+ *    clean while still surfacing the notice on a terminal.
+ * 2. **Not gated on `options.quiet`.** `--quiet` suppresses progress and
+ *    version chatter; it is not a warning switch. The scripts most likely to
+ *    still pass `--qa-gate` are CI scripts, which are also the most likely to
+ *    pass `--quiet` — suppressing there would defeat the deprecation window
+ *    for exactly its target audience. Silencing warnings should be an
+ *    explicit opt-out, not a side effect of asking for less progress output.
+ *
+ * `runCommand` calls this immediately after the header box, ahead of the
+ * manifest and settings checks: a dead flag is a fact about argv, not about
+ * project state, so it should be reported even from an uninitialized
+ * directory where those checks would return early.
+ */
+export function warnDeprecatedFlags(options) {
+    for (const notice of deprecatedFlagNotices(options)) {
+        console.error(chalk.yellow(`  !  ${notice}`));
+    }
+}

package/dist/src/commands/run-progress.js

@@ -58,6 +58,18 @@ export function buildProgressWiring(args) {
             // #543: activity events only feed the TUI's nowLine — skip the line renderer.
             if (event === "activity")
                 return;
+            // #804 AC-7: unlike activity, a waiting event MUST reach the renderer —
+            // it is the only signal during a pause that can last hours.
+            if (event === "waiting") {
+                renderer.onEvent({
+                    issue,
+                    phase,
+                    event,
+                    text: extra?.text,
+                    wakeAtMs: extra?.wakeAtMs,
+                });
+                return;
+            }
             // #624 Item 3: pass the outer-loop iteration through so the renderer can
             // render `(attempt N/M)` / `loop N/M`.
             renderer.onEvent({
@@ -71,9 +83,22 @@ export function buildProgressWiring(args) {
         };
     }
     else if (heartbeat) {
-        onProgress = (issue, phase, event) => {
+        onProgress = (issue, phase, event, extra) => {
             if (event === "activity")
                 return;
+            // #804 AC-7: mark/clear the auto-wait so the heartbeat reports the wait
+            // and, critically, does not report it as a stall. Must be handled before
+            // the `else` below, which would otherwise `stop()` the phase entirely and
+            // leave a multi-hour wait with no liveness signal at all.
+            if (event === "waiting") {
+                if (extra?.wakeAtMs !== undefined) {
+                    heartbeat.pauseForWait({ issueNumber: issue, phase }, extra.wakeAtMs);
+                }
+                else {
+                    heartbeat.resumeFromWait({ issueNumber: issue, phase });
+                }
+                return;
+            }
             if (event === "start")
                 heartbeat.start({
                     issueNumber: issue,

package/dist/src/commands/run.js

@@ -8,15 +8,21 @@ import { parseBatches } from "../lib/workflow/batch-executor.js";
 import { RunOrchestrator } from "../lib/workflow/run-orchestrator.js";
 import { displayConfig, displaySummary } from "./run-display.js";
 import { buildProgressWiring } from "./run-progress.js";
-import { normalizeQualityLoop, resolveTuiEnabled } from "./run-flags.js";
+import { normalizeQualityLoop, resolveTuiEnabled, warnDeprecatedFlags, } from "./run-flags.js";
 // Re-export public API for backwards compatibility
 export * from "./run-compat.js";
+// #848: red pre-flight rejection + non-zero exit (process.exitCode, not exit()).
+function rejectPreflight(message) {
+    console.log(chalk.red(message));
+    process.exitCode = 1;
+}
 /** Parse CLI args → validate → delegate to RunOrchestrator.run() → display summary. */
 export async function runCommand(issues, options) {
     // #705: fold the hidden `-q` alias into qualityLoop before any consumer reads
     // it (`-q` no longer maps to --quiet, which moved to `-s`). See run-flags.ts.
     options.qualityLoop = normalizeQualityLoop(options);
     console.log(ui.headerBox("SEQUANT WORKFLOW"));
+    warnDeprecatedFlags(options);
     if (!options.quiet) {
         try {
             const v = await checkVersionCached();
@@ -31,31 +37,26 @@ export async function runCommand(issues, options) {
     }
     const manifest = await getManifest();
     if (!manifest) {
-        console.log(chalk.red("❌ Sequant is not initialized. Run `sequant init` first."));
+        rejectPreflight("❌ Sequant is not initialized. Run `sequant init` first.");
         return;
     }
     const settings = await getSettings();
     // #605: --stacked implies --chain; reject explicit --no-chain combo before
     // we evaluate any --chain-dependent constraint below.
     if (options.stacked && options.chain === false) {
-        console.log(chalk.red("❌ --stacked cannot be combined with --no-chain"));
+        rejectPreflight("❌ --stacked cannot be combined with --no-chain");
         return;
     }
     if (options.stacked) {
         options.chain = true;
     }
-    // Validate constraints
     if (options.chain && options.batch?.length) {
-        console.log(chalk.red("❌ --chain cannot be used with --batch"));
+        rejectPreflight("❌ --chain cannot be used with --batch");
         return;
     }
     if (options.concurrency !== undefined &&
         (options.concurrency < 1 || !Number.isInteger(options.concurrency))) {
-        console.log(chalk.red(`❌ Invalid --concurrency value: ${options.concurrency}. Must be a positive integer.`));
-        return;
-    }
-    if (options.qaGate && !options.chain) {
-        console.log(chalk.red("❌ --qa-gate requires --chain flag"));
+        rejectPreflight(`❌ Invalid --concurrency value: ${options.concurrency}. Must be a positive integer.`);
         return;
     }
     let batches = null;

package/dist/src/commands/state.js

@@ -27,10 +27,13 @@ export async function stateInitCommand(options = {}) {
     const result = await discoverUntrackedWorktrees(discoverOptions);
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
+        if (!result.success)
+            process.exitCode = 1;
         return;
     }
     if (!result.success) {
         console.log(chalk.red(`✗ Discovery failed: ${result.error}`));
+        process.exitCode = 1;
         return;
     }
     if (result.discovered.length === 0) {
@@ -106,6 +109,7 @@ export async function stateRebuildCommand(options = {}) {
         else {
             console.log(chalk.red(`✗ Log rebuild failed: ${logResult.error}`));
         }
+        process.exitCode = 1;
         return;
     }
     // Step 2: Discover and add untracked worktrees
@@ -204,10 +208,13 @@ export async function stateCleanCommand(options = {}) {
     });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
+        if (!result.success)
+            process.exitCode = 1;
         return;
     }
     if (!result.success) {
         console.log(chalk.red(`✗ Cleanup failed: ${result.error}`));
+        process.exitCode = 1;
         return;
     }
     const orphanedCount = result.orphaned.length;

package/dist/src/commands/status.d.ts

@@ -1,6 +1,7 @@
 /**
  * sequant status - Show version, configuration, and workflow state
  */
+import { type IssueState } from "../lib/workflow/state-schema.js";
 export interface StatusCommandOptions {
     /** Show only issues state */
     issues?: boolean;
@@ -21,4 +22,12 @@ export interface StatusCommandOptions {
     /** Skip GitHub API queries (offline mode) */
     offline?: boolean;
 }
+/**
+ * Format a single issue state for display
+ *
+ * @internal Exported for testing only (#892: the windowHalt/autoWait pause
+ * lines are display contract — a halted issue must read as resumable, not as
+ * a bare failure).
+ */
+export declare function formatIssueState(issue: IssueState): string;
 export declare function statusCommand(options?: StatusCommandOptions): Promise<void>;

package/dist/src/commands/status.js

@@ -2,6 +2,8 @@
  * sequant status - Show version, configuration, and workflow state
  */
 import chalk from "chalk";
+import { formatResetTime } from "../lib/errors.js";
+import { MAX_RESUME_REENTRIES } from "../lib/workflow/state-schema.js";
 import { ui, colors } from "../lib/cli-ui.js";
 import { getManifest, getPackageVersion } from "../lib/manifest.js";
 import { fileExists } from "../lib/fs.js";
@@ -102,8 +104,12 @@ function getPhaseSymbol(phaseState) {
 }
 /**
  * Format a single issue state for display
+ *
+ * @internal Exported for testing only (#892: the windowHalt/autoWait pause
+ * lines are display contract — a halted issue must read as resumable, not as
+ * a bare failure).
  */
-function formatIssueState(issue) {
+export function formatIssueState(issue) {
     const lines = [];
     // Issue header
     lines.push(chalk.bold(`  #${issue.number}: ${issue.title.substring(0, 50)}${issue.title.length > 50 ? "..." : ""}`));
@@ -128,6 +134,16 @@ function formatIssueState(issue) {
         .join(" ");
     lines.push(`    Phases: ${phaseProgress}`);
     lines.push(`            ${phases.map((p) => p.charAt(0).toUpperCase()).join(" ")}`);
+    // #860: an auto-waiting issue is paused on purpose, not stalled — name the
+    // wake time so a multi-hour rate-limit pause is distinguishable from a hang.
+    if (issue.autoWait) {
+        lines.push(chalk.yellow(`    ⏸ Auto-wait: ${issue.autoWait.phase} paused — resuming at ${formatResetTime(new Date(issue.autoWait.wakeAt).getTime())}`));
+    }
+    // #892: a window-halted issue exited cleanly (lock released) and is waiting
+    // for `sequant resume` — show the resume time instead of a bare failure.
+    if (issue.windowHalt) {
+        lines.push(chalk.yellow(`    ⏸ Halted: ${issue.windowHalt.phase} hit a rate-limit window — resumable at ${formatResetTime(new Date(issue.windowHalt.resumeAt).getTime())} via \`sequant resume\` (re-entries ${issue.windowHalt.reentries}/${MAX_RESUME_REENTRIES})`));
+    }
     // PR info
     if (issue.pr) {
         lines.push(chalk.gray(`    PR: #${issue.pr.number} ${issue.pr.url}`));
@@ -419,6 +435,7 @@ async function displayIssueState(options) {
         else {
             console.log(chalk.red(`\nError reading state: ${error}`));
         }
+        process.exitCode = 1;
     }
 }
 /**
@@ -431,6 +448,8 @@ async function handleRebuild(options) {
     const result = await rebuildStateFromLogs({ verbose: !options.json });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
+        if (!result.success)
+            process.exitCode = 1;
         return;
     }
     if (result.success) {
@@ -443,6 +462,7 @@ async function handleRebuild(options) {
     }
     else {
         console.log(chalk.red(`✗ Rebuild failed: ${result.error}`));
+        process.exitCode = 1;
     }
 }
 /**
@@ -470,6 +490,8 @@ async function handleCleanup(options) {
     });
     if (options.json) {
         console.log(JSON.stringify(result, null, 2));
+        if (!result.success)
+            process.exitCode = 1;
         return;
     }
     if (result.success) {
@@ -511,5 +533,6 @@ async function handleCleanup(options) {
     }
     else {
         console.log(chalk.red(`✗ Cleanup failed: ${result.error}`));
+        process.exitCode = 1;
     }
 }

package/dist/src/commands/sync.js

@@ -8,8 +8,10 @@ import chalk from "chalk";
 import { join } from "path";
 import { createHash } from "crypto";
 import { getManifest, updateManifest, getPackageVersion, } from "../lib/manifest.js";
-import { copyTemplates, computeTemplateChanges, listTemplateFiles, getTemplatesDir, } from "../lib/templates.js";
+import { copyTemplates, computeTemplateChanges, listTemplateFiles, getTemplatesDir, assertTemplatesDirExists, isCustomizableFile, } from "../lib/templates.js";
 import { getConfig } from "../lib/config.js";
+import { resolveCliInvocation } from "../lib/version-check.js";
+import { syncSequantMcpPin } from "../lib/mcp-config.js";
 import { writeFile, readFile, fileExists, getFileStats } from "../lib/fs.js";
 import { generateAgentsMd, writeAgentsMd, AGENTS_MD_PATH, } from "../lib/agents-md.js";
 import { getProjectName } from "../lib/project-name.js";
@@ -195,6 +197,18 @@ export async function syncCommand(options = {}) {
         process.exitCode = 1;
         return;
     }
+    // Fail loudly on a missing templates root before anything reads or writes.
+    // This must precede the version fast path below: that path diffs against the
+    // same (missing) directory, sees no drift, and reports "already up to date"
+    // over an empty tree — the second-run trap in #822.
+    try {
+        await assertTemplatesDirExists();
+    }
+    catch (error) {
+        console.log(chalk.red(`❌ ${error.message}`));
+        process.exitCode = 1;
+        return;
+    }
     const packageVersion = getPackageVersion();
     const skillsVersion = await getSkillsVersion();
     if (!quiet) {
@@ -205,6 +219,18 @@ export async function syncCommand(options = {}) {
     // Get config tokens for template processing
     const config = await getConfig();
     const tokens = config?.tokens || {};
+    // Re-pin the project .mcp.json MCP server to the installed version (#793).
+    // `syncSequantMcpPin`'s contract has always named this the `update`/`sync`
+    // path, but only `update` ever called it, so a `sync` left the pin stale.
+    // Placed here for the same reason update.ts states: it must precede the
+    // "already up to date" fast path below, because a version-only upgrade
+    // leaves every template byte-identical and returns early — and that is
+    // exactly the case where the pin most needs refreshing.
+    const mcpPin = syncSequantMcpPin(process.cwd(), { dryRun });
+    if (mcpPin.updated && !quiet) {
+        const verb = dryRun ? "Would update" : "Updated";
+        console.log(chalk.blue(`${verb} .mcp.json MCP pin: ${mcpPin.from} → ${mcpPin.to}`));
+    }
     // The version marker is only a fast-path hint — verify actual content before
     // claiming "up to date". On a version match we still diff bundled templates
     // against installed content (rendered with the same variables) so we never
@@ -233,25 +259,36 @@ export async function syncCommand(options = {}) {
     }
     // Preview path: report exactly what the apply would write, then stop without
     // mutating (#722). This branch is only reached when `force` is set or the
-    // version marker mismatches — i.e. the path that runs `copyTemplates(force:
-    // true)` and rewrites the whole tree. (A matching-version, non-force dry-run
-    // already returned at the report-only short-circuit above, which never
-    // mutates.) `copyTemplates` does NOT protect in-place customizations the way
-    // `update` does — the force copy overwrites them — so the preview counts
-    // `local-override` files alongside `new`/`modified`. Reporting only
-    // new+modified would under-report the write-set, the exact divergence #722
-    // is about.
+    // version marker mismatches — i.e. the path that runs `copyTemplates` and
+    // rewrites the whole tree. (A matching-version, non-force dry-run already
+    // returned at the report-only short-circuit above, which never mutates.)
+    //
+    // Since #814 the apply path PRESERVES in-place customizations (files in
+    // CUSTOMIZABLE_FILES) under a plain sync and only overwrites them under an
+    // explicit `--force`. The preview must mirror that split exactly, or it would
+    // re-introduce the dry-run/apply divergence #722 is about: partition the
+    // `local-override` set into preserved (plain sync) vs overwritten (--force,
+    // or a non-customizable `.local`-twin the tree copy still rewrites).
     if (dryRun) {
         const changes = await computeTemplateChanges(manifest.stack, tokens);
         const newFiles = changes.filter((c) => c.status === "new");
         const modifiedFiles = changes.filter((c) => c.status === "modified");
         const localOverrides = changes.filter((c) => c.status === "local-override");
-        const toWrite = [...newFiles, ...modifiedFiles, ...localOverrides];
+        const preservedOverrides = force
+            ? []
+            : localOverrides.filter((c) => isCustomizableFile(c.path));
+        const overwrittenOverrides = localOverrides.filter((c) => force || !isCustomizableFile(c.path));
+        const toWrite = [...newFiles, ...modifiedFiles, ...overwrittenOverrides];
         if (!quiet) {
             console.log(chalk.bold("Summary (dry-run):"));
             console.log(chalk.green(`  New files: ${newFiles.length}`));
             console.log(chalk.yellow(`  Modified: ${modifiedFiles.length}`));
-            console.log(chalk.blue(`  Local overrides (overwritten by sync): ${localOverrides.length}`));
+            if (preservedOverrides.length > 0) {
+                console.log(chalk.blue(`  Customizable (preserved): ${preservedOverrides.length}`));
+            }
+            if (overwrittenOverrides.length > 0) {
+                console.log(chalk.blue(`  Local overrides (overwritten): ${overwrittenOverrides.length}`));
+            }
             if (modifiedFiles.length > 0) {
                 console.log(chalk.bold("\nModified files:"));
                 for (const file of modifiedFiles) {
@@ -264,9 +301,15 @@ export async function syncCommand(options = {}) {
                     console.log(chalk.green(`  ${file.path}`));
                 }
             }
-            if (localOverrides.length > 0) {
-                console.log(chalk.bold("\nLocal overrides (will be overwritten by sync):"));
-                for (const file of localOverrides) {
+            if (preservedOverrides.length > 0) {
+                console.log(chalk.bold("\nCustomizable files (preserved — run `sync --force` to replace):"));
+                for (const file of preservedOverrides) {
+                    console.log(chalk.blue(`  ${file.path}`));
+                }
+            }
+            if (overwrittenOverrides.length > 0) {
+                console.log(chalk.bold("\nLocal overrides (will be overwritten):"));
+                for (const file of overwrittenOverrides) {
                     console.log(chalk.blue(`  ${file.path}`));
                 }
             }
@@ -286,14 +329,39 @@ export async function syncCommand(options = {}) {
         }
         return;
     }
-    // Copy templates with force to overwrite existing files
+    // Copy templates: always refresh the managed trees, but only overwrite
+    // user-owned CUSTOMIZABLE_FILES (e.g. the constitution) when the user
+    // explicitly passed --force. These are two distinct notions of "force" and
+    // conflating them is what silently ate the constitution (#814).
     const copyOptions = {
-        force: true, // Always overwrite when syncing
+        force: true, // Always overwrite the managed skills/agents/hooks trees
+        overwriteCustomizable: force, // Clobber user-owned files only on explicit --force
     };
+    // AC-3: under --force, announce which customizable files are about to be
+    // overwritten *before* writing them, so the destructive action is never
+    // silent. Reuse the diff path's `local-override` classification (the same
+    // set --dry-run reports), narrowed to CUSTOMIZABLE_FILES.
+    if (force && !quiet) {
+        const changes = await computeTemplateChanges(manifest.stack, tokens);
+        const overwrites = changes.filter((c) => c.status === "local-override" && isCustomizableFile(c.path));
+        if (overwrites.length > 0) {
+            console.log(chalk.yellow(`Overwriting ${overwrites.length} customizable file(s) (--force):`));
+            for (const file of overwrites) {
+                console.log(chalk.yellow(`  ${file.path}`));
+            }
+        }
+    }
     if (!quiet) {
         console.log(chalk.blue("Copying templates..."));
     }
-    await copyTemplates(manifest.stack, tokens, copyOptions);
+    const { preservedCustomizable } = await copyTemplates(manifest.stack, tokens, copyOptions);
+    // AC-4: on a plain sync, report each customizable file that was preserved so
+    // the apply path's output matches what --dry-run already promises (#722).
+    if (!quiet && preservedCustomizable.length > 0) {
+        for (const file of preservedCustomizable) {
+            console.log(chalk.blue(`  preserved: ${file} — run \`sync --force\` to replace`));
+        }
+    }
     // Update version markers
     await updateSkillsVersion();
     await updateManifest();
@@ -340,9 +408,12 @@ export async function syncCommand(options = {}) {
  */
 export async function checkAndWarnSkillsOutdated(status) {
     const { outdated, currentVersion, packageVersion, contentDrift } = status ?? (await areSkillsOutdated());
+    // Name the invocation that reaches *this* build rather than assuming the
+    // documented `npm install sequant` shape — see resolveCliInvocation.
+    const cli = resolveCliInvocation();
     if (outdated) {
         console.log(chalk.yellow(`\n!  Skills are outdated (${currentVersion || "unknown"} → ${packageVersion})`));
-        console.log(chalk.yellow("   Run: npx sequant sync\n"));
+        console.log(chalk.yellow(`   Run: ${cli} sync\n`));
         return true;
     }
     if (contentDrift > 0) {
@@ -350,7 +421,7 @@ export async function checkAndWarnSkillsOutdated(status) {
         // version is report-only (it won't copy), so point at the commands that
         // actually resolve in-place drift — `sync --force` or `update`.
         console.log(chalk.yellow(`\n!  Version current, but ${contentDrift} file(s) differ from bundled content`));
-        console.log(chalk.yellow("   Run: npx sequant sync --force (or npx sequant update)\n"));
+        console.log(chalk.yellow(`   Run: ${cli} sync --force (or ${cli} update)\n`));
         return true;
     }
     return false;