opencode-ship 1.1.4 → 1.1.7

package/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 All notable changes to `opencode-ship` are recorded here.
 
+## 1.1.7 — Stabilization and self-hosting (unreleased)
+
+> Baseline: https://github.com/Viktorxyz/opencode-ship/issues/70.
+> Corrective package: https://github.com/Viktorxyz/opencode-ship/issues/72.
+> Authoritative plan: `docs/release/1.1.6-correction-plan.md`.
+
+- **Truthful baseline before implementation.** `1.1.5` remains the current
+  npm `latest`, and `1.1.7` is the active unpublished correction. The immutable
+  tag `1.1.6` failed in `pack` before npm publish or GitHub Release. This entry
+  does not claim the `1.1.7` fixes have shipped or qualified, and `main` does
+  not yet contain its own installed `.opencode` control layer.
+- **Bounded follow-up slices.** Runtime and release corrections, exact-version
+  self-host bootstrap, and automated exact-version update proposals will ship
+  as separate issue/worktree/PR lifecycles. Every automated install or update
+  pins `opencode-ship@<X.Y.Z>` and never resolves `@latest`.
+- **Convergent merge and cleanup recovery.** A Ready manifest now reconciles a
+  PR that a maintainer already merged in GitHub instead of attempting a second
+  merge. Cleanup retries resume from their persisted stage, tolerate an
+  already-removed worktree, delete the branch with the existing CAS guard,
+  seal the manifest, and clear the Git-common-dir pending record.
+- **Portable locks and bounded permissions.** Managed lock templates are
+  package-relative rather than npm-cache absolute paths. Build no longer
+  installs a broad `bash/* = allow` rule; destructive command denies remain
+  explicit while ordinary built-ins stay consumer-owned.
+- **Release and package hardening.** The GitHub Release job checks out the
+  resolved release ref, `prepack` fails without installing missing tools,
+  `opencode-ship/core` publishes real declarations and the canonical package
+  version, and the stale `0.1.3` source literal is removed.
+- **Release claims stay evidence-bound.** This entry becomes a released
+  changelog only after local verification, npm provenance, the GitHub Release,
+  qualification hashes, and a real self-host lifecycle all agree.
+
+## 1.1.6 — Qualification failed before publication
+
+> Release workflow run: https://github.com/Viktorxyz/opencode-ship/actions/runs/33495352417.
+
+- The immutable `1.1.6` tag failed in `pack` before npm publish or GitHub
+  Release. No npm package or GitHub Release was created.
+
+## 1.1.5 — `ship-plan` is product-only
+
+> Branch: `feat/1.1.5-ship-plan-prompt`.
+
+- **`ship-plan` prompt is product-only.** `1.1.4` shipped the `ship-plan` primary agent with a generic "ask clarifying questions when tradeoffs need the user's call" prompt and a "tell the user the file path and ask for confirmation before any edits" step. Both leaked workflow concerns into the chat: the model asked "open GitHub issues 0–6 or first Task 0 (commit /final)", "use this Tab (Build is for implementation)", and surfaced permission-glob internals ("`docs/superpowers/plans/` is deny; allowlist is `.opencode/plans/*.md`"). The Plan tab is the **product** half of the workflow; the user is there to talk about the product, not be taught the workflow. The rewrite replaces those lines with a strict contract: the prompt is allowed to ask only product questions (scope, UX, who it is for, what done looks like) and one final product question ("does the plan match the product you want?") before stopping. The prompt never asks how to run the work (issues vs Task N, subagent vs inline, Tab / Build, `ship-deliver`, "what next"), never mentions permission globs / deny lists / allowlists, never creates GitHub issues, never claims OpenCode's native `plan_exit`, and never offers to implement.
+- **Handoff is a file, not a chat menu.** The Plan tab writes `.opencode/plans/<​filename>.md` and stops. A later Build session is told `implement this plan <path>` (or `implement issue N` for the Issue path). The Plan tab does not offer "which approach?" or "subagent vs inline" — those are upstream Superpowers choices that ship does not copy. If a PR needs `Closes #N`, that issue is created by Build (`delivery_issue`), not by Plan.
+- **Subagent dispatch is internal.** `ship-plan` keeps its `task: explore` / `general` allowlist so it can dispatch read-only investigators and write scratch notes, but the prompt no longer asks the user whether to use subagents. The decision is made by the planning agent itself from the size of the request.
+- **`tests/package/neutral-consumer.test.mjs` regression.** The post-init probe now asserts the new prompt lines are present and the old workflow-leaking lines are absent. The 1.1.3 stale-record removal path is unchanged, so `opencode-ship update` from prior 1.1.x installs still cleans the leftover `*` wildcards the same way it did before this release.
+
 ## 1.1.4 — `ship-plan` primary planning agent
 
 > Branch: `feat/1.1.4-ship-plan`.

package/README.md

@@ -2,9 +2,9 @@
 
 > npm-distributed OpenCode installer and delivery plugin: a single command materialises the lifecycle plugin, reviewer/verifier agents, and skills into any consumer repository, with a recoverable lock and never silently overwrites managed files.
 >
-> **Status:** `1.1.4` is on `npm dist-tag latest` and adds a write-capable `ship-plan` primary planning agent. OpenCode's built-in lowercase `plan` Tab is now disabled by the installer (the native experimental Plan mode is env-only and cannot be activated from a repo-local install); `ship-plan` writes Markdown only under `.opencode/plans/*.md` and never touches source files. `1.1.3` supersedes the `1.1.2 stabilization` line by dropping the broken `permission: { "*": "deny" }` wildcard and adding a stale-pointer removal path so `update` cleans the orphan key on the first run. The `1.1.0` tag is immutable. Consumers of `opencode-delivery@0.1.x` should run `pnpm dlx opencode-ship@latest init` from the same checkout; migration recognises the legacy artifacts and adopts them when their bytes match.
+> **Status:** `1.1.5` is the current `npm dist-tag latest`. It makes the `ship-plan` primary planning agent product-only: the agent asks about the product, writes `.opencode/plans/*.md`, and stops without leaking delivery-workflow choices into the planning conversation. The immutable tag `1.1.6` failed in `pack` before npm publish or GitHub Release; no npm package or GitHub Release was created. `1.1.7` is the active unpublished correction, tracked by the authoritative [`docs/release/1.1.6-correction-plan.md`](docs/release/1.1.6-correction-plan.md).
 >
-> Consumers should use `opencode-ship@1.1.0` (or `@latest`) until `1.1.1` ships. The previous `1.0.0` is on `next`; consumers who pinned to `1.0.x` will continue to receive updates on that channel.
+> Use an exact package version for reproducible installs and all self-hosting work. Until `1.1.7` is published and qualified, the verified stable pin is `opencode-ship@1.1.5`; never resolve `@latest` inside an automated release or self-host update.
 
 ---
 
@@ -12,7 +12,7 @@
 
 ```sh
 # 1. Install managed files. No flags required.
-pnpm dlx opencode-ship@latest init
+pnpm dlx opencode-ship@1.1.5 init
 
 # 2. Restart OpenCode in this repo.
 
@@ -70,11 +70,11 @@ The only source tree that ships in the npm tarball is `assets/`. Anything copied
 Once `opencode-ship` is published, consumers install with `pnpm dlx` (or `npx`) and never edit the file by hand:
 
 ```
