pi-graphite 0.4.1 → 0.5.0

package/README.md

@@ -1,7 +1,7 @@
 # pi-graphite
 
 Opinionated pi tools + skill that wrap the [Graphite](https://graphite.com)
-`gt` CLI for stacked PR workflows. Seven tools, one correct path.
+`gt` CLI for stacked PR workflows. A small set of tools, one correct path.
 
 ```
 graphite_status → (graphite_setup if needed) → graphite_sync → graphite_navigate
@@ -46,10 +46,11 @@ agent loads it on demand.
 | `graphite_status`        | Read-only snapshot: current stack + current branch + PR + restack hints | `gt log --stack`, `gt info`                    |
 | `graphite_setup`         | Initialize Graphite or track an existing Git branch with explicit parent | `gt init --trunk`, `gt track --parent`         |
 | `graphite_sync`          | Start-of-day / after-merge cleanup + restack                            | `gt sync`                                      |
+| `graphite_get`           | Pull a branch / stack from the remote                                   | `gt get <branch>`                              |
 | `graphite_navigate`      | Move around the stack                                                   | `gt checkout`, `gt up`/`down`/`top`/`bottom`   |
 | `graphite_change`        | Create / amend a stacked branch                                         | `gt create -am`, `gt modify -am`, `gt modify --into`, `gt absorb` |
 | `graphite_submit`  | Push the entire stack and open/update PRs (dry-run by default)          | `gt submit --stack --no-edit --no-ai`          |
-| `graphite_recover`       | Continue / abort / undo                                                 | `gt continue`, `gt abort`, `gt undo`           |
+| `graphite_recover`       | Continue / abort / undo / restack                                       | `gt continue`, `gt abort`, `gt undo`, `gt restack` |
 
 ## Golden path
 
@@ -80,7 +81,9 @@ dependent branches.
 - Every tool requires absolute `cwd`.
 - `gt` is invoked with `--cwd <cwd> --no-interactive`, no shell strings. Tools that support AI metadata pass `--no-ai`.
 - Editor / pager / browser env is forced safe (`GT_EDITOR=true`, `GT_PAGER=`,
-  `BROWSER=true`, …). Commands have a hard timeout.
+  `BROWSER=true`, …). Commands have a hard timeout. `GRAPHITE_INTERACTIVE` is
+  deliberately **not** set — some `gt` builds treat it as "running inside
+  Graphite Interactive" and silently return empty output for read commands.
 - Interactive editor / hunk / browser / reorder paths are not exposed.
 - Commands echoed in tool output are safe to copy-paste back into a shell.
 - `graphite_setup action=track_branch` requires explicit `branch`, explicit
@@ -93,10 +96,20 @@ dependent branches.
   still contain `<<<<<<<` markers, unless `allowConflictMarkers:true`.
 - Output is ANSI-stripped, branded ("Graphite" not "Charcoal"), and truncated
   to ~50 KB / 2000 lines.
-- Stderr is parsed into structured `hints`
+- Failure output is parsed into structured `hints`
   (`notInitialized`, `conflictHalted`, `restackNeeded`, `trunkOutOfSync`,
   `branchNotTracked`, `noChangesStaged`, `checkedOutElsewhere`,
-  `operatingOnTrunk`, …).
+  `operatingOnTrunk`, `emptyOutput`, …).
+- Read commands that must produce output (`graphite_status`) treat an
+  exit-0 **empty stdout** as a failure (`emptyOutput` hint) instead of a
+  misleading "ok".
+- Output is also scanned (on success **and** failure) for non-fatal
+  `warnings` (`skippedBranches`, `remoteChanged`, `alreadyMerged`,
+  `needsRestack`). A result with warnings is reported as `ok (with warnings)`
+  so a `gt sync` / `gt submit` that silently skipped work is not mistaken for
+  a clean success.
+- A **mutating** command that fails appends a "partial side effects possible"
+  note, prompting a follow-up `graphite_status`.
 
 ### Git hooks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-graphite",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Opinionated pi tools + skill for stacked PR workflows with the Graphite (gt) CLI.",
   "keywords": [
     "pi",

package/skills/graphite/SKILL.md

@@ -26,27 +26,47 @@ Do not use it for:
   dedicated `gh` tool/extension; see the `gh` rule below
 - reading PR review comments or CI status — same
 - rewriting history beyond create/amend (split / fold / move / squash /
-  reorder). The extension does not expose stack surgery. Do not invoke
-  `gt` directly from bash for these — those subcommands prompt
-  interactively (base selectors, hunk pickers, editors) and will hang.
-  Ask the user to run them manually in their own terminal.
+  reorder). The extension does not expose stack surgery, and those
+  subcommands prompt interactively (base selectors, hunk pickers, editors)
+  and will hang. Ask the user to run them in their own terminal.
 
 ## Tools
 
-The extension registers seven tools. Prefer them over `gt`/`git`/`gh` in bash.
+The extension registers these tools. Prefer them over `gt`/`git`/`gh` in bash.
 
 | Tool | Purpose |
 |---|---|
 | `graphite_status` | Read-only snapshot: current stack + current branch + PR + restack hint |
 | `graphite_setup` | Initialize Graphite or track an existing Git branch with explicit parent |
 | `graphite_sync` | `gt sync` — pull trunk, drop merged branches, restack |
+| `graphite_get` | `gt get <branch>` — pull a branch / stack from the remote |
 | `graphite_navigate` | `gt checkout` / `up` / `down` / `top` / `bottom` / trunk |
 | `graphite_change` | `gt create` / `gt modify` / `gt modify --into` / `gt absorb` |
 | `graphite_submit` | `gt submit --stack --no-edit` (dry-run by default) |
-| `graphite_recover` | `gt continue` / `gt abort` / `gt undo` |
+| `graphite_recover` | `gt continue` / `gt abort` / `gt undo` / `gt restack` |
 
 All tools require an absolute `cwd`.
 
+## Reading tool output (don't trust a bare "ok")
+
+Each result starts with `[<label>] ok | ok (with warnings) | fail`. Read past
+the status line:
+
+- **`fail`** — read the `--- hints ---` and `--- suggestion ---` blocks; they
+  tell you exactly which recovery tool to call.
+- **`ok (with warnings)`** — gt exited 0 but its output mentioned skipped /
+  remotely-changed / already-merged branches or a needed restack. Treat this
+  as "succeeded but verify": run `graphite_status` before assuming the stack
+  is in the expected shape.
+- **`emptyOutput` hint on a status call** — gt returned nothing where output
+  was expected. Usually means the branch is untracked, the repo is not
+  Graphite-initialized, or the gt build short-circuited. Follow the
+  suggestion (often `graphite_setup`), and you may run a **read-only** gt
+  command directly to confirm (see the direct-`gt` rule).
+- After a **failed mutating** command (change / submit apply / sync / get /
+  recover / setup) the suggestion warns "partial side effects possible".
+  Always run `graphite_status` to see the real state before retrying.
+
 ## Golden path
 
 ```
@@ -179,6 +199,34 @@ graphite_status({ cwd })
 
 If `gt sync` halts on conflict, use the conflict recipe below.
 
+### Restack without pulling from remote
+
+When `graphite_status` shows branches out of date with their parent but trunk
+has not moved (no remote pull needed), restack directly:
+
+```
+graphite_recover({ cwd, action: "restack" })
+graphite_status({ cwd })
+```
+
+Use `graphite_sync` instead when trunk itself may have advanced on the remote.
+If restack halts on a conflict, follow the conflict recipe.
+
+### Pull a branch / stack from the remote
+
+To check out a teammate's branch, or re-pull a branch that changed remotely:
+
+```
+graphite_get({ cwd, branch: "<branch>" })
+graphite_status({ cwd })
+```
+
+If local commits should be overwritten by the remote version:
+
+```
+graphite_get({ cwd, branch: "<branch>", force: true, confirmDestructive: true })
+```
+
 ### Resolve a conflict
 
 1. Read the failing tool's `--- stderr ---` and `hints` block.
@@ -210,8 +258,12 @@ graphite_recover({ cwd, action: "undo" })
   use `graphite_change action="create"` instead.
 - **Never guess tracking parent.** `track_branch` requires explicit branch,
   explicit parent, and `confirmParent:true`.
-- **Prefer `graphite_sync` over manual restack.** The extension does not
-  expose a standalone restack tool. Sync covers both pull + restack.
+- **Restack vs sync.** Use `graphite_recover action="restack"` to rebase the
+  stack onto each parent's latest commit when no remote pull is needed. Use
+  `graphite_sync` when trunk may have advanced remotely (it pulls + restacks).
+- **Pull remote branches with `graphite_get`.** `graphite_sync` only touches
+  trunk + already-tracked local branches; use `graphite_get` to download a
+  branch/stack from the remote.
 - **Always dry-run first.** Show the user the dry-run plan from
   `graphite_submit apply=false` before pushing.
 - **`apply:true` requires `confirmRemote:true`.** The tool will refuse
@@ -225,5 +277,18 @@ graphite_recover({ cwd, action: "undo" })
   available. If you must shell out to `gh` from bash, pass fully explicit
   non-interactive arguments only — never `gh auth login`, `--web`, or any
   command that opens a browser, editor, or prompt.
+- **Direct `gt` is allowed only when no tool covers the command.** The tools
+  above are the default path. If you genuinely need a `gt` subcommand this
+  extension does not expose (and the user has not asked to run it
+  themselves), you may call `gt` from bash, but ONLY with explicit
+  non-interactive flags and never an interactive subcommand:
+  - Always pass `--no-interactive` (and `--cwd <abs>`).
+  - Safe read-only fallbacks: `gt log`, `gt log --stack`, `gt info`,
+    `gt children`, `gt parent`, `gt trunk`, `gt state`.
+  - Never run interactive surgery (`gt split` / `fold` / `move` / `squash` /
+    `reorder`) or anything that opens an editor, pager, hunk picker, or
+    browser — those hang. Ask the user to run those in their own terminal.
+  - Prefer the dedicated tool whenever one exists; direct `gt` skips the
+    safety confirmations, hint parsing, and warning detection the tools add.
 - **No interactive editor / browser / hunk picker.** All paths are
   non-interactive; pass explicit messages.

package/src/index.ts

@@ -3,6 +3,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { registerStatus } from "./tools/status";
 import { registerSetup } from "./tools/setup";
 import { registerSync } from "./tools/sync";
+import { registerGet } from "./tools/get";
 import { registerNavigate } from "./tools/navigate";
 import { registerChange } from "./tools/change";
 import { registerSubmit } from "./tools/submit";
@@ -11,15 +12,16 @@ import { registerRecover } from "./tools/recover";
 /**
  * pi-graphite — opinionated `gt` wrapper for stacked PR workflows.
  *
- * Seven workflow tools, one correct path:
+ * Workflow tools, one correct path:
  *
  *   graphite_status        — see where you are in the stack
  *   graphite_setup         — init repo / track existing branch when needed
  *   graphite_sync          — start-of-day / after-merge cleanup + restack
+ *   graphite_get           — pull a branch / stack from the remote
  *   graphite_navigate      — move to the branch / PR you want to mutate
  *   graphite_change        — create or amend a stacked branch
  *   graphite_submit  — push the whole stack and open/update PRs
- *   graphite_recover       — continue / abort / undo after conflicts or mistakes
+ *   graphite_recover       — continue / abort / undo / restack
  *
  * Golden path:
  *
@@ -45,6 +47,7 @@ export default function (pi: ExtensionAPI) {
   registerStatus(pi);
   registerSetup(pi);
   registerSync(pi);
+  registerGet(pi);
   registerNavigate(pi);
   registerChange(pi);
   registerSubmit(pi);

package/src/lib/exec.ts

@@ -41,10 +41,13 @@ export const SAFE_NONINTERACTIVE_ENV: Record<string, string> = {
   LESS: "FRX",
   BROWSER: "true",
   GH_BROWSER: "true",
-  // gt-gh treats this as "invoked from Graphite Interactive" and forces
-  // non-interactive behavior regardless of argv. Other gt builds should
-  // ignore it if unsupported; keep --no-interactive argv guards too.
-  GRAPHITE_INTERACTIVE: "1",
+  // NOTE: we intentionally do NOT set GRAPHITE_INTERACTIVE here. Some gt
+  // builds treat GRAPHITE_INTERACTIVE=1 as "invoked from Graphite Interactive"
+  // and short-circuit read commands (`gt log --stack`, `gt info`) to exit 0
+  // with EMPTY stdout — which made this extension blind while reporting
+  // success. Non-interactive behavior is already enforced via the
+  // --no-interactive argv guards in runGt() plus the editor/pager/browser
+  // overrides above.
 };
 
 export function safeNoninteractiveEnv(extra?: Record<string, string>): NodeJS.ProcessEnv {

package/src/lib/result.ts

@@ -19,6 +19,40 @@ export interface GtHints {
   prMissing?: boolean;
   operatingOnTrunk?: boolean;
   invalidArgument?: string;
+  /** exit 0 but stdout empty when output was expected (e.g. status). */
+  emptyOutput?: boolean;
+}
+
+/**
+ * Non-fatal warnings parsed from BOTH stdout and stderr regardless of exit
+ * code. gt frequently exits 0 while skipping branches or noting that a
+ * branch changed remotely / already merged; surfacing these keeps the agent
+ * from trusting a misleadingly "ok" result.
+ */
+export interface GtWarnings {
+  skippedBranches?: boolean;
+  remoteChanged?: boolean;
+  alreadyMerged?: boolean;
+  needsRestack?: boolean;
+}
+
+const WARNING_PATTERNS: Array<[keyof GtWarnings, RegExp]> = [
+  ["skippedBranches", /\bskipp(?:ing|ed)\b/i],
+  ["remoteChanged", /updated\s+remotely|changed\s+on\s+remote|newer\s+(?:commit|version)\s+(?:on|exists)|diverged\s+from\s+remote/i],
+  ["alreadyMerged", /already\s+(?:been\s+)?merged|has\s+been\s+merged|closed\s+remotely/i],
+  // Negative lookbehind avoids matching "does not need to be restacked".
+  ["needsRestack", /(?<!not\s)needs?\s+(?:to\s+be\s+)?restack|run\s+`?gt\s+restack`?|out\s+of\s+date\s+with\s+(?:its\s+)?parent/i],
+];
+
+function parseWarnings(r: GtRunResult): GtWarnings {
+  const text = `${r.stdout}\n${r.stderr}`;
+  const w: GtWarnings = {};
+  // A help/usage dump is full of command descriptions, not real warnings.
+  if (looksLikeUsageDump(text)) return w;
+  for (const [key, re] of WARNING_PATTERNS) {
+    if (re.test(text)) (w as Record<string, unknown>)[key] = true;
+  }
+  return w;
 }
 
 // Patterns run only on failure text.
