@savvy-web/silk-effects 5.4.0 → 5.5.0

package/README.md

@@ -13,7 +13,7 @@ Shared [Effect](https://effect.website/) library providing Silk Suite convention
 - Supply the Silk commitlint config, its prompt and formatter, and the `silk/body-no-markdown` rule
 - Run the lint-staged handlers and the `savvy lint fmt` formatters from a single implementation so the hook and the CLI cannot drift
 - Inspect a Turborepo read-only — diagnose per-package cache hits, derive the task graph and compute affected packages, all over `turbo --dry`
-- Manage the vendored reference repos declared in `.repos/config.json` — submodule status, sync, pinning and notes — and keep every vendored tree read-only between mutations
+- Manage the vendored reference repos declared in `.repos/config.json` — submodule status, drift detection, sync, add, pin, note, remove, rename and restore — and keep every vendored tree read-only between mutations
 - Locate config files and keep Biome schema URLs in sync across workspaces
 
 ## Install
@@ -364,13 +364,13 @@ const diagnosis = await Effect.runPromise(
 // => CacheDiagnosis: per-package HIT/MISS breakdown for the task
 ```
 
-#### ReposManager and ReposLockdown
+#### ReposManager, ReposDrift and ReposLockdown
 
-The `Repos` namespace drives vendored reference repos — upstream sources checked out as git submodules under `.repos/`, declared in a `.repos/config.json` manifest. `ReposConfigStore` reads and writes that manifest, and `ReposManager` does the git work: `status(root)` reports presence, the pinned commit, working-tree dirtiness and stale notes, `sync(root)` initializes missing submodules and applies each entry's sparse-checkout, `pin(root, name, ref)` moves an entry to a new ref, `add(root, options)` vendors a new one, and `note(root, name, op)` adds, removes or promotes an agent note.
+The `Repos` namespace drives vendored reference repos — upstream sources checked out as git submodules under `.repos/`, declared in a `.repos/config.json` manifest. `ReposConfigStore` reads and writes that manifest, and `ReposManager` does the git work: `status(root)` reports presence, the pinned commit, working-tree dirtiness and stale notes, `sync(root)` initializes missing submodules and applies each entry's sparse-checkout, `pin(root, name, ref)` moves an entry to a new ref, `add(root, options)` vendors a new one, `note(root, name, op)` adds, removes or promotes an agent note, `remove(root, name)` unvendors an entry, `rename(root, oldName, newName)` renames one in place, and `restore(root, names?)` hard-resets one or more dirty checkouts back to their pinned commit. `ReposDrift.check(root)` is a read-only companion — it reconciles the manifest, `.gitmodules`, the worktree, and `git submodule status`, reporting any mismatch as a typed drift kind.
 
-`ReposLockdown` is the permissions boundary around all of that. `lock(root, name)` chmods a vendored worktree and its submodule git metadata to files `0444` and directories `0555`; `unlock` reverses it; `withUnlocked(root, name, effect)` brackets an effect between the two. `ReposManager`'s `sync`, `add` and `pin` run their git mutations inside that bracket and re-lock afterwards, so a vendored tree is read-only whenever the manager is not mid-write. Reads are unaffected — a locked tree needs no special handling to open a file.
+`ReposLockdown` is the permissions boundary around all of that. `lock(root, name)` chmods a vendored worktree and its submodule git metadata to files `0444` and directories `0555` (an executable file locks at `0555` instead, preserving its executable bit); `unlock` reverses it, restoring `0644`/`0755` (`0755` for a file that was executable); `withUnlocked(root, name, effect)` brackets an effect between the two. `ReposManager`'s `sync`, `add`, `pin`, `remove` and `restore` run their git mutations inside that bracket and re-lock afterwards, and `rename` hand-rolls the same unlock/relock contract across its `oldName`→`newName` move, so a vendored tree is read-only whenever the manager is not mid-write. Reads are unaffected — a locked tree needs no special handling to open a file.
 
-Two consequences for callers: `ReposManager.layer` now requires `ReposLockdown` alongside `ReposConfigStore`, `Git`, `FileSystem` and `Path`, and `sync`, `add` and `pin` widen their error channel with `ReposLockdownError`, which carries the offending `path` and a `reason`.
+Two consequences for callers: `ReposManager.layer` requires `ReposLockdown` alongside `ReposConfigStore`, `Git`, `FileSystem` and `Path`, and `sync`, `add`, `pin`, `remove`, `rename` and `restore` widen their error channel with `ReposLockdownError`, which carries the offending `path` and a `reason`.
 
 ```typescript
 import { Effect, Layer } from "effect";

package/index.d.ts

@@ -8296,6 +8296,46 @@ declare class ReposLockdownError extends ReposLockdownErrorBase<{
   get message(): string;
 }
 //#endregion
+//#region src/repos/schemas/drift.d.ts
+/**
+ * The kinds of drift {@link ReposDrift} can detect between the four
+ * authorities it reconciles: the manifest, `.gitmodules`, the worktree, and
+ * `git submodule status`.
+ * @public
+ */
+declare const DriftKind: Schema.Literals<readonly ["urlMismatch", "pathMismatch", "unregisteredManifestEntry", "orphanGitmodulesEntry", "missingWorktree", "checkoutDiverged", "missingShallow", "gitmodulesUnparsable"]>;
+/** @public */
+type DriftKind = typeof DriftKind.Type;
+declare const RepoDrift_base: Schema.Class<RepoDrift, Schema.Struct<{
+  readonly name: Schema.String;
+  readonly kind: Schema.Literals<readonly ["urlMismatch", "pathMismatch", "unregisteredManifestEntry", "orphanGitmodulesEntry", "missingWorktree", "checkoutDiverged", "missingShallow", "gitmodulesUnparsable"]>;
+  readonly detail: Schema.String;
+  readonly manifestValue: Schema.optionalKey<Schema.String>;
+  readonly observedValue: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * One detected disagreement between two (or more) of the four authorities
+ * for a single vendored repo.
+ *
+ * @remarks
+ * `manifestValue`/`observedValue` carry the two disagreeing values when the
+ * drift is a value mismatch (`urlMismatch`, `pathMismatch`); other kinds
+ * populate whichever side has a value to show (or neither, for
+ * `gitmodulesUnparsable`, which is not about one repo).
+ * @public
+ */
+declare class RepoDrift extends RepoDrift_base {}
+declare const ReposDriftReport_base: Schema.Class<ReposDriftReport, Schema.Struct<{
+  readonly drifts: Schema.$Array<typeof RepoDrift>;
+  readonly clean: Schema.Boolean;
+}>, {}>;
+/**
+ * The result of reconciling the manifest, `.gitmodules`, the worktree, and
+ * `git submodule status` for every vendored repo.
+ * @public
+ */
+declare class ReposDriftReport extends ReposDriftReport_base {}
+//#endregion
 //#region src/repos/schemas/manifest.d.ts
 /**
  * A vendored-repo manifest key: non-empty, contains no `/` or `\`, and is
@@ -8382,6 +8422,21 @@ type ReposManifestFile = typeof ReposManifestFile.Type;
 /**
  * Status of one vendored repo: gitlink presence and dirtiness, plus notes
  * that no longer match the pinned ref.
+ *
+ * @remarks
+ * `commit` is an alias of `stagedCommit`, retained for one release so an
+ * existing consumer reading `entry.commit` keeps working while it migrates to
+ * the index-aware triple. It carries no independent release tag beyond
+ * `@public` (this schema has no narrower audience to gate it behind).
+ * Removal is scheduled by a tracked issue, not gated on a renderer migration
+ * precondition here.
+ *
+ * Not fully behavior-preserving: `commit: stagedCommit ?? null` reads `null`
+ * for a gitlink committed at `HEAD` but staged for REMOVAL, where the prior
+ * single-`commit` field showed the committed oid. `stagedCommit` is `None`
+ * in exactly that case (nothing is staged), so the alias reports "nothing
+ * staged" rather than "here is what HEAD still has" — a real, if narrow,
+ * difference from the pre-triple `commit` field's behavior.
  * @public
  */
 declare const RepoStatusEntry: Schema.Struct<{
@@ -8389,7 +8444,14 @@ declare const RepoStatusEntry: Schema.Struct<{
   readonly ref: Schema.String;
   readonly purpose: Schema.String;
   readonly present: Schema.Boolean;
+  /** @deprecated alias of `stagedCommit`; retained for one release. */
   readonly commit: Schema.NullOr<Schema.String>;
+  /** The gitlink oid staged in the index (`git ls-files --stage`) — sees a pin BEFORE it is committed. */
+  readonly stagedCommit: Schema.optionalKey<Schema.String>;
+  /** The gitlink oid committed at `HEAD` (`git ls-tree HEAD`). */
+  readonly committedCommit: Schema.optionalKey<Schema.String>;
+  /** The commit actually checked out in the submodule worktree (`git rev-parse HEAD` inside it); absent when there is no checkout. */
+  readonly checkedOutCommit: Schema.optionalKey<Schema.String>;
   readonly dirty: Schema.Boolean;
   readonly staleNoteIds: Schema.$Array<Schema.String>;
 }>;
@@ -8405,7 +8467,14 @@ declare const ReposStatusReport: Schema.Struct<{
     readonly ref: Schema.String;
     readonly purpose: Schema.String;
     readonly present: Schema.Boolean;
+    /** @deprecated alias of `stagedCommit`; retained for one release. */
     readonly commit: Schema.NullOr<Schema.String>;
+    /** The gitlink oid staged in the index (`git ls-files --stage`) — sees a pin BEFORE it is committed. */
+    readonly stagedCommit: Schema.optionalKey<Schema.String>;
+    /** The gitlink oid committed at `HEAD` (`git ls-tree HEAD`). */
+    readonly committedCommit: Schema.optionalKey<Schema.String>;
+    /** The commit actually checked out in the submodule worktree (`git rev-parse HEAD` inside it); absent when there is no checkout. */
+    readonly checkedOutCommit: Schema.optionalKey<Schema.String>;
     readonly dirty: Schema.Boolean;
     readonly staleNoteIds: Schema.$Array<Schema.String>;
   }>>;
@@ -8416,7 +8485,8 @@ type ReposStatusReport = typeof ReposStatusReport.Type;
 /**
  * Result of reconciling working-tree submodules with the manifest: missing
  * repos initialized, sparse-checkout patterns re-applied, already-present
- * repos left alone, and stale locks cleared.
+ * repos left alone, stale locks cleared, drifted submodule URLs reconciled,
+ * and orphan manifest entries (no gitlink at all) registered.
  * @public
  */
 declare const ReposSyncReport: Schema.Struct<{
@@ -8424,6 +8494,8 @@ declare const ReposSyncReport: Schema.Struct<{
   readonly sparseApplied: Schema.$Array<Schema.String>;
   readonly upToDate: Schema.$Array<Schema.String>;
   readonly clearedLocks: Schema.$Array<Schema.String>;
+  readonly urlSynced: Schema.$Array<Schema.String>;
+  readonly registered: Schema.$Array<Schema.String>;
 }>;
 /** @public */
 type ReposSyncReport = typeof ReposSyncReport.Type;
@@ -8452,6 +8524,62 @@ declare const ReposAddResult: Schema.Struct<{
 }>;
 /** @public */
 type ReposAddResult = typeof ReposAddResult.Type;
+/**
+ * Result of removing a vendored repo from the manifest: the gitlink, module
+ * gitdir, and `.gitmodules` section are all gone, and the entry's notes are
+ * surfaced so any durable ones can be promoted elsewhere before this result
+ * is committed.
+ * @public
+ */
+declare const ReposRemoveResult: Schema.Struct<{
+  readonly name: Schema.String;
+  readonly path: Schema.String;
+  readonly commitMessage: Schema.String;
+  readonly removedNotes: Schema.$Array<Schema.Struct<{
+    readonly id: Schema.String;
+    readonly date: Schema.String;
+    readonly ref: Schema.String;
+    readonly note: Schema.String;
+  }>>;
+}>;
+/** @public */
+type ReposRemoveResult = typeof ReposRemoveResult.Type;
+/**
+ * Result of renaming a vendored repo's manifest key: the `.repos/<name>`
+ * worktree moved, the module gitdir's `core.worktree` values re-pointed, the
+ * `.gitmodules` section canonicalized to the new name, and the manifest key
+ * renamed.
+ * @public
+ */
+declare const ReposRenameResult: Schema.Struct<{
+  readonly oldName: Schema.String;
+  readonly newName: Schema.String;
+  readonly path: Schema.String;
+  readonly commitMessage: Schema.String;
+}>;
+/** @public */
+type ReposRenameResult = typeof ReposRenameResult.Type;
+/**
+ * Result of hard-resetting one or more vendored repos to their staged (or
+ * committed) gitlink commit and re-applying sparse-checkout paths.
+ *
+ * @remarks
+ * `restored` lists every repo actually reset, paired with the commit it was
+ * reset to. `skippedClean` is populated ONLY by the names-omitted form of
+ * {@link ReposManagerShape.restore} — repos left untouched because `status`
+ * reported them clean; an explicit-names call never skips anything (an
+ * explicit ask is always honored), so it always reports an empty array.
+ * @public
+ */
+declare const ReposRestoreResult: Schema.Struct<{
+  readonly restored: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly commit: Schema.String;
+  }>>;
+  readonly skippedClean: Schema.$Array<Schema.String>;
+}>;
+/** @public */
+type ReposRestoreResult = typeof ReposRestoreResult.Type;
 /**
  * Result of an agent-note mutation against a vendored repo.
  * @public
@@ -8474,6 +8602,14 @@ interface ReposConfigStoreShape {
   readonly exists: (root: string) => Effect.Effect<boolean>;
   readonly read: (root: string) => Effect.Effect<ReposManifestFile, ReposConfigError>;
   readonly write: (root: string, manifest: ReposManifestFile) => Effect.Effect<void, ReposConfigError>;
+  /**
+   * Serialized read-modify-write: acquires an exclusive-create lock file
+   * beside the manifest, reads the current manifest (an absent manifest is
+   * passed to `fn` as `{ repos: {} }` — `update` can initialize), runs `fn`,
+   * writes the result, and always releases the lock. Concurrent callers
+   * queue behind the lock rather than racing a lost update.
+   */
+  readonly update: (root: string, fn: (manifest: ReposManifestFile) => ReposManifestFile | Effect.Effect<ReposManifestFile, ReposConfigError>) => Effect.Effect<ReposManifestFile, ReposConfigError>;
 }
 declare const ReposConfigStore_base: Context.ServiceClass<ReposConfigStore, "@savvy-web/silk-effects/ReposConfigStore", ReposConfigStoreShape>;
 /**
@@ -8488,6 +8624,31 @@ declare class ReposConfigStore extends ReposConfigStore_base {
   static readonly layer: Layer.Layer<ReposConfigStore, never, FileSystem.FileSystem | Path.Path>;
 }
 //#endregion
+//#region src/repos/services/drift.d.ts
+/**
+ * The {@link ReposDrift} service shape.
+ * @public
+ */
+interface ReposDriftShape {
+  readonly check: (root: string) => Effect.Effect<ReposDriftReport, ReposConfigError | GitSubmoduleError>;
+}
+declare const ReposDrift_base: Context.ServiceClass<ReposDrift, "@savvy-web/silk-effects/ReposDrift", ReposDriftShape>;
+/**
+ * Reconciles the four authorities a vendored repo's state is spread across —
+ * the manifest, `.gitmodules`, the worktree, and `git submodule status` —
+ * and reports every disagreement found. Read-only: no staging, no lockdown
+ * interaction, so it runs unmodified against a locked (`ReposLockdown`)
+ * tree.
+ * @public
+ */
+declare class ReposDrift extends ReposDrift_base {
+  /**
+   * Production implementation of {@link ReposDrift}.
+   * @public
+   */
+  static readonly layer: Layer.Layer<ReposDrift, never, ReposConfigStore | Git | FileSystem.FileSystem | Path.Path>;
+}
+//#endregion
 //#region src/repos/services/lockdown.d.ts
 /**
  * The {@link ReposLockdown} service shape.
@@ -8578,13 +8739,36 @@ interface ReposManagerShape {
     readonly id: string;
     readonly into: "layout" | "startHere";
   }) => Effect.Effect<ReposNoteResult, ReposConfigError | RepoNotFoundError | NoteNotFoundError>;
+  readonly remove: (root: string, name: string) => Effect.Effect<ReposRemoveResult, ReposConfigError | GitSubmoduleError | RepoNotFoundError | ReposLockdownError>;
+  /**
+   * Crash contract: unlike {@link add}, `rename` has no compensating
+   * rollback. `Effect.uninterruptibleMask` guards fiber interruption, not a
+   * hard process kill, so a `kill -9` between `git mv` and the manifest
+   * write can leave the tree renamed in git, the manifest still holding
+   * the old key, and the tree unlocked (the relock finalizer never runs).
+   * This is a deliberate asymmetry with `add`, which DOES roll back —
+   * `rename` does not, because unlike a fresh vendor there is no "nothing
+   * happened yet" state to unwind back to.
+   *
+   * Recovery is NOT a guaranteed clean "just run it again": `git mv` is not
+   * idempotent (a real-git probe confirms a second `git mv <old> <new>`
+   * after the first already succeeded fails with "bad source"), so a crash
+   * after `git mv` lands makes the next `rename` call fail at that same
+   * step rather than resume past it. A crash in that window needs manual
+   * inspection (`git status`, `.repos/config.json`, `.gitmodules`) before
+   * retrying, not a blind re-invocation.
+   */
+  readonly rename: (root: string, oldName: string, newName: string) => Effect.Effect<ReposRenameResult, ReposConfigError | GitSubmoduleError | RepoNotFoundError | ReposLockdownError>;
+  readonly restore: (root: string, names?: ReadonlyArray<string>) => Effect.Effect<ReposRestoreResult, ReposConfigError | GitSubmoduleError | RepoNotFoundError | ReposLockdownError>;
 }
 declare const ReposManager_base: Context.ServiceClass<ReposManager, "@savvy-web/silk-effects/ReposManager", ReposManagerShape>;
 /**
  * Drives the vendored `.repos/` submodules over git: reports status
  * (presence, dirtiness, stale notes), reconciles the working tree with the
  * manifest, vendors new entries (`add`), re-pins existing entries to a new
- * ref (`pin`), and adds, removes, or promotes agent notes (`note`).
+ * ref (`pin`), adds/removes/promotes agent notes (`note`), unvendors
+ * (`remove`), renames (`rename`), and explicitly hard-resets dirty
+ * checkouts back to their pinned commit (`restore`).
  * @public
  */
 declare class ReposManager extends ReposManager_base {
@@ -8602,7 +8786,7 @@ declare class ReposManager extends ReposManager_base {
   static readonly layer: Layer.Layer<ReposManager, never, ReposConfigStore | Git | FileSystem.FileSystem | Path.Path | ReposLockdown>;
 }
 declare namespace index_d_exports$3 {
-  export { GitSubmoduleError, GitSubmoduleErrorBase, MANIFEST_PATH, NOTE_LIMIT, NoteNotFoundError, NoteNotFoundErrorBase, REPOS_DIR, RepoEntry, RepoName, RepoNotFoundError, RepoNotFoundErrorBase, RepoNote, RepoOrientation, RepoStatusEntry, ReposAddResult, ReposConfigError, ReposConfigErrorBase, ReposConfigStore, ReposConfigStoreShape, ReposLockdown, ReposLockdownError, ReposLockdownErrorBase, ReposLockdownShape, ReposManager, ReposManagerShape, ReposManifestFile, ReposNoteResult, ReposPinResult, ReposStatusReport, ReposSyncReport, STALE_LOCK_MAX_AGE_MS, resolveModuleDir };
+  export { DriftKind, GitSubmoduleError, GitSubmoduleErrorBase, MANIFEST_PATH, NOTE_LIMIT, NoteNotFoundError, NoteNotFoundErrorBase, REPOS_DIR, RepoDrift, RepoEntry, RepoName, RepoNotFoundError, RepoNotFoundErrorBase, RepoNote, RepoOrientation, RepoStatusEntry, ReposAddResult, ReposConfigError, ReposConfigErrorBase, ReposConfigStore, ReposConfigStoreShape, ReposDrift, ReposDriftReport, ReposDriftShape, ReposLockdown, ReposLockdownError, ReposLockdownErrorBase, ReposLockdownShape, ReposManager, ReposManagerShape, ReposManifestFile, ReposNoteResult, ReposPinResult, ReposRemoveResult, ReposRenameResult, ReposRestoreResult, ReposStatusReport, ReposSyncReport, STALE_LOCK_MAX_AGE_MS, resolveModuleDir };
 }
 //#endregion
 //#region src/schemas/BiomeConfig.d.ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/silk-effects",
-	"version": "5.4.0",
+	"version": "5.5.0",
 	"private": false,
 	"description": "Shared Effect library for Silk Suite conventions",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/silk-effects",
@@ -34,13 +34,13 @@
 		"@changesets/get-github-info": "^1.0.0-next.4",
 		"@changesets/get-release-plan": "^5.0.0-next.9",
 		"@effected/commands": "^0.3.1",
-		"@effected/git": "^0.5.2",
+		"@effected/git": "^0.6.0",
 		"@effected/glob": "^0.2.2",
 		"@effected/jsonc": "^0.5.2",
 		"@effected/package-json": "^0.7.3",
 		"@effected/templates": "^0.1.1",
 		"@effected/walker": "^0.3.4",
-		"@effected/workspaces": "^0.10.0",
+		"@effected/workspaces": "^0.10.2",
 		"@effected/yaml": "^0.6.1",
 		"@manypkg/get-packages": "^3.1.0",
 		"mdast-util-heading-range": "^4.0.0",

package/repos/index.js

@@ -1,14 +1,17 @@
 import { __exportAll } from "../_virtual/_rolldown/runtime.js";
 import { MANIFEST_PATH, REPOS_DIR } from "./constants.js";
 import { GitSubmoduleError, GitSubmoduleErrorBase, NoteNotFoundError, NoteNotFoundErrorBase, RepoNotFoundError, RepoNotFoundErrorBase, ReposConfigError, ReposConfigErrorBase, ReposLockdownError, ReposLockdownErrorBase } from "./errors.js";
+import { DriftKind, RepoDrift, ReposDriftReport } from "./schemas/drift.js";
 import { RepoEntry, RepoName, RepoNote, RepoOrientation, ReposManifestFile } from "./schemas/manifest.js";
-import { RepoStatusEntry, ReposAddResult, ReposNoteResult, ReposPinResult, ReposStatusReport, ReposSyncReport } from "./schemas/reports.js";
+import { RepoStatusEntry, ReposAddResult, ReposNoteResult, ReposPinResult, ReposRemoveResult, ReposRenameResult, ReposRestoreResult, ReposStatusReport, ReposSyncReport } from "./schemas/reports.js";
 import { ReposConfigStore } from "./services/config-store.js";
+import { ReposDrift } from "./services/drift.js";
 import { ReposLockdown, resolveModuleDir } from "./services/lockdown.js";
 import { ReposManager, STALE_LOCK_MAX_AGE_MS } from "./services/manager.js";
 
 //#region src/repos/index.ts
 var repos_exports = /* @__PURE__ */ __exportAll({
+	DriftKind: () => DriftKind,
 	GitSubmoduleError: () => GitSubmoduleError,
 	GitSubmoduleErrorBase: () => GitSubmoduleErrorBase,
 	MANIFEST_PATH: () => MANIFEST_PATH,
@@ -16,6 +19,7 @@ var repos_exports = /* @__PURE__ */ __exportAll({
 	NoteNotFoundError: () => NoteNotFoundError,
 	NoteNotFoundErrorBase: () => NoteNotFoundErrorBase,
 	REPOS_DIR: () => REPOS_DIR,
+	RepoDrift: () => RepoDrift,
 	RepoEntry: () => RepoEntry,
 	RepoName: () => RepoName,
 	RepoNotFoundError: () => RepoNotFoundError,
@@ -27,6 +31,8 @@ var repos_exports = /* @__PURE__ */ __exportAll({
 	ReposConfigError: () => ReposConfigError,
 	ReposConfigErrorBase: () => ReposConfigErrorBase,
 	ReposConfigStore: () => ReposConfigStore,
+	ReposDrift: () => ReposDrift,
+	ReposDriftReport: () => ReposDriftReport,
 	ReposLockdown: () => ReposLockdown,
 	ReposLockdownError: () => ReposLockdownError,
 	ReposLockdownErrorBase: () => ReposLockdownErrorBase,
@@ -34,6 +40,9 @@ var repos_exports = /* @__PURE__ */ __exportAll({
 	ReposManifestFile: () => ReposManifestFile,
 	ReposNoteResult: () => ReposNoteResult,
 	ReposPinResult: () => ReposPinResult,
+	ReposRemoveResult: () => ReposRemoveResult,
+	ReposRenameResult: () => ReposRenameResult,
+	ReposRestoreResult: () => ReposRestoreResult,
 	ReposStatusReport: () => ReposStatusReport,
 	ReposSyncReport: () => ReposSyncReport,
 	STALE_LOCK_MAX_AGE_MS: () => STALE_LOCK_MAX_AGE_MS,
@@ -41,4 +50,4 @@ var repos_exports = /* @__PURE__ */ __exportAll({
 });
 
 //#endregion
-export { GitSubmoduleError, GitSubmoduleErrorBase, MANIFEST_PATH, NoteNotFoundError, NoteNotFoundErrorBase, REPOS_DIR, RepoEntry, RepoName, RepoNotFoundError, RepoNotFoundErrorBase, RepoNote, RepoOrientation, RepoStatusEntry, ReposAddResult, ReposConfigError, ReposConfigErrorBase, ReposConfigStore, ReposLockdown, ReposLockdownError, ReposLockdownErrorBase, ReposManager, ReposManifestFile, ReposNoteResult, ReposPinResult, ReposStatusReport, ReposSyncReport, STALE_LOCK_MAX_AGE_MS, repos_exports, resolveModuleDir };
+export { DriftKind, GitSubmoduleError, GitSubmoduleErrorBase, MANIFEST_PATH, NoteNotFoundError, NoteNotFoundErrorBase, REPOS_DIR, RepoDrift, RepoEntry, RepoName, RepoNotFoundError, RepoNotFoundErrorBase, RepoNote, RepoOrientation, RepoStatusEntry, ReposAddResult, ReposConfigError, ReposConfigErrorBase, ReposConfigStore, ReposDrift, ReposDriftReport, ReposLockdown, ReposLockdownError, ReposLockdownErrorBase, ReposManager, ReposManifestFile, ReposNoteResult, ReposPinResult, ReposRemoveResult, ReposRenameResult, ReposRestoreResult, ReposStatusReport, ReposSyncReport, STALE_LOCK_MAX_AGE_MS, repos_exports, resolveModuleDir };

package/repos/schemas/drift.js

@@ -0,0 +1,49 @@
+import { Schema } from "effect";
+
+//#region src/repos/schemas/drift.ts
+/**
+* The kinds of drift {@link ReposDrift} can detect between the four
+* authorities it reconciles: the manifest, `.gitmodules`, the worktree, and
+* `git submodule status`.
+* @public
+*/
+const DriftKind = Schema.Literals([
+	"urlMismatch",
+	"pathMismatch",
+	"unregisteredManifestEntry",
+	"orphanGitmodulesEntry",
+	"missingWorktree",
+	"checkoutDiverged",
+	"missingShallow",
+	"gitmodulesUnparsable"
+]);
+/**
+* One detected disagreement between two (or more) of the four authorities
+* for a single vendored repo.
+*
+* @remarks
+* `manifestValue`/`observedValue` carry the two disagreeing values when the
+* drift is a value mismatch (`urlMismatch`, `pathMismatch`); other kinds
+* populate whichever side has a value to show (or neither, for
+* `gitmodulesUnparsable`, which is not about one repo).
+* @public
+*/
+var RepoDrift = class extends Schema.Class("RepoDrift")({
+	name: Schema.String,
+	kind: DriftKind,
+	detail: Schema.String,
+	manifestValue: Schema.optionalKey(Schema.String),
+	observedValue: Schema.optionalKey(Schema.String)
+}) {};
+/**
+* The result of reconciling the manifest, `.gitmodules`, the worktree, and
+* `git submodule status` for every vendored repo.
+* @public
+*/
+var ReposDriftReport = class extends Schema.Class("ReposDriftReport")({
+	drifts: Schema.Array(RepoDrift),
+	clean: Schema.Boolean
+}) {};
+
+//#endregion
+export { DriftKind, RepoDrift, ReposDriftReport };

package/repos/schemas/reports.js

@@ -1,9 +1,25 @@
+import { RepoNote } from "./manifest.js";
 import { Schema } from "effect";
 
 //#region src/repos/schemas/reports.ts
 /**
 * Status of one vendored repo: gitlink presence and dirtiness, plus notes
 * that no longer match the pinned ref.
+*
+* @remarks
+* `commit` is an alias of `stagedCommit`, retained for one release so an
+* existing consumer reading `entry.commit` keeps working while it migrates to
+* the index-aware triple. It carries no independent release tag beyond
+* `@public` (this schema has no narrower audience to gate it behind).
+* Removal is scheduled by a tracked issue, not gated on a renderer migration
+* precondition here.
+*
+* Not fully behavior-preserving: `commit: stagedCommit ?? null` reads `null`
+* for a gitlink committed at `HEAD` but staged for REMOVAL, where the prior
+* single-`commit` field showed the committed oid. `stagedCommit` is `None`
+* in exactly that case (nothing is staged), so the alias reports "nothing
+* staged" rather than "here is what HEAD still has" — a real, if narrow,
+* difference from the pre-triple `commit` field's behavior.
 * @public
 */
 const RepoStatusEntry = Schema.Struct({
@@ -11,7 +27,14 @@ const RepoStatusEntry = Schema.Struct({
 	ref: Schema.String,
 	purpose: Schema.String,
 	present: Schema.Boolean,
+	/** @deprecated alias of `stagedCommit`; retained for one release. */
 	commit: Schema.NullOr(Schema.String),
+	/** The gitlink oid staged in the index (`git ls-files --stage`) — sees a pin BEFORE it is committed. */
+	stagedCommit: Schema.optionalKey(Schema.String),
+	/** The gitlink oid committed at `HEAD` (`git ls-tree HEAD`). */
+	committedCommit: Schema.optionalKey(Schema.String),
+	/** The commit actually checked out in the submodule worktree (`git rev-parse HEAD` inside it); absent when there is no checkout. */
+	checkedOutCommit: Schema.optionalKey(Schema.String),
 	dirty: Schema.Boolean,
 	staleNoteIds: Schema.Array(Schema.String)
 });
@@ -26,14 +49,17 @@ const ReposStatusReport = Schema.Struct({
 /**
 * Result of reconciling working-tree submodules with the manifest: missing
 * repos initialized, sparse-checkout patterns re-applied, already-present
-* repos left alone, and stale locks cleared.
+* repos left alone, stale locks cleared, drifted submodule URLs reconciled,
+* and orphan manifest entries (no gitlink at all) registered.
 * @public
 */
 const ReposSyncReport = Schema.Struct({
 	initialized: Schema.Array(Schema.String),
 	sparseApplied: Schema.Array(Schema.String),
 	upToDate: Schema.Array(Schema.String),
-	clearedLocks: Schema.Array(Schema.String)
+	clearedLocks: Schema.Array(Schema.String),
+	urlSynced: Schema.Array(Schema.String),
+	registered: Schema.Array(Schema.String)
 });
 /**
 * Result of re-pinning a vendored repo to a new ref.
@@ -57,6 +83,51 @@ const ReposAddResult = Schema.Struct({
 	path: Schema.String
 });
 /**
+* Result of removing a vendored repo from the manifest: the gitlink, module
+* gitdir, and `.gitmodules` section are all gone, and the entry's notes are
+* surfaced so any durable ones can be promoted elsewhere before this result
+* is committed.
+* @public
+*/
+const ReposRemoveResult = Schema.Struct({
+	name: Schema.String,
+	path: Schema.String,
+	commitMessage: Schema.String,
+	removedNotes: Schema.Array(RepoNote)
+});
+/**
+* Result of renaming a vendored repo's manifest key: the `.repos/<name>`
+* worktree moved, the module gitdir's `core.worktree` values re-pointed, the
+* `.gitmodules` section canonicalized to the new name, and the manifest key
+* renamed.
+* @public
+*/
+const ReposRenameResult = Schema.Struct({
+	oldName: Schema.String,
+	newName: Schema.String,
+	path: Schema.String,
+	commitMessage: Schema.String
+});
+/**
+* Result of hard-resetting one or more vendored repos to their staged (or
+* committed) gitlink commit and re-applying sparse-checkout paths.
+*
+* @remarks
+* `restored` lists every repo actually reset, paired with the commit it was
+* reset to. `skippedClean` is populated ONLY by the names-omitted form of
+* {@link ReposManagerShape.restore} — repos left untouched because `status`
+* reported them clean; an explicit-names call never skips anything (an
+* explicit ask is always honored), so it always reports an empty array.
+* @public
+*/
+const ReposRestoreResult = Schema.Struct({
+	restored: Schema.Array(Schema.Struct({
+		name: Schema.String,
+		commit: Schema.String
+	})),
+	skippedClean: Schema.Array(Schema.String)
+});
+/**
 * Result of an agent-note mutation against a vendored repo.
 * @public
 */
@@ -72,4 +143,4 @@ const ReposNoteResult = Schema.Struct({
 });
 
 //#endregion
-export { RepoStatusEntry, ReposAddResult, ReposNoteResult, ReposPinResult, ReposStatusReport, ReposSyncReport };
+export { RepoStatusEntry, ReposAddResult, ReposNoteResult, ReposPinResult, ReposRemoveResult, ReposRenameResult, ReposRestoreResult, ReposStatusReport, ReposSyncReport };

package/repos/services/config-store.js

@@ -1,7 +1,7 @@
 import { MANIFEST_PATH, REPOS_DIR } from "../constants.js";
 import { ReposConfigError } from "../errors.js";
 import { ReposManifestFile } from "../schemas/manifest.js";
-import { Context, Effect, FileSystem, Layer, Path, Schema } from "effect";
+import { Clock, Context, Effect, FileSystem, Layer, Option, Path, Schedule, Schema } from "effect";
 
 //#region src/repos/services/config-store.ts
 /**
@@ -71,10 +71,44 @@ var ReposConfigStore = class extends Context.Service()("@savvy-web/silk-effects/
 				kind: "invalid"
 			})));
 		});
+		const lockSchedule = Schedule.exponential("25 millis").pipe(Schedule.upTo({ duration: "2 seconds" }));
+		const LOCK_MAX_AGE_MS = 6e4;
+		const acquireLock = (root) => Effect.gen(function* () {
+			const lockPath = `${manifestPath(root)}.lock`;
+			const dir = path.join(root, REPOS_DIR);
+			yield* fs.makeDirectory(dir, { recursive: true }).pipe(Effect.mapError((cause) => new ReposConfigError({
+				path: lockPath,
+				reason: `mkdir failed: ${String(cause)}`,
+				kind: "invalid"
+			})));
+			yield* Effect.gen(function* () {
+				const info = yield* fs.stat(lockPath).pipe(Effect.option);
+				if (Option.isSome(info) && Option.isSome(info.value.mtime)) {
+					if ((yield* Clock.currentTimeMillis) - info.value.mtime.value.getTime() >= LOCK_MAX_AGE_MS) yield* fs.remove(lockPath).pipe(Effect.ignore);
+				}
+				yield* Effect.scoped(fs.open(lockPath, { flag: "wx" })).pipe(Effect.asVoid);
+			}).pipe(Effect.retry({
+				schedule: lockSchedule,
+				while: (error) => error.reason._tag === "AlreadyExists"
+			}), Effect.mapError((cause) => new ReposConfigError({
+				path: lockPath,
+				reason: `timed out acquiring lock after 2s at ${lockPath}: ${String(cause)}. If no other savvy process is running, a previous run likely crashed while holding it -- remove ${lockPath} and retry.`,
+				kind: "invalid"
+			})));
+		});
+		const releaseLock = (root) => fs.remove(`${manifestPath(root)}.lock`).pipe(Effect.ignore);
+		const update = (root, fn) => Effect.scoped(Effect.gen(function* () {
+			yield* Effect.acquireRelease(acquireLock(root), () => releaseLock(root));
+			const result = fn(yield* read(root).pipe(Effect.catchTag("ReposConfigError", (error) => error.kind === "missing" ? Effect.succeed({ repos: {} }) : Effect.fail(error))));
+			const next = Effect.isEffect(result) ? yield* result : result;
+			yield* write(root, next);
+			return next;
+		}));
 		return {
 			exists,
 			read,
-			write
+			write,
+			update
 		};
 	}));
 };

package/repos/services/drift.js

@@ -0,0 +1,168 @@
+import { REPOS_DIR } from "../constants.js";
+import { GitSubmoduleError } from "../errors.js";
+import { RepoDrift, ReposDriftReport } from "../schemas/drift.js";
+import { ReposConfigStore } from "./config-store.js";
+import { Context, Effect, FileSystem, Layer, Option, Path, Result } from "effect";
+import { Git, Gitmodules } from "@effected/git";
+
+//#region src/repos/services/drift.ts
+/**
+* Reconciles the four authorities a vendored repo's state is spread across —
+* the manifest, `.gitmodules`, the worktree, and `git submodule status` —
+* and reports every disagreement found. Read-only: no staging, no lockdown
+* interaction, so it runs unmodified against a locked (`ReposLockdown`)
+* tree.
+* @public
+*/
+var ReposDrift = class extends Context.Service()("@savvy-web/silk-effects/ReposDrift") {
+	/**
+	* Production implementation of {@link ReposDrift}.
+	* @public
+	*/
+	static layer = Layer.effect(this, Effect.gen(function* () {
+		const configStore = yield* ReposConfigStore;
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const git = yield* Git;
+		/** Map any typed `@effected/git` failure onto this module's `GitSubmoduleError`. */
+		const asSubmoduleError = (command, cwd) => (error) => new GitSubmoduleError({
+			command,
+			cwd,
+			reason: error.message
+		});
+		const isPresent = (repoPath) => fs.readDirectory(repoPath).pipe(Effect.map((files) => files.length > 0), Effect.orElseSucceed(() => false));
+		const check = (root) => Effect.gen(function* () {
+			const manifest = yield* configStore.read(root);
+			const manifestEntries = Object.entries(manifest.repos);
+			const gitmodulesPath = path.join(root, ".gitmodules");
+			const gitmodulesText = yield* fs.readFileString(gitmodulesPath).pipe(Effect.map(Option.some), Effect.catchTag("PlatformError", (error) => error.reason._tag === "NotFound" ? Effect.succeed(Option.none()) : Effect.fail(asSubmoduleError("read .gitmodules", gitmodulesPath)(error))));
+			if (Option.isNone(gitmodulesText)) {
+				const drifts = manifestEntries.map(([name, entry]) => RepoDrift.make({
+					name,
+					kind: "unregisteredManifestEntry",
+					detail: `manifest entry "${name}" has no corresponding .gitmodules section (.gitmodules is absent)`,
+					manifestValue: entry.url
+				}));
+				return ReposDriftReport.make({
+					drifts,
+					clean: drifts.length === 0
+				});
+			}
+			const parsed = Gitmodules.parseResult(gitmodulesText.value);
+			if (Result.isFailure(parsed)) return ReposDriftReport.make({
+				drifts: [RepoDrift.make({
+					name: ".gitmodules",
+					kind: "gitmodulesUnparsable",
+					detail: `.gitmodules failed to parse: ${parsed.failure.message}`
+				})],
+				clean: false
+			});
+			const gitmodules = parsed.success;
+			const statuses = yield* git.submoduleStatus(root).pipe(Effect.mapError(asSubmoduleError("git submodule status", root)));
+			const statusByPath = new Map(statuses.map((status) => [status.path, status]));
+			const drifts = [];
+			const matchedSectionNames = /* @__PURE__ */ new Set();
+			const pairedByName = /* @__PURE__ */ new Map();
+			for (const [name] of manifestEntries) {
+				const expectedPath = `${REPOS_DIR}/${name}`;
+				const nameMatch = gitmodules.entries.find((candidate) => candidate.name === expectedPath && !matchedSectionNames.has(candidate.name));
+				if (nameMatch) {
+					matchedSectionNames.add(nameMatch.name);
+					pairedByName.set(name, {
+						section: nameMatch,
+						viaPath: false
+					});
+				}
+			}
+			for (const [name] of manifestEntries) {
+				if (pairedByName.has(name)) continue;
+				const expectedPath = `${REPOS_DIR}/${name}`;
+				const pathMatch = gitmodules.entries.find((candidate) => candidate.path === expectedPath && !matchedSectionNames.has(candidate.name));
+				if (pathMatch) {
+					matchedSectionNames.add(pathMatch.name);
+					pairedByName.set(name, {
+						section: pathMatch,
+						viaPath: true
+					});
+				}
+			}
+			for (const [name, entry] of manifestEntries) {
+				const expectedPath = `${REPOS_DIR}/${name}`;
+				const paired = pairedByName.get(name);
+				if (!paired) {
+					drifts.push(RepoDrift.make({
+						name,
+						kind: "unregisteredManifestEntry",
+						detail: `manifest entry "${name}" has no corresponding .gitmodules section`,
+						manifestValue: entry.url
+					}));
+					continue;
+				}
+				const { section, viaPath } = paired;
+				const pathMatch = viaPath ? section : void 0;
+				if (pathMatch) drifts.push(RepoDrift.make({
+					name,
+					kind: "pathMismatch",
+					detail: `manifest entry "${name}" paired with .gitmodules section "${pathMatch.name}" by its path "${expectedPath}" -- the section name diverges from the manifest entry name`,
+					manifestValue: name,
+					observedValue: pathMatch.name
+				}));
+				else if (section.path !== expectedPath) drifts.push(RepoDrift.make({
+					name,
+					kind: "pathMismatch",
+					detail: `manifest entry "${name}" expects path "${expectedPath}" but .gitmodules records "${section.path}"`,
+					manifestValue: expectedPath,
+					observedValue: section.path
+				}));
+				if (section.url !== entry.url) drifts.push(RepoDrift.make({
+					name,
+					kind: "urlMismatch",
+					detail: `manifest entry "${name}" expects url "${entry.url}" but .gitmodules records "${section.url}"`,
+					manifestValue: entry.url,
+					observedValue: section.url
+				}));
+				if (section.shallow !== true) drifts.push(RepoDrift.make({
+					name,
+					kind: "missingShallow",
+					detail: `.gitmodules does not record submodule.${section.name}.shallow = true`,
+					observedValue: section.shallow === void 0 ? "unset" : String(section.shallow)
+				}));
+				const repoPath = path.join(root, section.path);
+				const present = yield* isPresent(repoPath);
+				const status = statusByPath.get(section.path);
+				if (!present || status?.state === "uninitialized") drifts.push(RepoDrift.make({
+					name,
+					kind: "missingWorktree",
+					detail: `manifest entry "${name}" expects a checked-out worktree at "${section.path}" but none is present`
+				}));
+				else if (status?.state === "outOfSync") drifts.push(RepoDrift.make({
+					name,
+					kind: "checkoutDiverged",
+					detail: `the worktree checked out at "${section.path}" no longer matches the commit recorded in the superproject index`
+				}));
+				else if (status?.state === "conflict") drifts.push(RepoDrift.make({
+					name,
+					kind: "checkoutDiverged",
+					detail: `submodule index entry for "${section.path}" is in an unresolved merge conflict`
+				}));
+			}
+			for (const section of gitmodules.entries) {
+				if (matchedSectionNames.has(section.name)) continue;
+				drifts.push(RepoDrift.make({
+					name: section.name,
+					kind: "orphanGitmodulesEntry",
+					detail: `.gitmodules section "${section.name}" has no corresponding manifest entry`,
+					observedValue: section.path
+				}));
+			}
+			return ReposDriftReport.make({
+				drifts,
+				clean: drifts.length === 0
+			});
+		});
+		return { check };
+	}));
+};
+
+//#endregion
+export { ReposDrift };

package/repos/services/manager.js

@@ -3,8 +3,8 @@ import { GitSubmoduleError, NoteNotFoundError, RepoNotFoundError, ReposConfigErr
 import { RepoName } from "../schemas/manifest.js";
 import { ReposConfigStore } from "./config-store.js";
 import { ReposLockdown, resolveModuleDir } from "./lockdown.js";
-import { Clock, Context, Effect, FileSystem, Layer, Option, Path, Schema } from "effect";
-import { Git } from "@effected/git";
+import { Clock, Context, Effect, Exit, FileSystem, Layer, Option, Path, Result, Schema } from "effect";
+import { Git, GitConfig, Gitmodules, LsRemoteEntry } from "@effected/git";
 import { createHash } from "node:crypto";
 
 //#region src/repos/services/manager.ts
@@ -30,7 +30,9 @@ const STALE_LOCK_MAX_AGE_MS = 6e5;
 * Drives the vendored `.repos/` submodules over git: reports status
 * (presence, dirtiness, stale notes), reconciles the working tree with the
 * manifest, vendors new entries (`add`), re-pins existing entries to a new
-* ref (`pin`), and adds, removes, or promotes agent notes (`note`).
+* ref (`pin`), adds/removes/promotes agent notes (`note`), unvendors
+* (`remove`), renames (`rename`), and explicitly hard-resets dirty
+* checkouts back to their pinned commit (`restore`).
 * @public
 */
 var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/ReposManager") {
@@ -58,12 +60,25 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 			reason: error.message
 		});
 		const isPresent = (repoPath) => fs.readDirectory(repoPath).pipe(Effect.map((files) => files.length > 0), Effect.orElseSucceed(() => false));
+		/**
+		* `Object.hasOwn`-guarded membership read for the manifest's `repos`
+		* map. A bare bracket read (`repos[name]`) resolves an INHERITED
+		* `Object.prototype` member for a name like `"constructor"` or
+		* `"toString"` instead of reporting absence, letting a crafted repo
+		* name read back a function rather than fail typed as
+		* `RepoNotFoundError` (the same prototype-pollution-read hazard
+		* `ReleasePlanner` guards against for changelog module ids).
+		*/
+		const getRepoEntry = (repos, name) => Object.hasOwn(repos, name) ? repos[name] : void 0;
 		const status = (root) => Effect.gen(function* () {
 			const manifest = yield* configStore.read(root);
 			const repos = yield* Effect.forEach(Object.entries(manifest.repos), ([name, entry]) => Effect.gen(function* () {
 				const repoPath = path.join(root, REPOS_DIR, name);
+				const repoPathRel = `${REPOS_DIR}/${name}`;
 				const present = yield* isPresent(repoPath);
-				const commit = (yield* git.lsTree(root, "HEAD", { pathspec: [`${".repos"}/${name}`] }).pipe(Effect.mapError(asSubmoduleError(`git ls-tree HEAD -- ${".repos"}/${name}`, root))))[0]?.oid ?? null;
+				const committedCommit = (yield* git.lsTree(root, "HEAD", { pathspec: [repoPathRel] }).pipe(Effect.mapError(asSubmoduleError(`git ls-tree HEAD -- ${repoPathRel}`, root))))[0]?.oid;
+				const stagedCommit = (yield* git.lsFiles(root, { pathspec: [repoPathRel] }).pipe(Effect.mapError(asSubmoduleError(`git ls-files --stage -- ${repoPathRel}`, root)))).find((lsFilesEntry) => lsFilesEntry.mode === "160000")?.oid;
+				const checkedOutCommit = present ? yield* git.revParse(repoPath, "HEAD").pipe(Effect.catchTag("NotARepositoryError", () => Effect.succeed(void 0)), Effect.mapError(asSubmoduleError("git rev-parse HEAD", repoPath))) : void 0;
 				let dirty = false;
 				if (present) dirty = (yield* git.status(repoPath).pipe(Effect.mapError(asSubmoduleError("git status --porcelain", repoPath)))).length > 0;
 				const staleNoteIds = (entry.notes ?? []).filter((note) => note.ref !== entry.ref).map((note) => note.id);
@@ -72,7 +87,10 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 					ref: entry.ref,
 					purpose: entry.purpose,
 					present,
-					commit,
+					commit: stagedCommit ?? null,
+					...stagedCommit !== void 0 ? { stagedCommit } : {},
+					...committedCommit !== void 0 ? { committedCommit } : {},
+					...checkedOutCommit !== void 0 ? { checkedOutCommit } : {},
 					dirty,
 					staleNoteIds
 				};
@@ -88,8 +106,12 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 			const sparseApplied = [];
 			const upToDate = [];
 			const clearedLocks = [];
+			const urlSynced = [];
+			const registered = [];
+			const gitmodulesPath = path.join(root, ".gitmodules");
 			for (const [name, entry] of Object.entries(manifest.repos)) {
 				const repoPath = path.join(root, REPOS_DIR, name);
+				const repoPathRel = `${REPOS_DIR}/${name}`;
 				const moduleDir = yield* resolveModuleDir(fs, path, root, name);
 				yield* lockdown.withUnlocked(root, name, Effect.gen(function* () {
 					let clearedAnyLock = false;
@@ -106,12 +128,38 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 						}))) clearedAnyLock = true;
 					}
 					if (clearedAnyLock) clearedLocks.push(name);
-					if (!(yield* isPresent(repoPath))) {
+					const present = yield* isPresent(repoPath);
+					const gitmodulesText = yield* fs.readFileString(gitmodulesPath).pipe(Effect.option);
+					let gitmodulesEntry;
+					if (Option.isSome(gitmodulesText)) gitmodulesEntry = (yield* Gitmodules.parse(gitmodulesText.value).pipe(Effect.mapError(asSubmoduleError("parse .gitmodules", gitmodulesPath)))).entries.find((candidate) => candidate.path === repoPathRel);
+					if (present && gitmodulesEntry) {
+						const currentUrl = yield* git.configGet(repoPath, "remote.origin.url").pipe(Effect.mapError(asSubmoduleError("git config --get remote.origin.url", repoPath)));
+						if (Option.isSome(currentUrl) && currentUrl.value !== entry.url) {
+							const configResult = GitConfig.parseResult(Option.getOrThrow(gitmodulesText));
+							if (Result.isFailure(configResult)) return yield* Effect.fail(asSubmoduleError("parse .gitmodules", gitmodulesPath)(configResult.failure));
+							const setResult = Gitmodules.setUrl(configResult.success, gitmodulesEntry.name, entry.url);
+							if (Result.isFailure(setResult)) return yield* Effect.fail(asSubmoduleError(`gitmodules set-url ${gitmodulesEntry.name}`, gitmodulesPath)(setResult.failure));
+							yield* fs.writeFileString(gitmodulesPath, setResult.success.stringify()).pipe(Effect.mapError(asSubmoduleError("write .gitmodules", gitmodulesPath)));
+							yield* git.submoduleSync(root, { paths: [repoPathRel] }).pipe(Effect.mapError(asSubmoduleError(`git submodule sync -- ${repoPathRel}`, root)));
+							urlSynced.push(name);
+						} else upToDate.push(name);
+					} else if (!present && !gitmodulesEntry) {
+						yield* git.submoduleAdd(root, {
+							url: entry.url,
+							path: repoPathRel,
+							depth: 1
+						}).pipe(Effect.mapError(asSubmoduleError(`git submodule add --depth 1 ${entry.url} ${repoPathRel}`, root)));
+						yield* git.configSet(root, `submodule.${repoPathRel}.shallow`, "true", { file: ".gitmodules" }).pipe(Effect.mapError(asSubmoduleError(`git config -f .gitmodules submodule.${repoPathRel}.shallow true`, root)));
+						yield* fetchRef(repoPath, entry.ref);
+						yield* git.checkout(repoPath, "FETCH_HEAD", { detach: true }).pipe(Effect.mapError(asSubmoduleError("git checkout --detach FETCH_HEAD", repoPath)));
+						yield* git.add(root, [".gitmodules", repoPathRel]).pipe(Effect.mapError(asSubmoduleError(`git add .gitmodules ${repoPathRel}`, root)));
+						registered.push(name);
+					} else if (!present) {
 						yield* git.submoduleUpdate(root, {
 							init: true,
 							depth: 1,
-							paths: [`${REPOS_DIR}/${name}`]
-						}).pipe(Effect.mapError(asSubmoduleError(`git submodule update --init --depth 1 -- ${REPOS_DIR}/${name}`, root)));
+							paths: [repoPathRel]
+						}).pipe(Effect.mapError(asSubmoduleError(`git submodule update --init --depth 1 -- ${repoPathRel}`, root)));
 						initialized.push(name);
 					} else upToDate.push(name);
 					if (entry.sparse && entry.sparse.length > 0) {
@@ -124,7 +172,9 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 				initialized,
 				sparseApplied,
 				upToDate,
-				clearedLocks
+				clearedLocks,
+				urlSynced,
+				registered
 			};
 		});
 		/** Last path segment of a repo URL, with a trailing `.git` stripped. */
@@ -154,23 +204,82 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 				kind: "invalid"
 			})));
 			const manifest = yield* configStore.read(root).pipe(Effect.catchTag("ReposConfigError", (error) => error.kind === "missing" ? Effect.succeed({ repos: {} }) : Effect.fail(error)));
-			if (manifest.repos[name]) return yield* Effect.fail(new ReposConfigError({
+			if (getRepoEntry(manifest.repos, name)) return yield* Effect.fail(new ReposConfigError({
 				path: MANIFEST_PATH,
 				reason: `"${name}" is already vendored — use pin to change its ref`,
 				kind: "invalid"
 			}));
 			const repoPath = `${REPOS_DIR}/${name}`;
 			const subPath = path.join(root, repoPath);
+			const remoteRefs = yield* git.lsRemote(root, options.url, {
+				heads: true,
+				tags: true
+			}).pipe(Effect.mapError(asSubmoduleError(`git ls-remote --heads --tags ${options.url}`, root)));
+			if (!remoteRefs.some((remoteRef) => LsRemoteEntry.shortName(remoteRef.ref) === options.ref)) {
+				const suggestionNames = LsRemoteEntry.nearMatches(remoteRefs, options.ref).map((match) => LsRemoteEntry.shortName(match.ref));
+				const suggestions = [...new Set(suggestionNames)].slice(0, 5);
+				const reason = suggestions.length > 0 ? `ref "${options.ref}" not found at ${options.url}; did you mean: ${suggestions.join(", ")}?` : `ref "${options.ref}" not found at ${options.url}`;
+				return yield* Effect.fail(new GitSubmoduleError({
+					command: `git ls-remote --heads --tags ${options.url}`,
+					cwd: root,
+					reason
+				}));
+			}
+			const gitmodulesPath = path.join(root, ".gitmodules");
 			yield* lockdown.withUnlocked(root, name, Effect.gen(function* () {
-				yield* git.submoduleAdd(root, {
-					url: options.url,
-					path: repoPath,
-					depth: 1
-				}).pipe(Effect.mapError(asSubmoduleError(`git submodule add --depth 1 ${options.url} ${repoPath}`, root)));
-				yield* git.configSet(root, `submodule.${repoPath}.shallow`, "true", { file: ".gitmodules" }).pipe(Effect.mapError(asSubmoduleError(`git config -f .gitmodules submodule.${repoPath}.shallow true`, root)));
-				yield* fetchRef(subPath, options.ref);
-				yield* git.checkout(subPath, "FETCH_HEAD", { detach: true }).pipe(Effect.mapError(asSubmoduleError("git checkout --detach FETCH_HEAD", subPath)));
-				if (options.sparse && options.sparse.length > 0) yield* git.sparseCheckoutSet(subPath, options.sparse, { cone: false }).pipe(Effect.mapError(asSubmoduleError("git sparse-checkout set --no-cone", subPath)));
+				const gitmodulesTextOption = yield* fs.readFileString(gitmodulesPath).pipe(Effect.option);
+				let existingGitmodulesEntry;
+				if (Option.isSome(gitmodulesTextOption)) existingGitmodulesEntry = (yield* Gitmodules.parse(gitmodulesTextOption.value).pipe(Effect.mapError(asSubmoduleError("parse .gitmodules", gitmodulesPath)))).entries.find((candidate) => candidate.path === repoPath);
+				const gitlinkStaged = (yield* git.lsFiles(root, { pathspec: [repoPath] }).pipe(Effect.mapError(asSubmoduleError(`git ls-files --stage -- ${repoPath}`, root)))).some((stagedEntry) => stagedEntry.mode === "160000");
+				let resuming = false;
+				if (existingGitmodulesEntry && gitlinkStaged) {
+					if (existingGitmodulesEntry.url !== options.url) return yield* Effect.fail(new ReposConfigError({
+						path: gitmodulesPath,
+						reason: `"${name}" already has a partial submodule at ${repoPath} registered to a different url (${existingGitmodulesEntry.url}) than requested (${options.url}) — resolve the conflict manually before retrying add`,
+						kind: "invalid"
+					}));
+					resuming = true;
+				}
+				const rollbackStep = (step, effect) => effect.pipe(Effect.asVoid, Effect.catch((rollbackError) => Effect.logWarning(`repos add rollback for "${name}" — ${step} failed: ${String(rollbackError)}`)));
+				const rollback = (cause) => Effect.gen(function* () {
+					const moduleDir = yield* resolveModuleDir(fs, path, root, name);
+					yield* rollbackStep("submodule deinit", git.submoduleDeinit(root, {
+						paths: [repoPath],
+						force: true
+					}));
+					yield* rollbackStep("rm --cached", git.rm(root, [repoPath], { cached: true }));
+					yield* rollbackStep("remove worktree", fs.remove(subPath, {
+						recursive: true,
+						force: true
+					}));
+					yield* rollbackStep("remove module gitdir", fs.remove(moduleDir, {
+						recursive: true,
+						force: true
+					}));
+					const currentGitmodulesText = yield* fs.readFileString(gitmodulesPath).pipe(Effect.option);
+					if (Option.isSome(currentGitmodulesText)) {
+						const parsedForRollback = yield* Gitmodules.parse(currentGitmodulesText.value).pipe(Effect.option);
+						const section = Option.isSome(parsedForRollback) ? parsedForRollback.value.entries.find((candidate) => candidate.name === repoPath) ?? parsedForRollback.value.entries.find((candidate) => candidate.path === repoPath) : void 0;
+						if (section) {
+							const configResult = GitConfig.parseResult(currentGitmodulesText.value);
+							if (Result.isSuccess(configResult)) {
+								const removeResult = Gitmodules.remove(configResult.success, section.name);
+								if (Result.isSuccess(removeResult)) yield* rollbackStep("restore .gitmodules", fs.writeFileString(gitmodulesPath, removeResult.success.stringify()));
+							}
+						}
+					}
+				}).pipe(Effect.andThen(Effect.fail(cause)));
+				yield* Effect.gen(function* () {
+					if (!resuming) yield* git.submoduleAdd(root, {
+						url: options.url,
+						path: repoPath,
+						depth: 1
+					}).pipe(Effect.mapError(asSubmoduleError(`git submodule add --depth 1 ${options.url} ${repoPath}`, root)));
+					yield* git.configSet(root, `submodule.${repoPath}.shallow`, "true", { file: ".gitmodules" }).pipe(Effect.mapError(asSubmoduleError(`git config -f .gitmodules submodule.${repoPath}.shallow true`, root)));
+					yield* fetchRef(subPath, options.ref);
+					yield* git.checkout(subPath, "FETCH_HEAD", { detach: true }).pipe(Effect.mapError(asSubmoduleError("git checkout --detach FETCH_HEAD", subPath)));
+					if (options.sparse && options.sparse.length > 0) yield* git.sparseCheckoutSet(subPath, options.sparse, { cone: false }).pipe(Effect.mapError(asSubmoduleError("git sparse-checkout set --no-cone", subPath)));
+				}).pipe(Effect.catch(rollback));
 			}));
 			const entry = {
 				url: options.url,
@@ -178,10 +287,10 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 				purpose: options.purpose,
 				...options.sparse && options.sparse.length > 0 ? { sparse: options.sparse } : {}
 			};
-			yield* configStore.write(root, { repos: {
-				...manifest.repos,
+			yield* configStore.update(root, (fresh) => ({ repos: {
+				...fresh.repos,
 				[name]: entry
-			} });
+			} }));
 			yield* git.add(root, [
 				".gitmodules",
 				MANIFEST_PATH,
@@ -195,7 +304,7 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 		});
 		const pin = (root, name, ref) => Effect.gen(function* () {
 			const manifest = yield* configStore.read(root);
-			const entry = manifest.repos[name];
+			const entry = getRepoEntry(manifest.repos, name);
 			if (!entry) return yield* Effect.fail(new RepoNotFoundError({ name }));
 			const repoPath = `${REPOS_DIR}/${name}`;
 			const subPath = path.join(root, repoPath);
@@ -208,14 +317,27 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 					newCommit: yield* git.revParse(subPath, "HEAD").pipe(Effect.mapError(asSubmoduleError("git rev-parse HEAD", subPath)))
 				};
 			}));
-			yield* configStore.write(root, { repos: {
-				...manifest.repos,
-				[name]: {
-					...entry,
-					ref
-				}
-			} });
-			yield* git.add(root, [MANIFEST_PATH, repoPath]).pipe(Effect.mapError(asSubmoduleError(`git add ${MANIFEST_PATH} ${repoPath}`, root)));
+			yield* configStore.update(root, (fresh) => {
+				const freshEntry = getRepoEntry(fresh.repos, name);
+				if (!freshEntry) return Effect.fail(new ReposConfigError({
+					path: path.join(root, MANIFEST_PATH),
+					reason: `pin applied to git but manifest entry "${name}" is gone; manifest and checkout now disagree`,
+					kind: "invalid"
+				}));
+				return Effect.succeed({ repos: {
+					...fresh.repos,
+					[name]: {
+						...freshEntry,
+						ref
+					}
+				} });
+			});
+			const gitmodulesChanged = (yield* git.status(root).pipe(Effect.mapError(asSubmoduleError("git status --porcelain", root)))).some((s) => s.path === ".gitmodules");
+			yield* git.add(root, gitmodulesChanged ? [
+				MANIFEST_PATH,
+				repoPath,
+				".gitmodules"
+			] : [MANIFEST_PATH, repoPath]).pipe(Effect.mapError(asSubmoduleError(gitmodulesChanged ? `git add ${MANIFEST_PATH} ${repoPath} .gitmodules` : `git add ${MANIFEST_PATH} ${repoPath}`, root)));
 			const staleNoteIds = (entry.notes ?? []).filter((note) => note.ref !== ref).map((note) => note.id);
 			return {
 				name,
@@ -228,7 +350,7 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 		});
 		const note = (root, name, op) => Effect.gen(function* () {
 			const manifest = yield* configStore.read(root);
-			const entry = manifest.repos[name];
+			const entry = getRepoEntry(manifest.repos, name);
 			if (!entry) return yield* Effect.fail(new RepoNotFoundError({ name }));
 			const notes = entry.notes ?? [];
 			if (op.op === "add") {
@@ -269,10 +391,10 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 					...entry,
 					notes: updatedNotes
 				};
-				yield* configStore.write(root, { repos: {
-					...manifest.repos,
+				yield* configStore.update(root, (fresh) => ({ repos: {
+					...fresh.repos,
 					[name]: updatedEntry
-				} });
+				} }));
 				return {
 					name,
 					op: "add",
@@ -291,10 +413,10 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 					...entry,
 					notes: updatedNotes
 				};
-				yield* configStore.write(root, { repos: {
-					...manifest.repos,
+				yield* configStore.update(root, (fresh) => ({ repos: {
+					...fresh.repos,
 					[name]: updatedEntry
-				} });
+				} }));
 				return {
 					name,
 					op: "remove",
@@ -302,19 +424,21 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 					noteCount: updatedNotes.length
 				};
 			}
+			const existing = entry.orientation?.[op.into];
+			const promoted = existing === void 0 ? target.note : `${existing}\n\n${target.note}`;
 			const updatedOrientation = {
 				...entry.orientation,
-				[op.into]: target.note
+				[op.into]: promoted
 			};
 			const updatedEntry = {
 				...entry,
 				orientation: updatedOrientation,
 				notes: updatedNotes
 			};
-			yield* configStore.write(root, { repos: {
-				...manifest.repos,
+			yield* configStore.update(root, (fresh) => ({ repos: {
+				...fresh.repos,
 				[name]: updatedEntry
-			} });
+			} }));
 			return {
 				name,
 				op: "promote",
@@ -322,12 +446,190 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 				noteCount: updatedNotes.length
 			};
 		});
+		const remove = (root, name) => Effect.gen(function* () {
+			const manifest = yield* configStore.read(root);
+			const entry = getRepoEntry(manifest.repos, name);
+			if (!entry) return yield* Effect.fail(new RepoNotFoundError({ name }));
+			const repoPath = `${REPOS_DIR}/${name}`;
+			const subPath = path.join(root, repoPath);
+			const moduleDir = yield* resolveModuleDir(fs, path, root, name);
+			yield* lockdown.withUnlocked(root, name, Effect.gen(function* () {
+				yield* git.submoduleDeinit(root, {
+					paths: [repoPath],
+					force: true
+				}).pipe(Effect.mapError(asSubmoduleError(`git submodule deinit --force -- ${repoPath}`, root)));
+				yield* git.rm(root, [repoPath], { cached: true }).pipe(Effect.mapError(asSubmoduleError(`git rm --cached ${repoPath}`, root)));
+				yield* fs.remove(subPath, {
+					recursive: true,
+					force: true
+				}).pipe(Effect.mapError((cause) => new GitSubmoduleError({
+					command: "remove worktree",
+					cwd: subPath,
+					reason: String(cause)
+				})));
+				yield* fs.remove(moduleDir, {
+					recursive: true,
+					force: true
+				}).pipe(Effect.mapError((cause) => new GitSubmoduleError({
+					command: "remove module gitdir",
+					cwd: moduleDir,
+					reason: String(cause)
+				})));
+			}));
+			const gitmodulesPath = path.join(root, ".gitmodules");
+			const gitmodulesText = yield* fs.readFileString(gitmodulesPath).pipe(Effect.mapError(asSubmoduleError("read .gitmodules", gitmodulesPath)));
+			const parsedGitmodules = yield* Gitmodules.parse(gitmodulesText).pipe(Effect.mapError(asSubmoduleError("parse .gitmodules", gitmodulesPath)));
+			const section = parsedGitmodules.entries.find((candidate) => candidate.name === repoPath) ?? parsedGitmodules.entries.find((candidate) => candidate.path === repoPath);
+			if (!section) return yield* Effect.fail(new ReposConfigError({
+				path: gitmodulesPath,
+				reason: `no .gitmodules section found for "${name}" (looked for name or path "${repoPath}")`,
+				kind: "invalid"
+			}));
+			const configResult = GitConfig.parseResult(gitmodulesText);
+			if (Result.isFailure(configResult)) return yield* Effect.fail(asSubmoduleError("parse .gitmodules", gitmodulesPath)(configResult.failure));
+			const removeResult = Gitmodules.remove(configResult.success, section.name);
+			if (Result.isFailure(removeResult)) return yield* Effect.fail(asSubmoduleError(`gitmodules remove ${section.name}`, gitmodulesPath)(removeResult.failure));
+			yield* fs.writeFileString(gitmodulesPath, removeResult.success.stringify()).pipe(Effect.mapError(asSubmoduleError("write .gitmodules", gitmodulesPath)));
+			yield* configStore.update(root, (fresh) => {
+				const { [name]: _dropped, ...rest } = fresh.repos;
+				return { repos: rest };
+			});
+			yield* git.add(root, [".gitmodules", MANIFEST_PATH]).pipe(Effect.mapError(asSubmoduleError(`git add .gitmodules ${MANIFEST_PATH}`, root)));
+			return {
+				name,
+				path: repoPath,
+				commitMessage: `chore(repos): remove ${name}`,
+				removedNotes: entry.notes ?? []
+			};
+		});
+		const rename = (root, oldName, newName) => Effect.gen(function* () {
+			const manifest = yield* configStore.read(root);
+			if (!getRepoEntry(manifest.repos, oldName)) return yield* Effect.fail(new RepoNotFoundError({ name: oldName }));
+			yield* Schema.decodeUnknownEffect(RepoName)(newName).pipe(Effect.mapError(() => new ReposConfigError({
+				path: MANIFEST_PATH,
+				reason: `invalid repo name "${newName}": must be non-empty, contain no "/" or "\\", and not be "." or ".."`,
+				kind: "invalid"
+			})));
+			if (getRepoEntry(manifest.repos, newName)) return yield* Effect.fail(new ReposConfigError({
+				path: MANIFEST_PATH,
+				reason: `"${newName}" is already vendored — choose a different name`,
+				kind: "invalid"
+			}));
+			const oldRepoPath = `${REPOS_DIR}/${oldName}`;
+			const newRepoPath = `${REPOS_DIR}/${newName}`;
+			const gitmodulesPath = path.join(root, ".gitmodules");
+			const moduleDir = yield* resolveModuleDir(fs, path, root, oldName);
+			yield* Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+				const unlockExit = yield* Effect.exit(lockdown.unlock(root, oldName));
+				let lockName = oldName;
+				const resultExit = Exit.isFailure(unlockExit) ? Exit.failCause(unlockExit.cause) : yield* Effect.exit(restore(Effect.gen(function* () {
+					yield* git.mv(root, oldRepoPath, newRepoPath).pipe(Effect.mapError(asSubmoduleError(`git mv ${oldRepoPath} ${newRepoPath}`, root)));
+					lockName = newName;
+					const absoluteNewSubPath = path.resolve(root, newRepoPath);
+					const worktreeValue = path.relative(moduleDir, absoluteNewSubPath);
+					yield* git.configSet(root, "core.worktree", worktreeValue, { file: path.join(moduleDir, "config") }).pipe(Effect.mapError(asSubmoduleError("git config core.worktree", moduleDir)));
+					const worktreeConfigPath = path.join(moduleDir, "config.worktree");
+					if (yield* fs.exists(worktreeConfigPath).pipe(Effect.orElseSucceed(() => false))) yield* git.configSet(root, "core.worktree", worktreeValue, { file: worktreeConfigPath }).pipe(Effect.mapError(asSubmoduleError("git config -f config.worktree core.worktree", moduleDir)));
+					const gitmodulesText = yield* fs.readFileString(gitmodulesPath).pipe(Effect.mapError(asSubmoduleError("read .gitmodules", gitmodulesPath)));
+					const section = (yield* Gitmodules.parse(gitmodulesText).pipe(Effect.mapError(asSubmoduleError("parse .gitmodules", gitmodulesPath)))).entries.find((candidate) => candidate.path === newRepoPath);
+					if (!section) return yield* Effect.fail(new ReposConfigError({
+						path: gitmodulesPath,
+						reason: `no .gitmodules section found for "${newName}" after mv (looked for path "${newRepoPath}")`,
+						kind: "invalid"
+					}));
+					if (section.name !== newRepoPath) {
+						const oldSectionName = section.name;
+						const configResult = GitConfig.parseResult(gitmodulesText);
+						if (Result.isFailure(configResult)) return yield* Effect.fail(asSubmoduleError("parse .gitmodules", gitmodulesPath)(configResult.failure));
+						const renameResult = Gitmodules.rename(configResult.success, oldSectionName, newRepoPath);
+						if (Result.isFailure(renameResult)) return yield* Effect.fail(asSubmoduleError(`gitmodules rename ${oldSectionName} -> ${newRepoPath}`, gitmodulesPath)(renameResult.failure));
+						yield* fs.writeFileString(gitmodulesPath, renameResult.success.stringify()).pipe(Effect.mapError(asSubmoduleError("write .gitmodules", gitmodulesPath)));
+						yield* git.add(root, [".gitmodules"]).pipe(Effect.mapError(asSubmoduleError("git add .gitmodules", root)));
+						const unsetIfPresent = (key) => git.configGet(root, key).pipe(Effect.mapError(asSubmoduleError(`git config --get ${key}`, root)), Effect.flatMap((current) => Option.isSome(current) ? git.configUnset(root, key).pipe(Effect.mapError(asSubmoduleError(`git config --unset ${key}`, root))) : Effect.void));
+						yield* unsetIfPresent(`submodule.${oldSectionName}.url`);
+						yield* unsetIfPresent(`submodule.${oldSectionName}.active`);
+					}
+					yield* git.submoduleInit(root, { paths: [newRepoPath] }).pipe(Effect.mapError(asSubmoduleError(`git submodule init -- ${newRepoPath}`, root)));
+					yield* configStore.update(root, (fresh) => {
+						const renamedEntry = getRepoEntry(fresh.repos, oldName);
+						if (!renamedEntry) return Effect.fail(new ReposConfigError({
+							path: MANIFEST_PATH,
+							reason: `rename applied to git but manifest entry "${oldName}" is gone; manifest and .gitmodules now disagree`,
+							kind: "invalid"
+						}));
+						const { [oldName]: _dropped, ...rest } = fresh.repos;
+						return { repos: {
+							...rest,
+							[newName]: renamedEntry
+						} };
+					});
+					yield* git.add(root, [MANIFEST_PATH]).pipe(Effect.mapError(asSubmoduleError(`git add ${MANIFEST_PATH}`, root)));
+					yield* git.submoduleStatus(root).pipe(Effect.mapError(asSubmoduleError("git submodule status", root)));
+				})));
+				const relockExit = yield* Effect.exit(lockdown.lock(root, lockName));
+				if (Exit.isFailure(resultExit)) return yield* Exit.failCause(resultExit.cause);
+				if (Exit.isFailure(relockExit)) return yield* Exit.failCause(relockExit.cause);
+			}));
+			return {
+				oldName,
+				newName,
+				path: newRepoPath,
+				commitMessage: `chore(repos): rename ${oldName} to ${newName}`
+			};
+		});
+		const restore = (root, names) => Effect.gen(function* () {
+			const manifest = yield* configStore.read(root);
+			let targetNames;
+			let skippedClean = [];
+			if (names && names.length > 0) {
+				for (const name of names) if (!getRepoEntry(manifest.repos, name)) return yield* Effect.fail(new RepoNotFoundError({ name }));
+				targetNames = names;
+			} else {
+				const report = yield* status(root);
+				targetNames = report.repos.filter((entry) => entry.dirty).map((entry) => entry.name);
+				skippedClean = report.repos.filter((entry) => !entry.dirty).map((entry) => entry.name);
+			}
+			const restored = [];
+			for (const name of targetNames) {
+				const entry = getRepoEntry(manifest.repos, name);
+				if (!entry) return yield* Effect.fail(new RepoNotFoundError({ name }));
+				const repoPath = `${REPOS_DIR}/${name}`;
+				const subPath = path.join(root, repoPath);
+				const commit = yield* lockdown.withUnlocked(root, name, Effect.gen(function* () {
+					let targetCommit = (yield* git.lsFiles(root, { pathspec: [repoPath] }).pipe(Effect.mapError(asSubmoduleError(`git ls-files --stage -- ${repoPath}`, root)))).find((lsFilesEntry) => lsFilesEntry.mode === "160000")?.oid;
+					if (targetCommit === void 0) targetCommit = (yield* git.lsTree(root, "HEAD", { pathspec: [repoPath] }).pipe(Effect.mapError(asSubmoduleError(`git ls-tree HEAD -- ${repoPath}`, root))))[0]?.oid;
+					if (targetCommit === void 0) return yield* Effect.fail(new GitSubmoduleError({
+						command: "resolve restore target commit",
+						cwd: subPath,
+						reason: `no staged or committed gitlink commit found for "${name}" -- nothing to restore to`
+					}));
+					yield* git.reset(subPath, {
+						mode: "hard",
+						ref: targetCommit
+					}).pipe(Effect.mapError(asSubmoduleError(`git reset --hard ${targetCommit}`, subPath)));
+					yield* git.clean(subPath, { directories: true }).pipe(Effect.mapError(asSubmoduleError("git clean --force -d", subPath)));
+					if (entry.sparse && entry.sparse.length > 0) yield* git.sparseCheckoutSet(subPath, entry.sparse, { cone: false }).pipe(Effect.mapError(asSubmoduleError("git sparse-checkout set --no-cone", subPath)));
+					return targetCommit;
+				}));
+				restored.push({
+					name,
+					commit
+				});
+			}
+			return {
+				restored,
+				skippedClean
+			};
+		});
 		return {
 			status,
 			sync,
 			add,
 			pin,
-			note
+			note,
+			remove,
+			rename,
+			restore
 		};
 	}));
 };