@savvy-web/silk-effects 5.5.2 → 5.6.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, drift detection, sync, add, pin, note, remove, rename and restore — 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 worktree read-only between mutations
 - Locate config files and keep Biome schema URLs in sync across workspaces
 
 ## Install
@@ -366,9 +366,17 @@ const diagnosis = await Effect.runPromise(
 
 #### 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, `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.
+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 gitlink 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, `git submodule status` and the superproject's local git config, 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` (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.
+`status` reports the gitlink as a triple, because the index, `HEAD` and the submodule's own checkout legitimately disagree mid-pin: `stagedCommit` (the index), `committedCommit` (`HEAD`) and `checkedOutCommit` (the worktree). The deprecated single `commit` field that aliased `stagedCommit` has been removed — read `stagedCommit` instead.
+
+`ReposLockdown` is the permissions boundary around all of that, and it covers the vendored WORKTREE only. `lock(root, name)` chmods that worktree 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 worktree is read-only whenever the manager is not mid-write. Reads are unaffected — a locked tree needs no special handling to open a file.
+
+The submodule's git metadata directory under `.git/modules/` is deliberately left writable, so a plain `git pull` and any GUI client that keeps per-gitdir state keep working against a repo that uses this mechanism. `unlock` still walks that directory, freeing one an older release locked; `lock` never re-locks it. The trade is that a `git checkout` inside a vendored worktree still succeeds, moving `HEAD` while leaving the files stale — `ReposDrift` classifies that as `checkoutDiverged` and `restore` repairs it, so a drifted pin is always detected rather than prevented.
+
+The declarative half of the boundary is written by `sync` and `add`, into the superproject's local git config rather than `.gitmodules`: `submodule.<path>.update = none` per entry and `fetch.recurseSubmodules = false`, so ordinary git clients skip these trees instead of discovering the boundary by failing on a permission error. `ReposSyncReport.boundaryMarked` lists the entries whose marker was asserted on that run.
+
+Two report fields exist to say what was achieved rather than attempted. `ReposRestoreResult.stillDirty` names repos that were reset but whose worktree is dirty afterwards, so a caller reading `restored` alone cannot mistake an incomplete restore for a clean one. `ReposRemoveResult.removedEntry` hands back the whole manifest entry — pass its `orientation` block straight to `add`'s `orientation` option to make a remove-then-re-add lossless, since `add` resurrects nothing on its own.
 
 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`.
 
@@ -388,7 +396,8 @@ const report = await Effect.runPromise(
     Effect.provide(NodeServices.layer),
   ),
 );
-// => ReposSyncReport: per-repo initialization and sparse-checkout outcome, trees left read-only
+// => ReposSyncReport: per-repo initialization and sparse-checkout outcome,
+//    plus boundaryMarked; worktrees left read-only
 ```
 
 ## Documentation

package/index.d.ts

@@ -8298,17 +8298,17 @@ declare class ReposLockdownError extends ReposLockdownErrorBase<{
 //#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`.
+ * The kinds of drift {@link ReposDrift} can detect between the five
+ * authorities it reconciles: the manifest, `.gitmodules`, the worktree,
+ * `git submodule status`, and the superproject's local git config.
  * @public
  */
-declare const DriftKind: Schema.Literals<readonly ["urlMismatch", "pathMismatch", "unregisteredManifestEntry", "orphanGitmodulesEntry", "missingWorktree", "checkoutDiverged", "missingShallow", "gitmodulesUnparsable"]>;
+declare const DriftKind: Schema.Literals<readonly ["urlMismatch", "pathMismatch", "unregisteredManifestEntry", "orphanGitmodulesEntry", "missingWorktree", "checkoutDiverged", "missingShallow", "gitmodulesUnparsable", "localRegistrationDivergence", "nestedSubmoduleDivergence"]>;
 /** @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 kind: Schema.Literals<readonly ["urlMismatch", "pathMismatch", "unregisteredManifestEntry", "orphanGitmodulesEntry", "missingWorktree", "checkoutDiverged", "missingShallow", "gitmodulesUnparsable", "localRegistrationDivergence", "nestedSubmoduleDivergence"]>;
   readonly detail: Schema.String;
   readonly manifestValue: Schema.optionalKey<Schema.String>;
   readonly observedValue: Schema.optionalKey<Schema.String>;
@@ -8424,19 +8424,11 @@ type ReposManifestFile = typeof ReposManifestFile.Type;
  * 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.
+ * The gitlink is reported as an index-aware TRIPLE — `stagedCommit` (the
+ * index), `committedCommit` (`HEAD`), `checkedOutCommit` (the submodule's own
+ * worktree) — because those three legitimately disagree during a pin, and a
+ * single field cannot say which one it means. A deprecated `commit` alias of
+ * `stagedCommit` bridged one release and is now gone; read `stagedCommit`.
  * @public
  */
 declare const RepoStatusEntry: Schema.Struct<{
@@ -8444,8 +8436,6 @@ 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`). */
@@ -8467,8 +8457,6 @@ 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`). */
@@ -8486,7 +8474,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, stale locks cleared, drifted submodule URLs reconciled,
- * and orphan manifest entries (no gitlink at all) registered.
+ * orphan manifest entries (no gitlink at all) registered, and the vendored
+ * boundary re-declared to git.
  * @public
  */
 declare const ReposSyncReport: Schema.Struct<{
@@ -8496,6 +8485,14 @@ declare const ReposSyncReport: Schema.Struct<{
   readonly clearedLocks: Schema.$Array<Schema.String>;
   readonly urlSynced: Schema.$Array<Schema.String>;
   readonly registered: Schema.$Array<Schema.String>;
+  /**
+   * Repos whose `submodule.<path>.update = none` marker was (re-)asserted in
+   * the superproject's local config — the declarative half of the vendored
+   * boundary, telling every git client to skip these trees rather than
+   * letting them discover the boundary by failing against a permission
+   * error.
+   */
+  readonly boundaryMarked: Schema.$Array<Schema.String>;
 }>;
 /** @public */
 type ReposSyncReport = typeof ReposSyncReport.Type;
@@ -8526,9 +8523,23 @@ declare const ReposAddResult: Schema.Struct<{
 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.
+ * gitdir, and `.gitmodules` section are all gone, and the entry that was
+ * removed is handed back so nothing durable is lost.
+ *
+ * @remarks
+ * `removedEntry` is the whole manifest entry, and it exists because
+ * remove-then-re-add is the standing remedy for several vendored-tree
+ * problems. `add` does not resurrect anything on its own, so without the
+ * entry in hand a caller following that remedy silently destroys the
+ * `orientation` block — larger and far harder to reconstruct than the notes,
+ * and invisible afterwards in every report an agent would think to check.
+ * Pass `removedEntry.orientation` straight back to `add` to make a re-vendor
+ * lossless.
+ *
+ * `removedNotes` is retained alongside it, and is exactly
+ * `removedEntry.notes ?? []`. Notes are ephemeral by policy — a last look
+ * before they go, so a durable one can be promoted elsewhere — whereas
+ * orientation is meant to survive.
  * @public
  */
 declare const ReposRemoveResult: Schema.Struct<{
@@ -8541,6 +8552,23 @@ declare const ReposRemoveResult: Schema.Struct<{
     readonly ref: Schema.String;
     readonly note: Schema.String;
   }>>;
+  readonly removedEntry: Schema.Struct<{
+    readonly url: Schema.String;
+    readonly ref: Schema.String;
+    readonly purpose: Schema.String;
+    readonly sparse: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly orientation: Schema.optional<Schema.Struct<{
+      readonly layout: Schema.optional<Schema.String>;
+      readonly keyPaths: Schema.optional<Schema.$Record<Schema.String, Schema.String>>;
+      readonly startHere: Schema.optional<Schema.String>;
+    }>>;
+    readonly notes: Schema.optional<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;
@@ -8569,6 +8597,13 @@ type ReposRenameResult = typeof ReposRenameResult.Type;
  * {@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.
+ *
+ * `stillDirty` is the honesty channel: a repo that was reset but whose
+ * worktree is STILL dirty afterwards. `restored` alone cannot express that —
+ * it says what was attempted, not what was achieved — and a caller reading
+ * only `restored` would take a report of a repo that never came clean as
+ * success. Membership in both `restored` and `stillDirty` is the normal shape
+ * for such a repo.
  * @public
  */
 declare const ReposRestoreResult: Schema.Struct<{
@@ -8577,6 +8612,7 @@ declare const ReposRestoreResult: Schema.Struct<{
     readonly commit: Schema.String;
   }>>;
   readonly skippedClean: Schema.$Array<Schema.String>;
+  readonly stillDirty: Schema.$Array<Schema.String>;
 }>;
 /** @public */
 type ReposRestoreResult = typeof ReposRestoreResult.Type;
@@ -8634,11 +8670,18 @@ interface ReposDriftShape {
 }
 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.
+ * Reconciles the five authorities a vendored repo's state is spread across —
+ * the manifest, `.gitmodules`, the worktree, `git submodule status`, and the
+ * superproject's LOCAL git config — and reports every disagreement found,
+ * including one level down into a vendored repo's own submodules. Read-only:
+ * no staging, no lockdown interaction, so it runs unmodified against a locked
+ * (`ReposLockdown`) tree.
+ *
+ * @remarks
+ * The local config is the fifth authority because the other four can all
+ * agree while a checkout is still REGISTERED under a pre-canonicalization
+ * section name — a state that reads clean here while `git submodule status`
+ * reports a perfectly healthy checkout as uninitialized.
  * @public
  */
 declare class ReposDrift extends ReposDrift_base {
@@ -8666,8 +8709,11 @@ interface ReposLockdownShape {
  * A submodule worktree's `<root>/.repos/<name>/.git` is normally a FILE
  * containing a single `gitdir: <path>` line pointing at the real metadata
  * directory, which git names after whatever path/name the submodule was
- * REGISTERED under — not necessarily the manifest key (e.g. this repo's own
- * `effect` entry has gitdir `.git/modules/.repos/effect-smol`). This helper
+ * REGISTERED under — not necessarily the manifest key. Git never renames
+ * that directory, so a manifest entry re-slugged after it was first vendored
+ * keeps its original gitdir name indefinitely (manifest key `<new>`, gitdir
+ * `.git/modules/.repos/<old>`). `ReposDrift` reports that state as
+ * `localRegistrationDivergence`; re-vendoring the entry clears it. This helper
  * reads that pointer and resolves it (relative pointers are relative to the
  * directory containing the `.git` file) so callers always land on the real
  * metadata directory.
@@ -8685,6 +8731,39 @@ declare const ReposLockdown_base: Context.ServiceClass<ReposLockdown, "@savvy-we
 /**
  * Enforces OS-level read-only permissions on vendored repos so they cannot
  * be accidentally edited outside the sync flow.
+ *
+ * @remarks
+ * SCOPE: the WORKTREE only. The submodule's git metadata directory
+ * (`.git/modules/...`) is deliberately NOT locked — `unlock` still walks it
+ * so trees locked by an older version are freed, but `lock` never re-locks
+ * it. Do not "restore" the metadata lock without re-reading this note.
+ *
+ * Locking the metadata directory made the boundary enforce itself only via
+ * `EACCES`, whose message names neither `.repos/` nor a reason, and it broke
+ * every client that needs incidental gitdir writes: a plain `git pull` that
+ * moves a gitlink recurses by default and dies writing `FETCH_HEAD`, and any
+ * client keeping per-gitdir state (GitKraken writes a `gk/` directory into
+ * every gitdir it manages, which no git setting governs) is structurally
+ * incompatible with a read-only gitdir. Since vendored reference sources are
+ * the overwhelming majority of submodules in this ecosystem, ordinary tooling
+ * collided with the lockdown constantly.
+ *
+ * What the worktree lock still buys, verified against git 2.54:
+ *
+ * - editing a vendored file fails (`EACCES`) — the property the system
+ *   actually needs;
+ * - `git reset --hard` inside a vendored tree fails (cannot unlink);
+ * - `git checkout <other>` does NOT fail — it moves `HEAD` while leaving the
+ *   worktree stale. That is the one guarantee given up here, and it is given
+ *   up knowingly: git immediately reports the submodule as `+<oid>`, which
+ *   {@link ReposDrift} already classifies as `checkoutDiverged` and
+ *   `ReposManager.restore` repairs.
+ *
+ * So the invariant weakens from "the pin cannot drift" to "a drifted pin is
+ * always detected and one command from repaired." The declarative half of the
+ * boundary — `submodule.<path>.update = none`, so clients skip these trees
+ * rather than discovering the boundary by failing — is asserted by
+ * `ReposManager.sync`, not here.
  * @public
  */
 declare class ReposLockdown extends ReposLockdown_base {
@@ -8720,12 +8799,25 @@ declare const STALE_LOCK_MAX_AGE_MS: number;
 interface ReposManagerShape {
   readonly status: (root: string) => Effect.Effect<ReposStatusReport, ReposConfigError | GitSubmoduleError>;
   readonly sync: (root: string) => Effect.Effect<ReposSyncReport, ReposConfigError | GitSubmoduleError | ReposLockdownError>;
+  /**
+   * Vendors a new repo.
+   *
+   * `options.orientation` exists so a re-vendor can be LOSSLESS in one call.
+   * Remove-then-re-add is the remedy for several vendored-tree problems, and
+   * without this parameter that remedy silently destroys the entry's
+   * orientation block — the durable, hand-curated part an agent reads to know
+   * where to look in the tree, and the part no report mentions is gone.
+   * Notes are ephemeral by policy and are NOT carried across a re-vendor;
+   * orientation is, when the caller passes it back (see
+   * {@link ReposRemoveResult.removedEntry}, which hands it to them).
+   */
   readonly add: (root: string, options: {
     readonly url: string;
     readonly ref: string;
     readonly purpose: string;
     readonly name?: string;
     readonly sparse?: ReadonlyArray<string>;
+    readonly orientation?: RepoOrientation;
   }) => Effect.Effect<ReposAddResult, ReposConfigError | GitSubmoduleError | ReposLockdownError>;
   readonly pin: (root: string, name: string, ref: string) => Effect.Effect<ReposPinResult, ReposConfigError | GitSubmoduleError | RepoNotFoundError | ReposLockdownError>;
   readonly note: (root: string, name: string, op: {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/silk-effects",
-	"version": "5.5.2",
+	"version": "5.6.0",
 	"private": false,
 	"description": "Shared Effect library for Silk Suite conventions",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/silk-effects",

package/repos/index.js

@@ -5,8 +5,8 @@ import { DriftKind, RepoDrift, ReposDriftReport } from "./schemas/drift.js";
 import { RepoEntry, RepoName, RepoNote, RepoOrientation, ReposManifestFile } from "./schemas/manifest.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 { ReposDrift } from "./services/drift.js";
 import { ReposManager, STALE_LOCK_MAX_AGE_MS } from "./services/manager.js";
 
 //#region src/repos/index.ts

package/repos/schemas/drift.js

@@ -2,9 +2,9 @@ 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`.
+* The kinds of drift {@link ReposDrift} can detect between the five
+* authorities it reconciles: the manifest, `.gitmodules`, the worktree,
+* `git submodule status`, and the superproject's local git config.
 * @public
 */
 const DriftKind = Schema.Literals([
@@ -15,7 +15,9 @@ const DriftKind = Schema.Literals([
 	"missingWorktree",
 	"checkoutDiverged",
 	"missingShallow",
-	"gitmodulesUnparsable"
+	"gitmodulesUnparsable",
+	"localRegistrationDivergence",
+	"nestedSubmoduleDivergence"
 ]);
 /**
 * One detected disagreement between two (or more) of the four authorities

package/repos/schemas/reports.js

@@ -1,4 +1,4 @@
-import { RepoNote } from "./manifest.js";
+import { RepoEntry, RepoNote } from "./manifest.js";
 import { Schema } from "effect";
 
 //#region src/repos/schemas/reports.ts
@@ -7,19 +7,11 @@ import { Schema } from "effect";
 * 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.
+* The gitlink is reported as an index-aware TRIPLE — `stagedCommit` (the
+* index), `committedCommit` (`HEAD`), `checkedOutCommit` (the submodule's own
+* worktree) — because those three legitimately disagree during a pin, and a
+* single field cannot say which one it means. A deprecated `commit` alias of
+* `stagedCommit` bridged one release and is now gone; read `stagedCommit`.
 * @public
 */
 const RepoStatusEntry = Schema.Struct({
@@ -27,8 +19,6 @@ 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`). */
@@ -50,7 +40,8 @@ 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, stale locks cleared, drifted submodule URLs reconciled,
-* and orphan manifest entries (no gitlink at all) registered.
+* orphan manifest entries (no gitlink at all) registered, and the vendored
+* boundary re-declared to git.
 * @public
 */
 const ReposSyncReport = Schema.Struct({
@@ -59,7 +50,15 @@ const ReposSyncReport = Schema.Struct({
 	upToDate: Schema.Array(Schema.String),
 	clearedLocks: Schema.Array(Schema.String),
 	urlSynced: Schema.Array(Schema.String),
-	registered: Schema.Array(Schema.String)
+	registered: Schema.Array(Schema.String),
+	/**
+	* Repos whose `submodule.<path>.update = none` marker was (re-)asserted in
+	* the superproject's local config — the declarative half of the vendored
+	* boundary, telling every git client to skip these trees rather than
+	* letting them discover the boundary by failing against a permission
+	* error.
+	*/
+	boundaryMarked: Schema.Array(Schema.String)
 });
 /**
 * Result of re-pinning a vendored repo to a new ref.
@@ -84,16 +83,31 @@ const ReposAddResult = Schema.Struct({
 });
 /**
 * 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.
+* gitdir, and `.gitmodules` section are all gone, and the entry that was
+* removed is handed back so nothing durable is lost.
+*
+* @remarks
+* `removedEntry` is the whole manifest entry, and it exists because
+* remove-then-re-add is the standing remedy for several vendored-tree
+* problems. `add` does not resurrect anything on its own, so without the
+* entry in hand a caller following that remedy silently destroys the
+* `orientation` block — larger and far harder to reconstruct than the notes,
+* and invisible afterwards in every report an agent would think to check.
+* Pass `removedEntry.orientation` straight back to `add` to make a re-vendor
+* lossless.
+*
+* `removedNotes` is retained alongside it, and is exactly
+* `removedEntry.notes ?? []`. Notes are ephemeral by policy — a last look
+* before they go, so a durable one can be promoted elsewhere — whereas
+* orientation is meant to survive.
 * @public
 */
 const ReposRemoveResult = Schema.Struct({
 	name: Schema.String,
 	path: Schema.String,
 	commitMessage: Schema.String,
-	removedNotes: Schema.Array(RepoNote)
+	removedNotes: Schema.Array(RepoNote),
+	removedEntry: RepoEntry
 });
 /**
 * Result of renaming a vendored repo's manifest key: the `.repos/<name>`
@@ -118,6 +132,13 @@ const ReposRenameResult = Schema.Struct({
 * {@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.
+*
+* `stillDirty` is the honesty channel: a repo that was reset but whose
+* worktree is STILL dirty afterwards. `restored` alone cannot express that —
+* it says what was attempted, not what was achieved — and a caller reading
+* only `restored` would take a report of a repo that never came clean as
+* success. Membership in both `restored` and `stillDirty` is the normal shape
+* for such a repo.
 * @public
 */
 const ReposRestoreResult = Schema.Struct({
@@ -125,7 +146,8 @@ const ReposRestoreResult = Schema.Struct({
 		name: Schema.String,
 		commit: Schema.String
 	})),
-	skippedClean: Schema.Array(Schema.String)
+	skippedClean: Schema.Array(Schema.String),
+	stillDirty: Schema.Array(Schema.String)
 });
 /**
 * Result of an agent-note mutation against a vendored repo.

package/repos/services/drift.js

@@ -2,16 +2,41 @@ 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 { resolveModuleDir } from "./lockdown.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.
+* Extracts the submodule NAME from a `submodule.<name>.<property>` config key.
+*
+* @remarks
+* A submodule's name is routinely a PATH (`git submodule add` derives the
+* section name from the path), so the name itself contains dots — which means
+* the key cannot be split on `.` and read positionally. Strip the fixed
+* `submodule.` prefix and the final `.<property>` segment instead; everything
+* between is the name, dots and all. Returns `undefined` for any key that is
+* not a `submodule.*.*` key.
+*/
+const submoduleNameFromKey = (key) => {
+	if (!key.startsWith("submodule.")) return;
+	const rest = key.slice(10);
+	const lastDot = rest.lastIndexOf(".");
+	return lastDot <= 0 ? void 0 : rest.slice(0, lastDot);
+};
+/**
+* Reconciles the five authorities a vendored repo's state is spread across —
+* the manifest, `.gitmodules`, the worktree, `git submodule status`, and the
+* superproject's LOCAL git config — and reports every disagreement found,
+* including one level down into a vendored repo's own submodules. Read-only:
+* no staging, no lockdown interaction, so it runs unmodified against a locked
+* (`ReposLockdown`) tree.
+*
+* @remarks
+* The local config is the fifth authority because the other four can all
+* agree while a checkout is still REGISTERED under a pre-canonicalization
+* section name — a state that reads clean here while `git submodule status`
+* reports a perfectly healthy checkout as uninitialized.
 * @public
 */
 var ReposDrift = class extends Context.Service()("@savvy-web/silk-effects/ReposDrift") {
@@ -31,6 +56,47 @@ var ReposDrift = class extends Context.Service()("@savvy-web/silk-effects/ReposD
 			reason: error.message
 		});
 		const isPresent = (repoPath) => fs.readDirectory(repoPath).pipe(Effect.map((files) => files.length > 0), Effect.orElseSucceed(() => false));
+		/**
+		* Reconciles the superproject's LOCAL git config for every manifest
+		* entry. Extracted from `check`'s main path so it also runs when
+		* `.gitmodules` is ABSENT: that early return short-circuits the whole
+		* reconciliation, so a repo with no `.gitmodules` but a stale
+		* `submodule.<name>.*` section reported clean while `git submodule
+		* status` still listed the phantom entry.
+		*/
+		const localRegistrationDrifts = (root, manifestEntries) => Effect.gen(function* () {
+			const found = [];
+			const configEntries = yield* git.configList(root).pipe(Effect.mapError(asSubmoduleError("git config --list", root)));
+			const registeredNames = new Set(configEntries.map((configEntry) => submoduleNameFromKey(configEntry.key)).filter((registeredName) => registeredName !== void 0));
+			const modulesRoot = path.join(root, ".git", "modules");
+			const canonicalNames = new Set(manifestEntries.map(([name]) => `${REPOS_DIR}/${name}`));
+			const explained = /* @__PURE__ */ new Set();
+			for (const [name] of manifestEntries) {
+				const expectedPath = `${REPOS_DIR}/${name}`;
+				const moduleDir = yield* resolveModuleDir(fs, path, root, name);
+				const relativeToModules = path.relative(modulesRoot, moduleDir);
+				if (relativeToModules.startsWith("..") || path.isAbsolute(relativeToModules) || relativeToModules === "") continue;
+				if (relativeToModules === expectedPath) continue;
+				explained.add(relativeToModules);
+				found.push(RepoDrift.make({
+					name,
+					kind: "localRegistrationDivergence",
+					detail: `manifest entry "${name}" is canonically "${expectedPath}" but this checkout's module gitdir is registered as "${relativeToModules}"${registeredNames.has(relativeToModules) ? ` (local git config still carries submodule.${relativeToModules}.*)` : ""} — re-vendor the entry to clear it: \`savvy repos remove ${name}\`, then \`savvy repos add\` with the orientation the remove result hands back`,
+					manifestValue: expectedPath,
+					observedValue: relativeToModules
+				}));
+			}
+			for (const registeredName of registeredNames) {
+				if (!registeredName.startsWith(`${".repos"}/`) || canonicalNames.has(registeredName) || explained.has(registeredName)) continue;
+				found.push(RepoDrift.make({
+					name: registeredName,
+					kind: "localRegistrationDivergence",
+					detail: `local git config registers submodule "${registeredName}", which matches no manifest entry — a stale registration left behind by a rename or an unvendoring; clear it with \`git config --remove-section submodule.${registeredName}\``,
+					observedValue: registeredName
+				}));
+			}
+			return found;
+		});
 		const check = (root) => Effect.gen(function* () {
 			const manifest = yield* configStore.read(root);
 			const manifestEntries = Object.entries(manifest.repos);
@@ -43,6 +109,7 @@ var ReposDrift = class extends Context.Service()("@savvy-web/silk-effects/ReposD
 					detail: `manifest entry "${name}" has no corresponding .gitmodules section (.gitmodules is absent)`,
 					manifestValue: entry.url
 				}));
+				drifts.push(...yield* localRegistrationDrifts(root, manifestEntries));
 				return ReposDriftReport.make({
 					drifts,
 					clean: drifts.length === 0
@@ -155,6 +222,21 @@ var ReposDrift = class extends Context.Service()("@savvy-web/silk-effects/ReposD
 					observedValue: section.path
 				}));
 			}
+			drifts.push(...yield* localRegistrationDrifts(root, manifestEntries));
+			for (const [name] of manifestEntries) {
+				const repoPath = path.join(root, REPOS_DIR, name);
+				if (!(yield* isPresent(repoPath))) continue;
+				const nested = yield* git.submoduleStatus(repoPath).pipe(Effect.orElseSucceed(() => []));
+				for (const nestedEntry of nested) {
+					if (nestedEntry.state === "current" || nestedEntry.state === "uninitialized") continue;
+					drifts.push(RepoDrift.make({
+						name,
+						kind: "nestedSubmoduleDivergence",
+						detail: `vendored repo "${name}" has its own submodule "${nestedEntry.path}" checked out at ${nestedEntry.sha}, which does not match what "${name}"'s pinned commit records — reading it would consult a stale authority; \`savvy repos restore ${name}\` deinitializes it`,
+						observedValue: nestedEntry.sha
+					}));
+				}
+			}
 			return ReposDriftReport.make({
 				drifts,
 				clean: drifts.length === 0

package/repos/services/lockdown.js

@@ -22,8 +22,11 @@ const fileModeFor = (baseMode, currentMode) => baseMode | (currentMode & EXEC_BI
 * A submodule worktree's `<root>/.repos/<name>/.git` is normally a FILE
 * containing a single `gitdir: <path>` line pointing at the real metadata
 * directory, which git names after whatever path/name the submodule was
-* REGISTERED under — not necessarily the manifest key (e.g. this repo's own
-* `effect` entry has gitdir `.git/modules/.repos/effect-smol`). This helper
+* REGISTERED under — not necessarily the manifest key. Git never renames
+* that directory, so a manifest entry re-slugged after it was first vendored
+* keeps its original gitdir name indefinitely (manifest key `<new>`, gitdir
+* `.git/modules/.repos/<old>`). `ReposDrift` reports that state as
+* `localRegistrationDivergence`; re-vendoring the entry clears it. This helper
 * reads that pointer and resolves it (relative pointers are relative to the
 * directory containing the `.git` file) so callers always land on the real
 * metadata directory.
@@ -55,6 +58,39 @@ const resolveModuleDir = (fs, path, root, name) => Effect.gen(function* () {
 /**
 * Enforces OS-level read-only permissions on vendored repos so they cannot
 * be accidentally edited outside the sync flow.
+*
+* @remarks
+* SCOPE: the WORKTREE only. The submodule's git metadata directory
+* (`.git/modules/...`) is deliberately NOT locked — `unlock` still walks it
+* so trees locked by an older version are freed, but `lock` never re-locks
+* it. Do not "restore" the metadata lock without re-reading this note.
+*
+* Locking the metadata directory made the boundary enforce itself only via
+* `EACCES`, whose message names neither `.repos/` nor a reason, and it broke
+* every client that needs incidental gitdir writes: a plain `git pull` that
+* moves a gitlink recurses by default and dies writing `FETCH_HEAD`, and any
+* client keeping per-gitdir state (GitKraken writes a `gk/` directory into
+* every gitdir it manages, which no git setting governs) is structurally
+* incompatible with a read-only gitdir. Since vendored reference sources are
+* the overwhelming majority of submodules in this ecosystem, ordinary tooling
+* collided with the lockdown constantly.
+*
+* What the worktree lock still buys, verified against git 2.54:
+*
+* - editing a vendored file fails (`EACCES`) — the property the system
+*   actually needs;
+* - `git reset --hard` inside a vendored tree fails (cannot unlink);
+* - `git checkout <other>` does NOT fail — it moves `HEAD` while leaving the
+*   worktree stale. That is the one guarantee given up here, and it is given
+*   up knowingly: git immediately reports the submodule as `+<oid>`, which
+*   {@link ReposDrift} already classifies as `checkoutDiverged` and
+*   `ReposManager.restore` repairs.
+*
+* So the invariant weakens from "the pin cannot drift" to "a drifted pin is
+* always detected and one command from repaired." The declarative half of the
+* boundary — `submodule.<path>.update = none`, so clients skip these trees
+* rather than discovering the boundary by failing — is asserted by
+* `ReposManager.sync`, not here.
 * @public
 */
 var ReposLockdown = class extends Context.Service()("@savvy-web/silk-effects/ReposLockdown") {
@@ -88,8 +124,9 @@ var ReposLockdown = class extends Context.Service()("@savvy-web/silk-effects/Rep
 			if (order === "lock") yield* chmod(dir, dirMode);
 		});
 		const walkRoot = (root, name, fileBaseMode, dirMode, order) => Effect.gen(function* () {
-			const moduleDir = yield* resolveModuleDir(fs, path, root, name);
-			for (const dir of [path.join(root, REPOS_DIR, name), moduleDir]) {
+			const worktree = path.join(root, REPOS_DIR, name);
+			const targets = order === "unlock" ? [worktree, yield* resolveModuleDir(fs, path, root, name)] : [worktree];
+			for (const dir of targets) {
 				if (!(yield* fs.exists(dir).pipe(Effect.mapError((cause) => new ReposLockdownError({
 					path: dir,
 					reason: `stat failed: ${String(cause)}`

package/repos/services/manager.js

@@ -87,7 +87,6 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 					ref: entry.ref,
 					purpose: entry.purpose,
 					present,
-					commit: stagedCommit ?? null,
 					...stagedCommit !== void 0 ? { stagedCommit } : {},
 					...committedCommit !== void 0 ? { committedCommit } : {},
 					...checkedOutCommit !== void 0 ? { checkedOutCommit } : {},
@@ -108,12 +107,16 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 			const clearedLocks = [];
 			const urlSynced = [];
 			const registered = [];
+			const boundaryMarked = [];
 			const gitmodulesPath = path.join(root, ".gitmodules");
+			yield* git.configSet(root, "fetch.recurseSubmodules", "false").pipe(Effect.mapError(asSubmoduleError("git config fetch.recurseSubmodules false", root)));
 			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* () {
+					const updateKey = `submodule.${repoPathRel}.update`;
+					const assertBoundaryMarker = git.configSet(root, updateKey, "none").pipe(Effect.mapError(asSubmoduleError(`git config ${updateKey} none`, root)));
 					let clearedAnyLock = false;
 					for (const lock of STALE_LOCKS) {
 						const lockPath = path.join(moduleDir, lock);
@@ -155,17 +158,24 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 						yield* git.add(root, [".gitmodules", repoPathRel]).pipe(Effect.mapError(asSubmoduleError(`git add .gitmodules ${repoPathRel}`, root)));
 						registered.push(name);
 					} else if (!present) {
+						yield* git.configSet(root, updateKey, "checkout").pipe(Effect.mapError(asSubmoduleError(`git config ${updateKey} checkout`, root)));
 						yield* git.submoduleUpdate(root, {
 							init: true,
 							depth: 1,
 							paths: [repoPathRel]
-						}).pipe(Effect.mapError(asSubmoduleError(`git submodule update --init --depth 1 -- ${repoPathRel}`, root)));
+						}).pipe(Effect.mapError(asSubmoduleError(`git submodule update --init --depth 1 -- ${repoPathRel}`, root)), Effect.ensuring(Effect.ignore(assertBoundaryMarker)));
 						initialized.push(name);
 					} else upToDate.push(name);
 					if (entry.sparse && entry.sparse.length > 0) {
+						if ((yield* git.submoduleStatus(repoPath).pipe(Effect.orElseSucceed(() => []))).some((nestedEntry) => nestedEntry.state !== "uninitialized")) yield* git.submoduleDeinit(repoPath, {
+							all: true,
+							force: true
+						}).pipe(Effect.mapError(asSubmoduleError("git submodule deinit --all --force", repoPath)));
 						yield* git.sparseCheckoutSet(repoPath, entry.sparse, { cone: false }).pipe(Effect.mapError(asSubmoduleError("git sparse-checkout set --no-cone", repoPath)));
 						sparseApplied.push(name);
 					}
+					yield* assertBoundaryMarker;
+					boundaryMarked.push(name);
 				}));
 			}
 			return {
@@ -174,7 +184,8 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 				upToDate,
 				clearedLocks,
 				urlSynced,
-				registered
+				registered,
+				boundaryMarked
 			};
 		});
 		/** Last path segment of a repo URL, with a trailing `.git` stripped. */
@@ -281,11 +292,14 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 					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));
 			}));
+			yield* git.configSet(root, "fetch.recurseSubmodules", "false").pipe(Effect.mapError(asSubmoduleError("git config fetch.recurseSubmodules false", root)));
+			yield* git.configSet(root, `submodule.${repoPath}.update`, "none").pipe(Effect.mapError(asSubmoduleError(`git config submodule.${repoPath}.update none`, root)));
 			const entry = {
 				url: options.url,
 				ref: options.ref,
 				purpose: options.purpose,
-				...options.sparse && options.sparse.length > 0 ? { sparse: options.sparse } : {}
+				...options.sparse && options.sparse.length > 0 ? { sparse: options.sparse } : {},
+				...options.orientation ? { orientation: options.orientation } : {}
 			};
 			yield* configStore.update(root, (fresh) => ({ repos: {
 				...fresh.repos,
@@ -499,7 +513,8 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 				name,
 				path: repoPath,
 				commitMessage: `chore(repos): remove ${name}`,
-				removedNotes: entry.notes ?? []
+				removedNotes: entry.notes ?? [],
+				removedEntry: entry
 			};
 		});
 		const rename = (root, oldName, newName) => Effect.gen(function* () {
@@ -590,6 +605,7 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 				skippedClean = report.repos.filter((entry) => !entry.dirty).map((entry) => entry.name);
 			}
 			const restored = [];
+			const stillDirty = [];
 			for (const name of targetNames) {
 				const entry = getRepoEntry(manifest.repos, name);
 				if (!entry) return yield* Effect.fail(new RepoNotFoundError({ name }));
@@ -603,22 +619,32 @@ var ReposManager = class extends Context.Service()("@savvy-web/silk-effects/Repo
 						cwd: subPath,
 						reason: `no staged or committed gitlink commit found for "${name}" -- nothing to restore to`
 					}));
+					if ((yield* git.submoduleStatus(subPath).pipe(Effect.orElseSucceed(() => []))).some((nestedEntry) => nestedEntry.state !== "uninitialized")) yield* git.submoduleDeinit(subPath, {
+						all: true,
+						force: true
+					}).pipe(Effect.mapError(asSubmoduleError("git submodule deinit --all --force", subPath)));
 					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;
+					const afterStatus = yield* git.status(subPath).pipe(Effect.mapError(asSubmoduleError("git status --porcelain", subPath)));
+					return {
+						targetCommit,
+						dirty: afterStatus.length > 0
+					};
 				}));
 				restored.push({
 					name,
-					commit
+					commit: commit.targetCommit
 				});
+				if (commit.dirty) stillDirty.push(name);
 			}
 			return {
 				restored,
-				skippedClean
+				skippedClean,
+				stillDirty
 			};
 		});
 		return {