@@ -68,9 +102,29 @@ const PATTERNS: Array<[Exclude<keyof GtHints, "checkedOutElsewhere" | "invalidAr
   ],
 ];
 
+/**
+ * gt dumps its full usage/help (Commands:/Options: blocks) on an unknown
+ * argument. Those command descriptions contain phrases ("halted by a rebase
+ * conflict", "restack", …) that would otherwise trigger false-positive
+ * hints. Detect the dump so we can suppress content-derived hints and keep
+ * only the invalidArgument signal.
+ */
+function looksLikeUsageDump(text: string): boolean {
+  return /\n\s*Commands:\s*\n/i.test(text) && /\n\s*Options:\s*\n/i.test(text);
+}
+
 function parseHints(r: GtRunResult): GtHints {
   const text = `${r.stdout}\n${r.stderr}`;
   const hints: GtHints = {};
+
+  // Match both singular and plural ("Unknown argument(s):").
+  const invalid = text.match(/Unknown arguments?:\s*([^\n]+)/i);
+  if (invalid) hints.invalidArgument = invalid[1].trim();
+
+  // When gt printed its help dump, the only trustworthy signal is the
+  // unknown-argument line; everything else is description text.
+  if (looksLikeUsageDump(text)) return hints;
+
   for (const [key, re] of PATTERNS) {
     if (re.test(text)) (hints as Record<string, unknown>)[key] = true;
   }
@@ -80,28 +134,56 @@ function parseHints(r: GtRunResult): GtHints {
     );
     hints.checkedOutElsewhere = { branch: m?.[1], worktree: m?.[2] };
   }