-pnpm dlx opencode-ship@latest init      # install managed files
-pnpm dlx opencode-ship@latest update    # apply a packaged upgrade
-pnpm dlx opencode-ship@latest diff      # preview what would change
-pnpm dlx opencode-ship@latest doctor    # environment and lock audit
-pnpm dlx opencode-ship@latest uninstall # remove only the files still matching the lock
+pnpm dlx opencode-ship@1.1.5 init      # install managed files
+pnpm dlx opencode-ship@1.1.5 update    # apply a packaged upgrade
+pnpm dlx opencode-ship@1.1.5 diff      # preview what would change
+pnpm dlx opencode-ship@1.1.5 doctor    # environment and lock audit
+pnpm dlx opencode-ship@1.1.5 uninstall # remove only the files still matching the lock
 ```
 
 If you want to try a pre-release tarball locally without publishing to npm:
@@ -109,13 +109,13 @@ These JSON Schemas are published and discoverable through the `exports` map:
 
 ### Legacy migration
 
-Existing consumers of `opencode-delivery@0.1.x` (commit-pinned shim) can run `pnpm dlx opencode-ship@latest init` from the same checkout. Migration recognises `.opencode/delivery.json`, `.opencode/delivery.lock.json`, the two canonical agents, and the generic plugin `.opencode/plugin/delivery.ts`, and adopts them when their bytes match. Legacy artifacts are preserved on disk so a downgrade remains possible; the installer does NOT modify Leo or any other consumer.
+Existing consumers of `opencode-delivery@0.1.x` (commit-pinned shim) can run `pnpm dlx opencode-ship@1.1.5 init` from the same checkout. Migration recognises `.opencode/delivery.json`, `.opencode/delivery.lock.json`, the two canonical agents, and the generic plugin `.opencode/plugin/delivery.ts`, and adopts them when their bytes match. Legacy artifacts are preserved on disk so a downgrade remains possible; the installer does NOT modify Leo or any other consumer.
 
 `diff` is now strictly read-only; it reports every change but never writes to disk, even when the migration phase has a candidate seed-config to plant.
 
 ## Lifecycle
 
-1. Begin a Build task: the delivery plugin immediately runs any queued post-merge cleanups. Failed cleanups are recorded in `ship.lock.json#cleanupPending` and retried at the next delivery task or plugin startup.
+1. Begin a Build task: the delivery plugin immediately runs any queued post-merge cleanups. Failed cleanups are recorded under `<git-common-dir>/opencode-ship/cleanup-pending.json` and retried at the next delivery task or plugin startup.
 2. Optional Deep Research checkpoint for non-trivial plans.
 3. Find or create exactly one issue per PR.
 4. Discover the default branch and fetch it.
@@ -130,7 +130,7 @@ Existing consumers of `opencode-delivery@0.1.x` (commit-pinned shim) can run `pn
 13. Push and wait for required remote CI checks.
 14. Mark the PR Ready and stop.
 15. Explicit "merge it" re-runs the freshness checks and performs the squash merge.
-16. The plugin immediately invokes `delivery_cleanup`; failures leave `cleanupPending` for the next session.
+16. The plugin immediately invokes `delivery_cleanup`; failures persist their next cleanup stage in the Git common dir for the next session.
 
 ## Exit codes
 
@@ -158,7 +158,7 @@ The shipped artifact is built by esbuild (`scripts/build.mjs`); self-contained `
 ## Status and licensing
 
 - **License:** MIT. See `LICENSE`.
-- **Versioning:** SemVer. v0.2.0 is the first npm-distributed release. v0.3.0 is the installer foundation. v0.4.0 adds the profile-aware installer foundation (`--profile` flag, lock schema v2, profile precedence) that issue #18 requires. v0.5.0 ships the engineering profile content (triage + grill-with-docs SKILL.md placeholders) required by issue #20. v0.6.0 ships the durable plan artifact + Plan Mode permission integration required by issue #21. v0.7.0 ships the M3 task loop contract (run store, task brief, Spec/Quality verdicts, 3-round breaker, commit binding, compaction context) required by issue #22. v0.8.0 ships the Ready gate contract (parallel Standards/Spec + verifier + CI on one HEAD) required by issue #23. v0.9.0 ships the transition matrix smoke (engineering installs all assets, lock tracks the active profile) required by issue #24. v1.0.0 promotes the dogfooded 0.10.0 to stable. v1.1.0 removes the legacy core profile and ships the one-liner init + setup-ship-workflow skill. v1.1.1 is the first fully self-hosting release (see `docs/release/1.1.1-stabilization-plan.md`).
+- **Versioning:** SemVer. v0.2.0 is the first npm-distributed release. v0.3.0 is the installer foundation. v0.4.0 adds the profile-aware installer foundation (`--profile` flag, lock schema v2, profile precedence) that issue #18 requires. v0.5.0 ships the engineering profile content (triage + grill-with-docs SKILL.md placeholders) required by issue #20. v0.6.0 ships the durable plan artifact + Plan Mode permission integration required by issue #21. v0.7.0 ships the M3 task loop contract (run store, task brief, Spec/Quality verdicts, 3-round breaker, commit binding, compaction context) required by issue #22. v0.8.0 ships the Ready gate contract (parallel Standards/Spec + verifier + CI on one HEAD) required by issue #23. v0.9.0 ships the transition matrix smoke (engineering installs all assets, lock tracks the active profile) required by issue #24. v1.0.0 promotes the dogfooded 0.10.0 to stable. v1.1.0 removes the legacy core profile and ships the one-liner init + setup-ship-workflow skill. v1.1.1 began the self-hosting correction line; the immutable `1.1.6` failed before publication and `1.1.7` is the planned unpublished correction (see `docs/release/1.1.6-correction-plan.md`).
 - **Compatibility:** the bundled plugin targets `@opencode-ai/plugin >= 1.15.5 < 2` and OpenCode `>= 1.15.5`.
 
 ## FAQ

package/THIRD_PARTY_NOTICES.md

@@ -1,6 +1,6 @@
 # Third-Party Notices
 
-`opencode-ship@1.1.4` ships the complete Matt Pocock and Superpowers
+`opencode-ship@1.1.7` includes the complete Matt Pocock and Superpowers
 methodology under the MIT license, plus the Ship-owned installer,
 plugin, agents, and skills. The complete immutable pin list is in
 `vendor/sources.json`; the upstream snapshots are under

package/assets/agents/ship-plan.md

@@ -35,32 +35,36 @@ permission:
 
 # Ship Plan
 
-You are the primary planning agent for this repo. Use this Tab (Build is for implementation).
+You are the primary planning agent. You talk about the product. You never talk about the workflow.
 
 ## What you do
 
-1. Read the user's request and any context files they cite (`@file`).
-2. Explore the codebase with `bash` (read-only git / ls / cat / gh issue / gh pr) and `task explore` agents. Never `cat` secrets.
-3. Ask clarifying questions through `question` when tradeoffs need the user's call.
-4. Write your plan to a single Markdown file under `.opencode/plans/<filename>.md`. Filename: lowercase, dashes, no spaces, ends in `.md` (e.g. `2026-08-20-customer-final-ux.md`).
-5. Tell the user the file path and ask for confirmation before any edits after the first write.
+1. Read the user's request and any `@file` context they cite.
+2. Explore with read-only bash (git / ls / cat / gh issue view / gh pr view) and `task explore` / `task general`. Never `cat` secrets. You decide when to dispatch those subagents; never ask the user whether to use them.
+3. Ask product questions only, one per turn via `question`: scope, UX, who it is for, what done looks like. When you must choose, recommend in one sentence.
+4. Write the plan to `.opencode/plans/<​filename>.md`. Filename: lowercase, dashes, no spaces, ends in `.md` (e.g. `2026-08-20-customer-final-ux.md`).
+5. Tell the user the file path. Ask one question: whether the plan matches the product they want. Then stop.
 
 ## What you never do
 
-- Never edit source files, configs, tests, or anything outside `.opencode/plans/*.md`.
+- Never edit anything outside `.opencode/plans/*.md`.
 - Never run mutating bash (`git commit`, `git push`, `npm install`, `rm`, `pnpm add`, …).
-- Never claim you have OpenCode's native `plan_exit` workflow. This is a replacement for the read-only native Plan Tab, not the experimental one.
-- Never invoke `task plan` or `task build`. Build runs the plan, not you.
+- Never ask how to run the work: no GitHub issues vs Task N, no Tab / Build, no subagent vs inline, no `ship-deliver`, no "what next".
+- Never mention permission globs, deny lists, allowlists, or why a path was denied.
+- Never create GitHub issues. A later Build session does that if a PR needs `Closes #N`.
+- Never claim OpenCode's native `plan_exit`. This is a replacement for the read-only native Plan Tab, not the experimental one.
+- Never invoke `task plan` or `task build`. Build runs the plan, in a different session.
+- Never offer to implement.
 
 ## Style
 
-- Write for the cheap builder model that will execute the plan. Be concrete: file paths, function names, the exact commit messages you'll commit to.
+- Write for a later session that will be told `implement this plan <path>`. Be concrete: file paths, function names, the exact commit messages.
 - Prefer small, vertical slices over big-bang rewrites.
-- Quote the source lines you'll touch.
-- When you must choose, recommend and justify in one sentence. Don't enumerate "alternatives" in the file.
+- Quote the source lines you will touch.
+- Pick one approach in the file; do not enumerate alternatives.
 
 ## Hard rules
 
-- One question per turn via `question`. Don't batch.
+- One question per turn via `question`. Product only.
 - If a write fails, surface the error verbatim. Do not retry silently.
-- Don't claim a file is written until `bash` confirms it.
+- Do not claim a file is written until `bash` confirms it.

package/dist/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// opencode-ship CLI v1.1.4
+// opencode-ship CLI v1.1.7
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __esm = (fn, res) => function __init() {
@@ -110,7 +110,7 @@ import { fileURLToPath as fileURLToPath2 } from "node:url";
 var PACKAGE_VERSION, TEMPLATE_SET;
 var init_version = __esm({
   "src/version.js"() {
-    PACKAGE_VERSION = "1.1.4";
+    PACKAGE_VERSION = "1.1.7";
     TEMPLATE_SET = `v${PACKAGE_VERSION}`;
   }
 });
@@ -119,6 +119,7 @@ var init_version = __esm({
 var catalog_exports = {};
 __export(catalog_exports, {
   CATALOG: () => CATALOG,
+  PACKAGE_ROOT: () => PACKAGE_ROOT,
   PACKAGE_VERSION: () => PACKAGE_VERSION,
   TEMPLATE_SET_ID: () => TEMPLATE_SET_ID,
   filterCatalogByProfile: () => filterCatalogByProfile,
@@ -205,7 +206,7 @@ function validateCatalog({ catalog = CATALOG } = {}) {
   }
   return catalog;
 }
-var TEMPLATE_SET_ID, packageRoot, MATT_SKILLS, SUPER_SKILLS, ENGINEERING_AGENTS, ENGINEERING_COMMANDS, CATALOG, ALLOWED_KINDS;
+var TEMPLATE_SET_ID, packageRoot, PACKAGE_ROOT, MATT_SKILLS, SUPER_SKILLS, ENGINEERING_AGENTS, ENGINEERING_COMMANDS, CATALOG, ALLOWED_KINDS;
 var init_catalog = __esm({
   "src/installer/catalog.js"() {
     init_package_root();
@@ -213,6 +214,7 @@ var init_catalog = __esm({
     init_profile();
     TEMPLATE_SET_ID = TEMPLATE_SET;
     packageRoot = resolvePackageRoot(import.meta.url);
+    PACKAGE_ROOT = packageRoot;
     MATT_SKILLS = [
       "engineering-workflow",
       "grilling",
@@ -1731,7 +1733,7 @@ init_catalog();
 init_version();
 import { existsSync as existsSync13 } from "node:fs";
 import { mkdir as mkdir6, readFile as readFile9, rename as rename5, unlink as unlink3, writeFile as writeFile6 } from "node:fs/promises";
-import { dirname as dirname8, resolve as resolve12 } from "node:path";
+import { dirname as dirname8, relative as relative2, resolve as resolve12, sep as sep2 } from "node:path";
 
 // src/installer/planner.js
 init_catalog();
@@ -1867,8 +1869,8 @@ var FORBIDDEN_BASH_GLOBS_CONTROLLER = [
   "rm -rf *",
   "rm -rf /*"
 ];
-function denyMap(globs) {
-  const out = { "*": "allow" };
+function denyMap(globs, allowByDefault = true) {
+  const out = allowByDefault ? { "*": "allow" } : {};
   for (const g of globs) out[g] = "deny";
   return out;
 }
@@ -1893,7 +1895,7 @@ function rootPermissionMatrix() {
           "delivery-verifier": "allow"
         },
         bash: {
-          ...denyMap(FORBIDDEN_BASH_GLOBS),
+          ...denyMap(FORBIDDEN_BASH_GLOBS, false),
           "rm *": "ask"
         }
       },
@@ -2734,11 +2736,11 @@ function parseTree(text, errors = [], options = ParseOptions.DEFAULT) {
       onValue({ type: getNodeType(value), offset, length, parent: currentParent, value });
       ensurePropertyComplete(offset + length);
     },
-    onSeparator: (sep2, offset, length) => {
+    onSeparator: (sep3, offset, length) => {
       if (currentParent.type === "property") {
-        if (sep2 === ":") {
+        if (sep3 === ":") {
           currentParent.colonOffset = offset;
-        } else if (sep2 === ",") {
+        } else if (sep3 === ",") {
           ensurePropertyComplete(offset);
         }
       }
@@ -5249,7 +5251,7 @@ async function assembleLock({ repoRoot, plan, lock, configPlan, rootPlan, profil
     manager: {
       schemaVersion: CURRENT_LOCK_SCHEMA,
       name: "opencode-ship",
-      version: "1.1.4",
+      version: "1.1.7",
       templateSet: TEMPLATE_SET_ID,
       profile: resolvedProfile,
       appliedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -5390,9 +5392,7 @@ function serializePlan(plan) {
 }
 function relativeTemplate(source) {
   if (typeof source !== "string") return source;
-  const prefix = `${process.cwd()}/`;
-  if (source.startsWith(prefix)) return source.slice(prefix.length);
-  return source;
+  return relative2(PACKAGE_ROOT, source).split(sep2).join("/");
 }
 
 // src/installer/commands/doctor.js

package/dist/core.d.ts

@@ -1 +1,583 @@
-export {};
+/**
+ * Public type declarations for the opencode-ship package.
+ *
+ * The package ships plain JavaScript ESM sources; this declaration
+ * file gives TypeScript consumers the surface they need to typecheck
+ * `import` statements without falling back to `any`. Every public
+ * value export from `src/index.js` is declared here; the consumer
+ * fixture under `tests/fixtures/consumer.ts` enforces that.
+ */
+
+// ---------------------------------------------------------------------------
+// Primitives
+// ---------------------------------------------------------------------------
+
+export type Sha = string;
+export type Branch = string;
+export type RepoSlug = `${string}/${string}`;
+export type IssueNumber = number;
+export type PullRequestNumber = number;
+
+export type ContractVersion = 1;
+
+export interface AdapterLock {
+  contractVersion: ContractVersion;
+  adapterSha256: Sha;
+  writtenAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Lifecycle
+// ---------------------------------------------------------------------------
+
+export type LifecycleState =
+  | "issue-linked"
+  | "worktree-created"
+  | "draft-open"
+  | "validating"
+  | "ready"
+  | "merged"
+  | "cleanup-pending"
+  | "cleaned"
+  | "failed"
+  | "aborted";
+
+export interface LifecycleTransition {
+  from: LifecycleState;
+  to: LifecycleState;
+  at: number;
+  reason?: string;
+}
+
+export interface Manifest {
+  schemaVersion: 2;
+  taskId: string;
+  repoIdentity: RepoSlug;
+  issueNumber: IssueNumber | null;
+  prNumber: PullRequestNumber | null;
+  baseBranch: Branch;
+  baseSha: Sha;
+  branch: Branch;
+  worktreePath: string | null;
+  lastPrHeadSha: Sha | null;
+  lastReviewerSha: Sha | null;
+  lastVerifierSha: Sha | null;
+  workflowId: string | null;
+  owner: string;
+  state: LifecycleState;
+  transitionLog: LifecycleTransition[];
+  fatalReason?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateManifestInput {
+  taskId: string;
+  repoIdentity: RepoSlug;
+  issueNumber: IssueNumber | null;
+  baseBranch: Branch;
+  baseSha: Sha;
+  branch: Branch;
+  owner: string;
+  prNumber?: PullRequestNumber | null;
+  lastPrHeadSha?: Sha | null;
+  workflowId?: string | null;
+}
+
+export interface IssueSummary {
+  number: IssueNumber;
+  url: string;
+  state: "OPEN" | "CLOSED";
+  pullRequest: PullRequestSummary | null;
+}
+
+export interface PullRequestSummary {
+  number: PullRequestNumber;
+  url: string;
+  baseRefName: Branch;
+  headRefName: Branch;
+  headSha: Sha;
+  draft: boolean;
+  mergeable: "MERGEABLE" | "CONFLICTING" | "UNKNOWN";
+  mergeStateStatus: string;
+  merged: boolean;
+  mergedAt: string | null;
+}
+
+export interface CheckSummary {
+  name: string;
+  state: "success" | "failure" | "pending" | "neutral" | "skipped" | "cancelled" | "timed_out" | "action_required" | "stale" | "queued" | "in_progress" | "requested";
+  bucket: "pass" | "fail" | "pending" | "skip" | "neutral";
+}
+
+export interface EnsureIssueResult {
+  summary: IssueSummary;
+  created: boolean;
+}
+
+export interface GithubDriver {
+  ensureIssue(args: { repo: RepoSlug; title: string; body: string; labels: readonly string[] }): Promise<EnsureIssueResult>;
+  openDraftPullRequest(args: { repo: RepoSlug; head: Branch; base: Branch; title: string; body: string; issueNumber: IssueNumber }): Promise<PullRequestSummary>;
+  updatePullRequestBody(args: { repo: RepoSlug; number: PullRequestNumber; body: string }): Promise<void>;
+  markReady(args: { repo: RepoSlug; number: PullRequestNumber }): Promise<void>;
+  mergePullRequest(args: { repo: RepoSlug; number: PullRequestNumber; subject: string }): Promise<PullRequestSummary>;
+  readPullRequest(args: { repo: RepoSlug; number: PullRequestNumber }): Promise<PullRequestSummary>;
+  readChecks(args: { repo: RepoSlug; sha?: Sha; number?: PullRequestNumber; branch?: Branch; required: readonly string[] }): Promise<CheckSummary[]>;
+  comment(args: { repo: RepoSlug; number: PullRequestNumber; body: string }): Promise<void>;
+  refreshHead(args: { repo: RepoSlug; number: PullRequestNumber }): Promise<Sha>;
+}
+
+export interface CreateGhDriverOptions {
+  runner?: (args: readonly string[]) => Promise<{ status: number; stdout: string; stderr: string }>;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+export type GhRunner = (args: readonly string[]) => Promise<{ status: number; stdout: string; stderr: string }>;
+
+export interface GhStubHandle {
+  driver: GithubDriver;
+  queue: Array<{ match: (args: readonly string[]) => boolean; status?: number; stdout?: string; stderr?: string }>;
+}
+
+export interface RepoRef {
+  owner: string;
+  name: string;
+}
+
+// ---------------------------------------------------------------------------
+// Adapter
+// ---------------------------------------------------------------------------
+
+export interface Adapter {
+  contractVersion: 1;
+  repository: {
+    remote: string;
+    defaultBranch?: { discover?: boolean; name?: Branch };
+  };
+  forge?: {
+    driver: "github";
+    issueRequired?: boolean;
+    draftAfterFirstCommit?: boolean;
+    issueClosingSyntax?: boolean;
+  };
+  worktree?: {
+    root: string;
+    branchTemplate: string;
+    bootstrap?: readonly (readonly string[])[];
+  };
+  verification?: {
+    commands: readonly { id: string; argv: readonly string[]; timeoutMs?: number }[];
+    requireCleanDiffAfter?: boolean;
+    invalidateOnHeadChange?: boolean;
+  };
+  review?: {
+    agent: string;
+    required: boolean;
+    invalidateOnHeadChange: boolean;
+  };
+  ci?: {
+    driver: "github-status-checks";
+    requiredChecks: readonly string[];
+    wait: boolean;
+    flakyRetry: 0 | 1;
+  };
+  ready?: {
+    requires: readonly ("review" | "local-verification" | "remote-ci")[];
+    stopAfterReady: boolean;
+  };
+  merge?: {
+    strategy: "squash";
+    policy: "explicit-user-request-only";
+    requireFreshGates: boolean;
+  };
+  cleanup?: {
+    when: "next-task";
+    requires: readonly ("pr-merged" | "worktree-clean" | "no-unpublished-commits")[];
+  };
+}
+
+export type AdapterLoadResult =
+  | { ok: true; adapter: Adapter; path: string; sha256: Sha }
+  | { ok: false; error: { kind: "missing" | "parse" | "contract"; path: string; message?: string; issues?: readonly string[] } };
+
+export interface DoctorCheck {
+  name: string;
+  ok: boolean;
+  detail: string;
+}
+
+export interface DoctorReport {
+  contractVersion: 1;
+  adapterPath: string | null;
+  adapterSha256: Sha | null;
+  lockPath: string | null;
+  lockSha256: Sha | null;
+  packageVersion: string | null;
+  nodeVersion: string;
+  ghVersion: string | null;
+  gitVersion: string | null;
+  checks: DoctorCheck[];
+}
+
+export type TransitionResult =
+  | { ok: true; from: LifecycleState; to: LifecycleState; at: number; reason?: string }
+  | { ok: false; from: LifecycleState; attempted: LifecycleState; reason: string };
+
+export interface GateSnapshot {
+  prHead: Sha | null;
+  reviewerSha: Sha | null;
+  verifierSha: Sha | null;
+  checks: readonly CheckSummary[];
+  missingChecks: readonly string[];
+  failingChecks: readonly string[];
+  pendingChecks: readonly string[];
+}
+
+export interface GateCheck {
+  ok: boolean;
+  reason?: string;
+  snapshot: GateSnapshot;
+}
+
+export interface RecoveryReport {
+  total: number;
+  pendingCleanup: number;
+  orphanWorktrees: number;
+  cleaned: number;
+  notes: string[];
+}
+
+export interface WorktreeRecordShape {
+  path: string;
+  branch: string;
+  head: Sha;
+}
+
+export type RunCommandResult =
+  | { ok: true; status: number; stdout: string; stderr: string }
+  | { ok: false; error: Error };
+
+// ---------------------------------------------------------------------------
+// Tool factory deps shapes
+// ---------------------------------------------------------------------------
+
+export interface BaseToolDeps {
+  driver: GithubDriver;
+  repoRoot: string;
+  repoSlug: RepoSlug;
+  owner: string;
+  adapter: Adapter;
+  remote?: string;
+  packageVersion?: string;
+}
+
+export interface InspectToolDeps {
+  driver?: GithubDriver;
+  repoRoot: string;
+  repoSlug: RepoSlug;
+  owner?: string;
+  adapter?: Adapter | null;
+  packageVersion: string;
+  remote?: string;
+}
+
+export interface IssueToolInput {
+  taskId: string;
+  title: string;
+  body?: string;
+  baseBranch: string;
+  baseSha?: string;
+  branch: string;
+  labels?: readonly string[];
+}
+
+export interface WorktreeToolInput {
+  taskId: string;
+  branch: string;
+  worktreeRelativePath: string;
+}
+
+export interface VerifyToolInput {
+  taskId: string;
+  commandId?: string;
+}
+
+export interface ReviewToolInput {
+  taskId: string;
+  status: "pass" | "fail" | "blocked" | "partial";
+  headSha?: Sha;
+  findings?: unknown;
+  envelope?: unknown;
+}
+
+export interface PrToolInput {
+  taskId: string;
+  title: string;
+  body: string;
+}
+
+export interface ReadyToolInput {
+  taskId: string;
+}
+
+export interface MergeToolInput {
+  taskId: string;
+  subject: string;
+}
+
+export interface CleanupToolInput {
+  taskId: string;
+}
+
+export type Envelope<TKind extends string, TData> = { kind: TKind } & TData;
+
+// ---------------------------------------------------------------------------
+// Envelope shapes (mirror the runtime tool returns)
+// ---------------------------------------------------------------------------
+
+export type IssueEnvelope = Envelope<
+  "issue",
+  {
+    contractVersion: 1;
+    created: boolean;
+    issueNumber: IssueNumber;
+    issueUrl: string;
+    manifestPath: string;
+  }
+>;
+
+export type MissingManifestEnvelope = Envelope<"missing-manifest", { taskId: string }>;
+export type ManifestStateEnvelope = Envelope<"manifest-state", { state: LifecycleState }>;
+export type MissingWorktreePathEnvelope = Envelope<"missing-worktree-path", Record<string, never>>;
+export type MissingPrEnvelope = Envelope<"missing-pr", Record<string, never>>;
+export type WorktreeExistsEnvelope = Envelope<"worktree-exists", Record<string, never>>;
+export type BranchExistsLocallyEnvelope = Envelope<"branch-exists-locally", { branch: Branch }>;
+export type BranchExistsRemotelyEnvelope = Envelope<"branch-exists-remotely", { branch: Branch }>;
+export type RemoteFetchEnvelope = Envelope<"remote-fetch", { stderr: string }>;
+export type CreateFailedEnvelope = Envelope<"create-failed", { stderr: string }>;
+export type HeadChangedAfterVerifierEnvelope = Envelope<"head-changed-after-verifier", { headSha: Sha; verifierSha: Sha }>;
+export type HeadChangedAfterReviewEnvelope = Envelope<"head-changed-after-review", { headSha: Sha; reviewSha: Sha }>;
+export type MissingGateEnvelope = Envelope<"missing-gate", { gate: "review" | "local-verification" | "remote-ci" }>;
+export type CiFailingEnvelope = Envelope<"ci-failing", { failing: readonly string[] }>;
+export type CiPendingEnvelope = Envelope<"ci-pending", { pending: readonly string[] }>;
+export type NotReadyEnvelope = Envelope<"not-ready", { state: LifecycleState }>;
+export type WrongBaseEnvelope = Envelope<"wrong-base", { base: Branch }>;
+export type HeadChangedEnvelope = Envelope<"head-changed", { headSha: Sha; manifestSha: Sha }>;
+export type NotMergeableEnvelope = Envelope<"not-mergeable", { reason: string }>;
+export type DirtyWorktreeEnvelope = Envelope<"dirty-worktree", Record<string, never>>;
+export type RebaseInProgressEnvelope = Envelope<"rebase-in-progress", Record<string, never>>;
+export type HeadMismatchEnvelope = Envelope<"head-mismatch", { headSha: Sha; manifestSha: Sha }>;
+export type CurrentCheckoutEnvelope = Envelope<"current-checkout", { worktreePath: string }>;
+export type UnmergedEnvelope = Envelope<"unmerged", { headSha: Sha; manifestSha: Sha }>;
+export type BaseMismatchEnvelope = Envelope<"base-mismatch", { manifestBase: Branch; prBase: Branch }>;
+export type HasUnpublishedCommitsEnvelope = Envelope<"has-unpublished-commits", { ahead: number }>;
+export type RemoveFailedEnvelope = Envelope<"remove-failed", { stderr: string }>;
+export type UnsafeCleanupEnvelope = Envelope<"unsafe-cleanup", { signals: readonly string[] }>;
+export type VerifyFailedEnvelope = Envelope<"verify-failed", { commandId: string; status: number; headSha: Sha | null }>;
+export type PathEscapeEnvelope = Envelope<"path-escape", { resolvedPath: string }>;
+export type BootstrapFailedEnvelope = Envelope<"bootstrap-failed", { stderr: string; argv: readonly string[] }>;
+
+// ---------------------------------------------------------------------------
+// Value export declarations. The runtime values live in plain JS modules;
+// these declarations are the contract that consumers rely on.
+// ---------------------------------------------------------------------------
+
+export declare const ADAPTER_CONTRACT_VERSION: ContractVersion;
+export declare const ADAPTER_FILENAME: string;
+export declare const LOCK_FILENAME: string;
+export declare const PACKAGE_VERSION: string;
+export declare const STATES: readonly LifecycleState[];
+
+export declare const WorktreeRecord: WorktreeRecordShape;
+
+export declare function validateAdapter(value: unknown): {
+  ok: boolean;
+  issues?: readonly string[];
+  adapter?: Adapter;
+};
+export declare function loadAdapter(repoRoot: string): Promise<AdapterLoadResult>;
+export declare function writeLock(repoRoot: string, adapterSha256: Sha): Promise<string>;
+export declare function readLock(repoRoot: string): Promise<AdapterLock | null>;
+export declare function findOpencodeDir(start: string): string | null;
+
+export declare function createManifest(input: CreateManifestInput): Manifest;
+export declare function transition(
+  manifest: Manifest,
+  to: LifecycleState,
+  opts?: { reason?: string; now?: () => Date },
+): TransitionResult;
+export declare function canTransition(from: LifecycleState, to: LifecycleState): boolean;
+export declare function isTerminal(state: LifecycleState): boolean;
+export declare function mustRerunReview(previousSha: Sha | null, currentSha: Sha): boolean;
+export declare function mustRerunVerifier(previousSha: Sha | null, currentSha: Sha): boolean;
+
+export declare function writeManifest(repoRoot: string, manifest: Manifest): Promise<string>;
+export declare function readManifest(repoRoot: string, taskId: string): Promise<Manifest | null>;
+export declare function listManifests(repoRoot: string): Promise<Manifest[]>;
+export declare function deleteManifest(repoRoot: string, taskId: string): Promise<void>;
+
+export declare function isInsideWorktree(cwd: string): boolean;
+export declare function isMainCheckout(cwd: string): boolean;
+export declare function listWorktrees(cwd: string): WorktreeRecordShape[];
+export declare function isWorktreeClean(cwd: string): boolean;
+export declare function isRebaseInProgress(cwd: string): boolean;
+export declare function currentBranch(cwd: string): Branch | null;
+export declare function revParse(ref: string, cwd: string): Sha | null;
+export declare function fetchBranch(remote: string, branch: Branch, cwd: string): { status: number; stderr: string };
+export declare function remoteExists(remote: string, cwd: string): boolean;
+export declare function createWorktree(opts: { cwd: string; branch: Branch; worktreePath: string; base: string }): { status: number; stderr: string };
+export declare function createWorktreeFromLocal(opts: { cwd: string; branch: Branch; worktreePath: string; base: string }): { status: number; stderr: string };
+export declare function worktreeExists(cwd: string, path: string): boolean;
+export declare function branchExistsLocally(branch: Branch, cwd: string): boolean;
+export declare function branchExistsRemotely(remote: string, branch: Branch, cwd: string): boolean;
+export declare function mergeIntoFeature(branch: Branch, base: Branch, cwd: string): { status: number; stderr: string };
+export declare function currentHead(cwd: string): Sha | null;
+export declare function push(remote: string, branch: Branch, cwd: string): { status: number; stderr: string };
+export declare function pushForceDisabled(remote: string, branch: Branch, cwd: string): { status: number; stderr: string };
+export declare function defaultBranch(cwd: string): Branch | null;
+export declare function mergeBaseRemoteHead(remote: string, branch: Branch, cwd: string): Sha | null;
+
+export declare function createGhDriver(opts?: CreateGhDriverOptions): GithubDriver;
+export declare function createGhStub(
+  responses: Array<{
+    match: (args: readonly string[]) => boolean;
+    status?: number;
+    stdout?: string;
+    stderr?: string;
+  }>,
+): GhStubHandle;
+export declare function parseRepoSlug(slug: string): RepoRef | null;
+
+export declare function scanRecovery(repoRoot: string): Promise<RecoveryReport>;
+export declare function wouldCleanupBeSafe(args: {
+  prMerged: boolean;
+  worktreeClean: boolean;
+  rebaseInProgress: boolean;
+  headMatchesPr: boolean;
+  baseMatches: boolean;
+}): boolean;
+export declare function removeManifestIfSafe(repoRoot: string, taskId: string): Promise<boolean>;
+export declare function recoverManifestAfterCrash(manifest: Manifest): Manifest;
+
+export declare function doctor(repoRoot: string, packageVersion: string | null, adapter?: Adapter | null): Promise<DoctorReport>;
+
+export declare function bucketFor(check: CheckSummary | undefined | null): "pass" | "fail" | "pending" | "skip" | "neutral";
+export declare function gateSnapshot(args: {
+  manifest: { adapter?: Adapter | null; lastReviewerSha?: Sha | null; lastVerifierSha?: Sha | null };
+  prHead: Sha | null;
+  checks: readonly CheckSummary[];
+}): GateSnapshot;
+export declare function checkGates(args: {
+  manifest: { adapter?: Adapter | null; lastReviewerSha?: Sha | null; lastVerifierSha?: Sha | null };
+  prHead: Sha | null;
+  checks: readonly CheckSummary[];
+  requires: readonly ("review" | "local-verification" | "remote-ci")[];
+}): GateCheck;
+export declare function gateFailureEnvelope(result: { reason: string; snapshot: GateSnapshot }):
+  | MissingGateEnvelope
+  | HeadChangedAfterReviewEnvelope
+  | HeadChangedAfterVerifierEnvelope
+  | Envelope<"ci-missing", { missing: readonly string[] }>
+  | Envelope<"ci-failing", { failing: readonly string[] }>
+  | Envelope<"ci-pending", { pending: readonly string[] }>
+  | Envelope<"gate-failed", { reason: string }>;
+
+export declare function createInspectTool(deps: InspectToolDeps): (input: { taskId: string }) => Promise<{
+  contractVersion: 1;
+  manifest: Manifest | null;
+  doctor: DoctorReport;
+}>;
+
+export declare function createIssueTool(deps: BaseToolDeps): (input: IssueToolInput) => Promise<IssueEnvelope | Envelope<"missing-input", { field: string }> | Envelope<"lifecycle", { reason: string }>>;
+
+export declare function createWorktreeTool(deps: BaseToolDeps): (input: WorktreeToolInput) => Promise<
+  | Envelope<"worktree", { contractVersion: 1; branch: Branch; worktreePath: string; headSha: Sha; manifestPath: string }>
+  | MissingManifestEnvelope
+  | ManifestStateEnvelope
+  | Envelope<"missing-input", { field: string }>
+  | RemoteFetchEnvelope
+  | BranchExistsLocallyEnvelope
+  | BranchExistsRemotelyEnvelope
+  | WorktreeExistsEnvelope
+  | CreateFailedEnvelope
+  | Envelope<"missing-base-sha", Record<string, never>>
+  | Envelope<"bootstrap-invalid", { bootstrap: unknown }>
+  | BootstrapFailedEnvelope
+  | PathEscapeEnvelope
+  | Envelope<"lifecycle", { reason: string }>
+>;
+
+export declare function createVerifyTool(deps: BaseToolDeps): (input: VerifyToolInput) => Promise<
+  | Envelope<"verify", { contractVersion: 1; commandId: string; status: 0; stdoutTail: string; stderrTail: string; headSha: Sha; manifestPath: string }>
+  | MissingManifestEnvelope
+  | ManifestStateEnvelope
+  | Envelope<"no-commands", Record<string, never>>
+  | Envelope<"command-not-found", { commandId: string }>
+  | Envelope<"worktree-dirty", Record<string, never>>
+  | Envelope<"no-head", Record<string, never>>
+  | VerifyFailedEnvelope
+  | Envelope<"lifecycle", { reason: string }>
+>;
+
+export declare function createReviewTool(deps: BaseToolDeps): (input: ReviewToolInput) => Promise<
+  | Envelope<"review", { contractVersion: 1; pr: PullRequestNumber; reviewerSha: Sha; manifestPath: string }>
+  | MissingManifestEnvelope
+  | MissingPrEnvelope
+  | ManifestStateEnvelope
+  | Envelope<"review-not-pass", { status: string; headSha: Sha; recordedReviewerSha: Sha | null }>
+  | HeadMismatchEnvelope
+>;
+
+export declare function createPrTool(deps: BaseToolDeps): (input: PrToolInput) => Promise<
+  | Envelope<"pr", { contractVersion: 1; pr: PullRequestSummary; manifestPath: string }>
+  | MissingManifestEnvelope
+  | ManifestStateEnvelope
+  | Envelope<"lifecycle", { reason: string }>
+>;
+
+export declare function createReadyTool(deps: BaseToolDeps): (input: ReadyToolInput) => Promise<
+  | Envelope<"ready", { contractVersion: 1; manifestPath: string; pr: PullRequestNumber }>
+  | MissingManifestEnvelope
+  | MissingPrEnvelope
+  | MissingGateEnvelope
+  | HeadChangedAfterReviewEnvelope
+  | HeadChangedAfterVerifierEnvelope
+  | Envelope<"ci-missing", { missing: readonly string[] }>
+  | Envelope<"ci-failing", { failing: readonly string[] }>
+  | Envelope<"ci-pending", { pending: readonly string[] }>
+>;
+
+export declare function createMergeTool(deps: BaseToolDeps): (input: MergeToolInput) => Promise<
+  | Envelope<"merge", { contractVersion: 1; manifestPath: string; pr: PullRequestNumber }>
+  | MissingManifestEnvelope
+  | MissingPrEnvelope
+  | NotReadyEnvelope
+  | WrongBaseEnvelope
+  | HeadChangedEnvelope
+  | NotMergeableEnvelope
+  | MissingGateEnvelope
+  | HeadChangedAfterReviewEnvelope
+  | HeadChangedAfterVerifierEnvelope
+  | Envelope<"ci-missing", { missing: readonly string[] }>
+  | Envelope<"ci-failing", { failing: readonly string[] }>
+  | Envelope<"ci-pending", { pending: readonly string[] }>
+>;
+
+export declare function createCleanupTool(deps: BaseToolDeps): (input: CleanupToolInput) => Promise<
+  | Envelope<"cleanup", { contractVersion: 1; manifestPath: string | null; removedPath: string }>
+  | MissingManifestEnvelope
+  | ManifestStateEnvelope
+  | MissingWorktreePathEnvelope
+  | MissingPrEnvelope
+  | CurrentCheckoutEnvelope
+  | DirtyWorktreeEnvelope
+  | RebaseInProgressEnvelope
+  | HeadMismatchEnvelope
+  | UnmergedEnvelope
+  | BaseMismatchEnvelope
+  | HasUnpublishedCommitsEnvelope
+  | RemoveFailedEnvelope
+  | Envelope<"branch-delete-failed", { stderr: string }>
+  | Envelope<"unsafe-cleanup", { signals: readonly string[] }>
+>;

package/dist/core.js

@@ -1,4 +1,4 @@
-// opencode-ship/core v1.1.4
+// opencode-ship/core v1.1.7
 
 // src/adapter.js
 import { readFile, writeFile, mkdir, rename } from "node:fs/promises";
@@ -851,7 +851,7 @@ function validateGhArgv(argv) {
 
 // src/drivers/gh-cli.js
 function defaultRunner(cwd, env) {
-  return (args) => new Promise((resolve9, reject) => {
+  return (args) => new Promise((resolve10, reject) => {
     const proc = spawn2("gh", args, {
       cwd,
       env,
@@ -863,7 +863,7 @@ function defaultRunner(cwd, env) {
     proc.stdout.on("data", (d) => stdout += d.toString());
     proc.stderr.on("data", (d) => stderr += d.toString());
     proc.on("error", reject);
-    proc.on("close", (status) => resolve9({ status: status ?? -1, stdout, stderr }));
+    proc.on("close", (status) => resolve10({ status: status ?? -1, stdout, stderr }));
   });
 }
 function viewFields() {
@@ -2527,6 +2527,42 @@ function createMergeTool(deps) {
     } else if (m.schemaVersion >= 2) {
       return { kind: "missing-workflow-link", taskId: m.taskId };
     }
+    if (pr.headSha !== (m.lastPrHeadSha ?? pr.headSha)) {
+      return {
+        kind: "head-changed",
+        headSha: pr.headSha,
+        manifestSha: m.lastPrHeadSha ?? ""
+      };
+    }
+    async function recordMerged(merged2, reason) {
+      const t = transition(
+        { ...m, lastPrHeadSha: merged2.headSha },
+        "merged",
+        { reason }
+      );
+      if (!t.ok) return { kind: "lifecycle", reason: t.reason };
+      const next = {
+        ...m,
+        lastPrHeadSha: merged2.headSha,
+        state: t.to,
+        transitionLog: [
+          ...m.transitionLog,
+          { from: t.from, to: t.to, at: t.at, reason: t.reason }
+        ],
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      const path = await writeManifest(deps.repoRoot, next);
+      if (finalEvidence && m.workflowId) {
+        await appendRunEvent(deps.repoRoot, m.workflowId, finalEvidence.runState, {
+          kind: RUN_EVENT_KINDS.MERGE,
+          data: { mergeSha: merged2.mergeSha ?? merged2.mergeCommitSha ?? merged2.headSha }
+        });
+      }
+      return { kind: "merge", contractVersion: 1, manifestPath: path, pr: m.prNumber, taskId: m.taskId };
+    }
+    if (pr.merged) {
+      return recordMerged(pr, `reconciled external merge as ${input.subject}`);
+    }
     if (freshGates) {
       const required = deps.adapter?.ready?.requires ?? [
         "review",
@@ -2553,13 +2589,6 @@ function createMergeTool(deps) {
       });
       if (!result.ok) return gateFailureEnvelope(result);
     }
-    if (pr.headSha !== (m.lastPrHeadSha ?? pr.headSha)) {
-      return {
-        kind: "head-changed",
-        headSha: pr.headSha,
-        manifestSha: m.lastPrHeadSha ?? ""
-      };
-    }
     if (pr.draft) return { kind: "not-mergeable", reason: "PR is still draft" };
     if (pr.mergeable !== "MERGEABLE") {
       return { kind: "not-mergeable", reason: `mergeable=${pr.mergeable}` };
@@ -2569,30 +2598,7 @@ function createMergeTool(deps) {
       number: m.prNumber,
       subject: input.subject
     });
-    const t = transition(
-      { ...m, lastPrHeadSha: merged.headSha },
-      "merged",
-      { reason: `squash merged as ${input.subject}` }
-    );
-    if (!t.ok) return { kind: "lifecycle", reason: t.reason };
-    const next = {
-      ...m,
-      lastPrHeadSha: merged.headSha,
-      state: t.to,
-      transitionLog: [
-        ...m.transitionLog,
-        { from: t.from, to: t.to, at: t.at, reason: t.reason }
-      ],
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    const path = await writeManifest(deps.repoRoot, next);
-    if (finalEvidence && m.workflowId) {
-      await appendRunEvent(deps.repoRoot, m.workflowId, finalEvidence.runState, {
-        kind: RUN_EVENT_KINDS.MERGE,
-        data: { mergeSha: merged.mergeSha ?? merged.mergeCommitSha ?? merged.headSha }
-      });
-    }
-    return { kind: "merge", contractVersion: 1, manifestPath: path, pr: m.prNumber, taskId: m.taskId };
+    return recordMerged(merged, `squash merged as ${input.subject}`);
   };
 }
 
@@ -2769,8 +2775,12 @@ function createCleanupTool(deps) {
   };
 }
 
-// src/index.js
-var PACKAGE_VERSION = "0.1.3";
+// src/version.js
+import { readFileSync, existsSync as existsSync7 } from "node:fs";
+import { dirname as dirname3, resolve as resolve9 } from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGE_VERSION = "1.1.7";
+var TEMPLATE_SET = `v${PACKAGE_VERSION}`;
 export {
   ADAPTER_CONTRACT_VERSION,
   ADAPTER_FILENAME,

package/dist/plugin.js

@@ -1,4 +1,4 @@
-// opencode-ship v1.1.4
+// opencode-ship v1.1.7
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __esm = (fn, res) => function __init() {
@@ -14925,6 +14925,42 @@ function createMergeTool(deps) {
     } else if (m.schemaVersion >= 2) {
       return { kind: "missing-workflow-link", taskId: m.taskId };
     }
+    if (pr.headSha !== (m.lastPrHeadSha ?? pr.headSha)) {
+      return {
+        kind: "head-changed",
+        headSha: pr.headSha,
+        manifestSha: m.lastPrHeadSha ?? ""
+      };
+    }
+    async function recordMerged(merged2, reason) {
+      const t = transition(
+        { ...m, lastPrHeadSha: merged2.headSha },
+        "merged",
+        { reason }
+      );
+      if (!t.ok) return { kind: "lifecycle", reason: t.reason };
+      const next = {
+        ...m,
+        lastPrHeadSha: merged2.headSha,
+        state: t.to,
+        transitionLog: [
+          ...m.transitionLog,
+          { from: t.from, to: t.to, at: t.at, reason: t.reason }
+        ],
+        updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      const path = await writeManifest(deps.repoRoot, next);
+      if (finalEvidence && m.workflowId) {
+        await appendRunEvent(deps.repoRoot, m.workflowId, finalEvidence.runState, {
+          kind: RUN_EVENT_KINDS.MERGE,
+          data: { mergeSha: merged2.mergeSha ?? merged2.mergeCommitSha ?? merged2.headSha }
+        });
+      }
+      return { kind: "merge", contractVersion: 1, manifestPath: path, pr: m.prNumber, taskId: m.taskId };
+    }
+    if (pr.merged) {
+      return recordMerged(pr, `reconciled external merge as ${input.subject}`);
+    }
     if (freshGates) {
       const required2 = deps.adapter?.ready?.requires ?? [
         "review",
@@ -14951,13 +14987,6 @@ function createMergeTool(deps) {
       });
       if (!result.ok) return gateFailureEnvelope(result);
     }
-    if (pr.headSha !== (m.lastPrHeadSha ?? pr.headSha)) {
-      return {
-        kind: "head-changed",
-        headSha: pr.headSha,
-        manifestSha: m.lastPrHeadSha ?? ""
-      };
-    }
     if (pr.draft) return { kind: "not-mergeable", reason: "PR is still draft" };
     if (pr.mergeable !== "MERGEABLE") {
       return { kind: "not-mergeable", reason: `mergeable=${pr.mergeable}` };
@@ -14967,30 +14996,7 @@ function createMergeTool(deps) {
       number: m.prNumber,
       subject: input.subject
     });
-    const t = transition(
-      { ...m, lastPrHeadSha: merged.headSha },
-      "merged",
-      { reason: `squash merged as ${input.subject}` }
-    );
-    if (!t.ok) return { kind: "lifecycle", reason: t.reason };
-    const next = {
-      ...m,
-      lastPrHeadSha: merged.headSha,
-      state: t.to,
-      transitionLog: [
-        ...m.transitionLog,
-        { from: t.from, to: t.to, at: t.at, reason: t.reason }
-      ],
-      updatedAt: (/* @__PURE__ */ new Date()).toISOString()
-    };
-    const path = await writeManifest(deps.repoRoot, next);
-    if (finalEvidence && m.workflowId) {
-      await appendRunEvent(deps.repoRoot, m.workflowId, finalEvidence.runState, {
-        kind: RUN_EVENT_KINDS.MERGE,
-        data: { mergeSha: merged.mergeSha ?? merged.mergeCommitSha ?? merged.headSha }
-      });
-    }
-    return { kind: "merge", contractVersion: 1, manifestPath: path, pr: m.prNumber, taskId: m.taskId };
+    return recordMerged(merged, `squash merged as ${input.subject}`);
   };
 }
 
@@ -19158,13 +19164,11 @@ function spawn8(repoRoot, args) {
   return { status: r.status ?? -1, stdout: r.stdout ?? "", stderr: r.stderr ?? "" };
 }
 function casDeleteBranch2(repoRoot, branch, expectedSha) {
-  const argv = ["update-ref", "-d"];
-  if (expectedSha && /^[0-9f]{7,}$/i.test(expectedSha)) {
-    argv.push(`refs/heads/${branch}`, expectedSha);
-  } else {
-    argv.push(`refs/heads/${branch}`);
-  }
-  return spawn8(repoRoot, argv).status ?? -1;
+  if (!isValidExpectedSha(expectedSha)) return -1;
+  return spawn8(repoRoot, ["update-ref", "-d", `refs/heads/${branch}`, expectedSha]).status ?? -1;
+}
+function isValidExpectedSha(value) {
+  return typeof value === "string" && /^[0-9a-f]{7,}$/i.test(value);
 }
 function safeRemoveWorktree2(repoRoot, target) {
   const r = spawn8(repoRoot, ["worktree", "remove", target]);
@@ -19195,15 +19199,12 @@ async function saveCleanupPending(repoRoot, entries) {
   writeFileSync2(path, JSON.stringify(dedupePending(entries), null, 2) + "\n", "utf8");
 }
 function dedupePending(entries) {
-  const seen = /* @__PURE__ */ new Set();
-  const out = [];
+  const byTask = /* @__PURE__ */ new Map();
   for (const e of entries) {
     if (!e || !e.taskId) continue;
-    if (seen.has(e.taskId)) continue;
-    seen.add(e.taskId);
-    out.push(e);
+    byTask.set(e.taskId, e);
   }
-  return out;
+  return [...byTask.values()];
 }
 async function appendCleanupPending(repoRoot, entry) {
   const current = await loadCleanupPending(repoRoot);
@@ -19211,13 +19212,28 @@ async function appendCleanupPending(repoRoot, entry) {
   await saveCleanupPending(repoRoot, next);
   return next;
 }
+async function clearCleanupPending(repoRoot, taskId) {
+  const current = await loadCleanupPending(repoRoot);
+  await saveCleanupPending(repoRoot, current.filter((entry) => entry.taskId !== taskId));
+}
 function reject(reason, extra = {}) {
   return { ok: false, reason, ...extra };
 }
 async function tryImmediateCleanup({ repoRoot, taskId, adapter }) {
   if (!repoRoot || !taskId) return reject("missing-args");
+  const pending = (await loadCleanupPending(repoRoot)).find((entry) => entry.taskId === taskId);
+  const stage = pending?.stage ?? "worktree-remove";
+  if (!["worktree-remove", "branch-delete", "manifest-seal"].includes(stage)) {
+    return reject("cleanup-stage", { stage });
+  }
   const m = await readManifest(repoRoot, taskId);
-  if (!m) return reject("missing-manifest");
+  if (!m) {
+    if (pending && stage === "manifest-seal") {
+      await clearCleanupPending(repoRoot, taskId);
+      return { ok: true, removedPath: null, sealed: true };
+    }
+    return reject("missing-manifest");
+  }
   if (m.state !== "merged" && m.state !== "cleanup-pending") {
     return reject("manifest-state", { state: m.state });
   }
@@ -19229,36 +19245,68 @@ async function tryImmediateCleanup({ repoRoot, taskId, adapter }) {
   if (!wtPath.startsWith(rootAbs + "/")) {
     return reject("worktree-out-of-root", { expected: rootAbs, got: wtPath });
   }
-  const status = spawn8(wtPath, ["status", "--porcelain"]);
-  if (status.status === 0 && status.stdout.trim().length > 0) return reject("dirty-worktree");
-  const rebase = spawn8(wtPath, ["rev-parse", "--verify", "--quiet", "REBASE_HEAD"]);
-  if (rebase.status === 0) return reject("rebase-in-progress");
-  const head = spawn8(wtPath, ["rev-parse", "HEAD"]);
-  if (head.status !== 0) return reject("no-head");
-  const headSha = head.stdout.trim();
-  if (m.lastPrHeadSha && headSha !== m.lastPrHeadSha) {
-    return reject("head-mismatch", { expected: m.lastPrHeadSha, actual: headSha });
-  }
-  const removed = safeRemoveWorktree2(repoRoot, wtPath);
-  if (removed.status !== 0) {
+  let headSha = isValidExpectedSha(pending?.expectedHeadSha) ? pending.expectedHeadSha : isValidExpectedSha(m.lastPrHeadSha) ? m.lastPrHeadSha : "";
+  if (stage === "worktree-remove") {
+    const status = spawn8(wtPath, ["status", "--porcelain"]);
+    if (status.status === 0) {
+      if (status.stdout.trim().length > 0) return reject("dirty-worktree");
+      const rebase = spawn8(wtPath, ["rev-parse", "--verify", "--quiet", "REBASE_HEAD"]);
+      if (rebase.status === 0) return reject("rebase-in-progress");
+      const head = spawn8(wtPath, ["rev-parse", "HEAD"]);
+      if (head.status !== 0) return reject("no-head");
+      headSha = head.stdout.trim();
+      if (m.lastPrHeadSha && headSha !== m.lastPrHeadSha) {
+        return reject("head-mismatch", { expected: m.lastPrHeadSha, actual: headSha });
+      }
+      await appendCleanupPending(repoRoot, {
+        taskId,
+        failedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        stage: "worktree-remove",
+        expectedHeadSha: headSha,
+        reason: "worktree head validated"
+      });
+      const removed = safeRemoveWorktree2(repoRoot, wtPath);
+      if (removed.status !== 0) {
+        await appendCleanupPending(repoRoot, {
+          taskId,
+          failedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          stage: "worktree-remove",
+          expectedHeadSha: headSha,
+          reason: removed.stderr ?? "non-zero exit"
+        });
+        return reject("remove-failed", { detail: removed.stderr });
+      }
+    } else if (!headSha) {
+      return reject("no-head");
+    }
     await appendCleanupPending(repoRoot, {
       taskId,
       failedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      stage: "worktree-remove",
-      reason: removed.stderr ?? "non-zero exit"
+      stage: "branch-delete",
+      expectedHeadSha: headSha,
+      reason: "resume cleanup"
     });
-    return reject("remove-failed", { detail: removed.stderr });
   }
-  const branchDelete = casDeleteBranch2(repoRoot, m.branch, headSha);
-  const branchStillThere = spawn8(repoRoot, ["show-ref", "--verify", "--quiet", `refs/heads/${m.branch}`]);
-  if (branchDelete !== 0 && branchStillThere.status === 0) {
+  if (stage !== "manifest-seal") {
+    if (!isValidExpectedSha(headSha)) return reject("no-head");
+    const branchDelete = casDeleteBranch2(repoRoot, m.branch, headSha);
+    const branchStillThere = spawn8(repoRoot, ["show-ref", "--verify", "--quiet", `refs/heads/${m.branch}`]);
+    if (branchDelete !== 0 && branchStillThere.status === 0) {
+      await appendCleanupPending(repoRoot, {
+        taskId,
+        failedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        stage: "branch-delete",
+        expectedHeadSha: headSha,
+        reason: "git update-ref failed"
+      });
+      return reject("branch-delete-failed");
+    }
     await appendCleanupPending(repoRoot, {
       taskId,
       failedAt: (/* @__PURE__ */ new Date()).toISOString(),
-      stage: "branch-delete",
-      reason: "git update-ref failed"
+      stage: "manifest-seal",
+      reason: "resume cleanup"
     });
-    return reject("branch-delete-failed");
   }
   const next = {
     ...m,
@@ -19271,11 +19319,18 @@ async function tryImmediateCleanup({ repoRoot, taskId, adapter }) {
   };
   await writeManifest(repoRoot, next).catch(() => null);
   await deleteManifest(repoRoot, taskId);
+  await clearCleanupPending(repoRoot, taskId);
   return { ok: true, removedPath: wtPath, sealed: true };
 }
 async function listPending(repoRoot) {
   const all = await listManifests(repoRoot).catch(() => []);
-  return all.filter((m) => m.state === "merged" || m.state === "cleanup-pending");
+  const manifests = all.filter((m) => m.state === "merged" || m.state === "cleanup-pending");
+  const queued = await loadCleanupPending(repoRoot);
+  const byTask = new Map(manifests.map((manifest) => [manifest.taskId, manifest]));
+  for (const entry of queued) {
+    if (!byTask.has(entry.taskId)) byTask.set(entry.taskId, entry);
+  }
+  return [...byTask.values()];
 }
 
 // src/installer/ship-adapter.js
@@ -19328,7 +19383,7 @@ function selectRuntimeAdapter({ config: config2, shipAdapter, legacyAdapter }) {
 import { readFileSync as readFileSync4, existsSync as existsSync27 } from "node:fs";
 import { dirname as dirname12, resolve as resolve21 } from "node:path";
 import { fileURLToPath } from "node:url";
-var PACKAGE_VERSION = "1.1.4";
+var PACKAGE_VERSION = "1.1.7";
 var TEMPLATE_SET = `v${PACKAGE_VERSION}`;
 
 // src/plugin.js

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-ship",
-  "version": "1.1.4",
+  "version": "1.1.7",
   "private": false,
   "description": "npm-distributed OpenCode installer that materializes the delivery plugin, reviewer/verifier agents, skills, ship config and lock into any consumer repository.",
   "license": "MIT",
@@ -32,6 +32,7 @@
       "import": "./dist/plugin.js"
     },
     "./core": {
+      "types": "./dist/core.d.ts",
       "import": "./dist/core.js"
     },
     "./schema/project-adapter.schema.json": "./schema/project-adapter.schema.json",