-  const invalid = text.match(/Unknown argument:\s*([^\n]+)/i);
-  if (invalid) hints.invalidArgument = invalid[1].trim();
   return hints;
 }
 
+export interface FormatOptions {
+  /**
+   * When true, an exit-0 result with empty stdout is treated as a FAILURE
+   * (with an emptyOutput hint). Use for read commands that must produce
+   * output, e.g. `gt log --stack` / `gt info`. Without this, gt silently
+   * returning nothing would be reported as "ok" and blind the agent.
+   */
+  requireStdout?: boolean;
+  /**
+   * When true, a FAILURE appends a "partial side effects possible" note so
+   * the agent knows the command may have mutated state before erroring
+   * (e.g. `gt create` made a branch then hit a metadata lock). Set for any
+   * command that can change local/remote state.
+   */
+  mutating?: boolean;
+}
+
+const PARTIAL_SIDE_EFFECTS_NOTE =
+  "This command can mutate state, and it failed mid-flight: partial side effects are possible " +
+  "(e.g. a created branch, partial restack, a metadata lock, or some PRs already pushed). " +
+  "Run graphite_status to confirm the actual stack state before retrying.";
+
 export interface FormattedResult {
   ok: boolean;
   isFailure: boolean;
   result: GtRunResult;
   /** Empty object on success. Populated only on failure. */
   hints: GtHints;
+  /** Non-fatal warnings parsed on success AND failure. */
+  warnings: GtWarnings;
   /** Recovery suggestion derived from hints + auxiliary probes. */
   suggestion?: string;
 }
 
-export function formatResult(r: GtRunResult): FormattedResult {
-  const isFailure = r.exitCode !== 0 || r.timedOut || !!r.spawnError;
+export function formatResult(r: GtRunResult, opts?: FormatOptions): FormattedResult {
+  const hardFailure = r.exitCode !== 0 || r.timedOut || !!r.spawnError;
+  const emptyOutput =
+    !hardFailure && !!opts?.requireStdout && r.stdout.trim() === "";
+  const isFailure = hardFailure || emptyOutput;
+  const hints = isFailure ? parseHints(r) : {};
+  if (emptyOutput) hints.emptyOutput = true;
   return {
     ok: !isFailure,
     isFailure,
     result: r,
-    hints: isFailure ? parseHints(r) : {},
+    hints,
+    warnings: parseWarnings(r),
   };
 }
 
@@ -127,11 +209,24 @@ export function renderText(label: string, f: FormattedResult): string {
     lines.push("--- hints ---");
     lines.push(JSON.stringify(f.hints));
   }
+  if (Object.keys(f.warnings).length) {
+    lines.push("--- warnings ---");
+    lines.push(JSON.stringify(f.warnings));
+    lines.push(
+      "gt reported success but the above conditions were detected in its output. " +
+        "Verify the result (e.g. run graphite_status) before assuming the stack is in the expected state.",
+    );
+  }
   if (f.isFailure && f.suggestion) {
     lines.push("--- suggestion ---");
     lines.push(f.suggestion);
   }
-  return `[${label}] ${f.ok ? "ok" : "fail"}\n${lines.join("\n")}`;
+  const status = f.ok
+    ? Object.keys(f.warnings).length
+      ? "ok (with warnings)"
+      : "ok"
+    : "fail";
+  return `[${label}] ${status}\n${lines.join("\n")}`;
 }
 
 /* ----------------------- auxiliary probes (best-effort) ----------------------- */
@@ -255,6 +350,13 @@ export async function enrichFailure(cwd: string, f: FormattedResult): Promise<vo
       `Operation refused on the trunk branch. Check out a non-trunk branch first with graphite_navigate.`,
     );
   }
+  if (f.hints.emptyOutput) {
+    parts.push(
+      `gt exited 0 but produced no output where output was expected. This usually means the current branch is not tracked by Graphite, you are not in a Graphite-initialized repo, or the gt build short-circuited (do NOT set GRAPHITE_INTERACTIVE). ` +
+        `Confirm with \`git -C <cwd> rev-parse --abbrev-ref HEAD\` and \`gt --version\`, and consider running graphite_setup. ` +
+        `As a fallback you may run a read-only gt command directly (e.g. \`gt log --stack\`) with non-interactive flags.`,
+    );
+  }
 
   if (parts.length) f.suggestion = parts.join(" ");
 }
@@ -268,10 +370,16 @@ export async function ensureSuccess(
   label: string,
   r: GtRunResult,
   cwd: string,
+  opts?: FormatOptions,
 ): Promise<FormattedResult> {
-  const f = formatResult(r);
+  const f = formatResult(r, opts);
   if (f.isFailure) {
     await enrichFailure(cwd, f);
+    if (opts?.mutating) {
+      f.suggestion = f.suggestion
+        ? `${f.suggestion} ${PARTIAL_SIDE_EFFECTS_NOTE}`
+        : PARTIAL_SIDE_EFFECTS_NOTE;
+    }
     throw new Error(renderText(label, f));
   }
   return f;
@@ -283,10 +391,13 @@ export async function ensureSuccess(
  * agent sees the full picture, not just the first error.
  */
 export async function ensureAllSuccess(
-  items: Array<{ label: string; result: GtRunResult }>,
+  items: Array<{ label: string; result: GtRunResult; requireStdout?: boolean }>,
   cwd: string,
 ): Promise<FormattedResult[]> {
-  const formatted = items.map((i) => ({ label: i.label, f: formatResult(i.result) }));
+  const formatted = items.map((i) => ({
+    label: i.label,
+    f: formatResult(i.result, { requireStdout: i.requireStdout }),
+  }));
   const failed = formatted.filter((x) => x.f.isFailure);
   if (failed.length) {
     await Promise.all(failed.map((x) => enrichFailure(cwd, x.f)));

package/src/tools/change.ts

@@ -130,7 +130,7 @@ export function registerChange(pi: ExtensionAPI) {
       }
       const label = `gt ${shellJoin(args)}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = await ensureSuccess(label, r, p.cwd);
+      const f = await ensureSuccess(label, r, p.cwd, { mutating: true });
       return {
         content: [{ type: "text", text: renderText(label, f) }],
         details: { action: p.action, result: f },

package/src/tools/get.ts

@@ -0,0 +1,67 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { runGt } from "../lib/exec";
+import { assertSafeRef, shellJoin } from "../lib/argv";
+import { ensureSuccess, renderText } from "../lib/result";
+import {
+  CwdParam,
+  Type,
+  requireConfirm,
+  type ToolReturn,
+} from "../lib/schema";
+
+/**
+ * graphite_get — `gt get <branch>`.
+ *
+ * Download a branch (and its descendants) from the Graphite remote and check
+ * it out. Used to pull a teammate's stack, or to re-pull a branch after it
+ * changed remotely. Distinct from graphite_sync, which operates on trunk +
+ * already-tracked local branches.
+ *
+ * Because `gt get` can overwrite local commits with the remote version,
+ * `force` requires `confirmDestructive:true`.
+ */
+export function registerGet(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_get",
+    label: "Graphite: get",
+    description:
+      "Download a branch and its descendants from the Graphite remote and check it out via `gt get <branch>`. Use to pull a teammate's stack or re-pull a branch that changed remotely. `force` (overwrite local) requires confirmDestructive.",
+    promptSnippet:
+      "graphite_get: `gt get <branch>` — pull a branch/stack from remote",
+    promptGuidelines: [
+      "Use graphite_get to pull a branch (and its descendants) from the remote. graphite_sync only handles trunk + already-tracked local branches.",
+      "graphite_get with force=true may overwrite local commits; pass confirmDestructive:true.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      branch: Type.String({
+        description: "Branch to download from the Graphite remote and check out.",
+      }),
+      force: Type.Optional(
+        Type.Boolean({
+          description:
+            "Overwrite local branch state with remote (--force). Requires confirmDestructive.",
+        }),
+      ),
+      confirmDestructive: Type.Optional(Type.Boolean()),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      if (p.force) {
+        requireConfirm(
+          p.confirmDestructive,
+          "gt get --force (may overwrite local commits with the remote version)",
+        );
+      }
+      const args = ["get", assertSafeRef(p.branch, "branch")];
+      if (p.force) args.push("--force");
+
+      const label = `gt ${shellJoin(args)}`;
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = await ensureSuccess(label, r, p.cwd, { mutating: true });
+      return {
+        content: [{ type: "text", text: renderText(label, f) }],
+        details: { result: f },
+      };
+    },
+  });
+}

package/src/tools/recover.ts

@@ -82,16 +82,17 @@ export function registerRecover(pi: ExtensionAPI) {
     name: "graphite_recover",
     label: "Graphite: recover",
     description:
-      "Recover from a halted Graphite operation or a recent mistake: continue (resume a paused gt command after resolving conflicts), abort (cancel the in-flight operation), or undo (revert the most recent gt mutation in this worktree). Always prefer this over `git rebase --continue`.",
+      "Recover or repair Graphite stack state: continue (resume a paused gt command after resolving conflicts), abort (cancel the in-flight operation), undo (revert the most recent gt mutation in this worktree), or restack (rebase the current stack so each branch sits on its parent's latest commit). Always prefer this over `git rebase --continue`.",
     promptSnippet:
-      "graphite_recover: continue / abort / undo — never use `git rebase --continue`",
+      "graphite_recover: continue / abort / undo / restack — never use `git rebase --continue`",
     promptGuidelines: [
       "After resolving a rebase or cherry-pick conflict from a gt command, call graphite_recover action=continue (not `git rebase --continue`) so Graphite propagates the fix to dependent branches.",
       "graphite_recover action=undo only undoes commands run from the current worktree.",
+      "Use graphite_recover action=restack when graphite_status reports branches out of date with their parent but no remote pull is needed; use graphite_sync when trunk itself may have moved.",
     ],
     parameters: Type.Object({
       cwd: CwdParam,
-      action: StringEnum(["continue", "abort", "undo"] as const),
+      action: StringEnum(["continue", "abort", "undo", "restack"] as const),
       stageAll: Type.Optional(
         Type.Boolean({
           description: "action=continue: stage all changes first (--all).",
@@ -135,10 +136,13 @@ export function registerRecover(pi: ExtensionAPI) {
           args = ["undo"];
           if (p.force) args.push("--force");
           break;
+        case "restack":
+          args = ["restack"];
+          break;
       }
       const label = `gt ${shellJoin(args)}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = await ensureSuccess(label, r, p.cwd);
+      const f = await ensureSuccess(label, r, p.cwd, { mutating: true });
       return {
         content: [{ type: "text", text: renderText(label, f) }],
         details: { action: p.action, result: f },

package/src/tools/setup.ts

@@ -111,7 +111,7 @@ export function registerSetup(pi: ExtensionAPI) {
 
       const label = `gt ${shellJoin(args)}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = await ensureSuccess(label, r, p.cwd);
+      const f = await ensureSuccess(label, r, p.cwd, { mutating: true });
       return {
         content: [{ type: "text", text: renderText(label, f) }],
         details: { action: p.action, result: f },

package/src/tools/status.ts

@@ -33,8 +33,8 @@ export function registerStatus(pi: ExtensionAPI) {
       ]);
       const [fl, fi] = await ensureAllSuccess(
         [
-          { label: "gt log --stack", result: log },
-          { label: "gt info", result: info },
+          { label: "gt log --stack", result: log, requireStdout: true },
+          { label: "gt info", result: info, requireStdout: true },
         ],
         p.cwd,
       );

package/src/tools/submit.ts

@@ -129,7 +129,8 @@ export function registerSubmit(pi: ExtensionAPI) {
 
       const label = `gt ${shellJoin(args)}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = await ensureSuccess(label, r, p.cwd);
+      // A dry-run does not mutate; an applied submit does.
+      const f = await ensureSuccess(label, r, p.cwd, { mutating: apply });
       return {
         content: [{ type: "text", text: renderText(label, f) }],
         details: { apply, result: f },

package/src/tools/sync.ts

@@ -70,7 +70,7 @@ export function registerSync(pi: ExtensionAPI) {
 
       const label = `gt ${shellJoin(args)}`;
       const r = await runGt(args, { cwd: p.cwd, signal });
-      const f = await ensureSuccess(label, r, p.cwd);
+      const f = await ensureSuccess(label, r, p.cwd, { mutating: true });
       return {
         content: [{ type: "text", text: renderText(label, f) }],
         details: { result: f },