agentwheel 0.20.7 → 0.20.9

package/README.md

@@ -396,6 +396,37 @@ current directory, then fallback to the current directory. `--all-detected` is a
 for applying to every runtime marker found in the current directory or `--target-root`; `--all` remains
 reserved for configured agents.
 
+### Target state identity
+
+Graph-backed installs keep two target fingerprints with different purposes:
+
+- The full target fingerprint records rendering inputs in the graph lock. Adapter code, adapter
+  configuration, and adapter module changes therefore remain visible and can produce a real update.
+- The stable state fingerprint selects the graph lock, install manifest, source lock, and apply
+  journal. It is derived from the contribution scope and effective destination, including the
+  normalized install root and a structured local or SSH endpoint. Adapter implementation evolution
+  that resolves to the same destination reuses the installed state instead of orphaning it.
+
+Changing an artifact destination within the same effective install root is handled as a planned
+transition from the old path to the new path. Changing the effective install root, local/SSH kind, or
+SSH endpoint selects a different target state. SSH state identity requires an explicit host; a display
+label is not endpoint identity.
+
+State created by an older Agentwheel release may be named with the full target fingerprint. For a
+local target, Agentwheel adopts that state only when one canonical graph lock, its v2 install
+manifest, the contribution owner, target details, and graph-lock digest all agree. A supported
+install or uninstall carries an explicit migration and revalidates the old and new state under the
+shared apply lock before replacing the legacy paths. An explicit `stateKey` remains the manifest and
+source-lock key while its legacy graph-lock path moves. Ownership handoff and retirement require a
+full install to migrate first. Status, dependency inspection, uninstall, and journal commands use
+the same discovery rules.
+
+Agentwheel refuses ambiguous candidates, a graph lock without its correlated manifest, or
+disagreeing stable and legacy state, and preserves those files for manual reconciliation. A pending
+apply journal that embeds and exactly correlates the missing manifest and graph state remains
+discoverable for recovery. Legacy SSH state is also preserved and refused because the old records do
+not prove which endpoint owned it.
+
 ## Core Ideas
 
 **Three places, one direction:**

package/dist/{apply-OEKVIYBV.js → apply-JBULQGW5.js}

@@ -5,8 +5,8 @@ import {
   commitManifestMetadataJournal,
   recoverPendingApply,
   uninstall
-} from "./chunk-4AM3LNUQ.js";
-import "./chunk-JXX6EDIP.js";
+} from "./chunk-E7Z2YB2C.js";
+import "./chunk-SHPNLNBR.js";
 import "./chunk-7VPI5J5Y.js";
 export {
   applyCombinedInstallPlan,

package/dist/{chunk-4AM3LNUQ.js → chunk-E7Z2YB2C.js}

@@ -24,7 +24,7 @@ import {
   rollbackCompletedOperations,
   sourceLockPath,
   writeApplyJournal
-} from "./chunk-JXX6EDIP.js";
+} from "./chunk-SHPNLNBR.js";
 import {
   pathExists,
   writeJsonAtomic
@@ -32,9 +32,10 @@ import {
 
 // src/install/apply.ts
 import { execFile } from "child_process";
+import { createHash as createHash4 } from "crypto";
 import { mkdtemp as mkdtemp2, readFile as readFile8, rm as rm2, writeFile as writeFile8 } from "fs/promises";
 import { tmpdir as tmpdir2 } from "os";
-import { basename as basename2, dirname as dirname8, join as join3 } from "path";
+import { basename as basename2, dirname as dirname8, join as join3, resolve as resolve3 } from "path";
 import { promisify } from "util";
 
 // src/model/graph-lock.ts
@@ -572,6 +573,9 @@ async function computeInstallManifestInventoryRevision(targetRoot, adapter, tran
   const inventory = (await listInstallManifests(targetRoot, adapter, transport)).map((item) => [item.fileName, item.manifest.revision]);
   return createHash2("sha256").update(JSON.stringify(inventory)).digest("hex");
 }
+function computeSourceLockRevision(lock) {
+  return lock ? createHash2("sha256").update(canonicalJson(lock)).digest("hex") : null;
+}
 async function writeInstallManifest(manifest, transport = localTransport) {
   const next = withManifestRevision(manifest);
   await transport.writeJsonAtomic(installManifestPath(next.targetRoot, next.adapter, {
@@ -582,6 +586,11 @@ async function writeInstallManifest(manifest, transport = localTransport) {
 async function writeSourceLock(targetRoot, adapter, lock, transport = localTransport, scope = {}) {
   await transport.writeJsonAtomic(sourceLockPath(targetRoot, adapter, scope), lock);
 }
+async function readSourceLock(targetRoot, adapter, transport = localTransport, scope = {}) {
+  const path = sourceLockPath(targetRoot, adapter, scope);
+  if (!await transport.pathExists(path)) return void 0;
+  return sourceLockSchema.parse(JSON.parse(await transport.readFile(path)));
+}
 async function removeStateFiles(targetRoot, adapter, transport = localTransport, scope = {}) {
   await transport.rm(installManifestPath(targetRoot, adapter, scope));
   await transport.rm(sourceLockPath(targetRoot, adapter, scope));
@@ -1442,6 +1451,8 @@ async function applyPlanTransactionally(plan, options = {}) {
     await assertRuntimeJournalGate(plan.targetRoot, plan.adapter, transport, scope);
     await assertRuntimeStateRevision(plan, transport);
     await assertBaseRevision(plan, transport);
+    await assertTargetStateFilePreconditions(plan, transport, options.graphLock?.path);
+    await assertStateMigrationPreconditions(plan, transport);
     const now = (/* @__PURE__ */ new Date()).toISOString();
     const graphLockDigest = options.graphLockDigest ?? plan.graphLockDigest;
     const mutation = mutationMetadataForApplyJournal();
@@ -1470,9 +1481,11 @@ async function applyPlanTransactionally(plan, options = {}) {
         adapterCode: plan.adapterCode,
         entries: []
       },
-      sourceLock: options.sourceLock,
+      sourceLock: options.sourceLock ?? plan.stateMigration?.sourceLock ?? void 0,
       graphLockPath: options.graphLock?.path,
-      graphLock: options.graphLock?.lock
+      graphLock: options.graphLock?.lock,
+      graphLockRemovePath: plan.stateMigration && plan.stateMigration.fromGraphLockPath !== options.graphLock?.path ? plan.stateMigration.fromGraphLockPath : void 0,
+      stateRemoveKey: plan.stateMigration?.fromStateKey !== plan.stateKey ? plan.stateMigration?.fromStateKey : void 0
     };
     await writeApplyJournal(journal, transport);
     const entries = [];
@@ -1549,6 +1562,8 @@ async function uninstall(plan, options = {}) {
     await assertRuntimeJournalGate(plan.targetRoot, plan.adapter, transport, scope);
     await assertRuntimeStateRevision(plan, transport);
     await assertBaseRevision(plan, transport);
+    await assertTargetStateFilePreconditions(plan, transport, resolvedOptions.graphLock?.path);
+    await assertStateMigrationPreconditions(plan, transport);
     await assertExactMergeRemovalPreconditions(removable, transport);
     const revalidatedSkips = /* @__PURE__ */ new Map();
     for (const operation of skipped) {
@@ -1581,9 +1596,11 @@ async function uninstall(plan, options = {}) {
       operations: resolvedOptions.keepFiles ? [] : removable,
       completed: [],
       manifest: finalManifest,
+      sourceLock: plan.stateMigration?.sourceLock ?? void 0,
       graphLockPath: resolvedOptions.graphLock?.path,
       graphLock: resolvedOptions.graphLock?.lock,
-      graphLockRemovePath: resolvedOptions.removeGraphLockPath,
+      graphLockRemovePath: resolvedOptions.removeGraphLockPath ?? (plan.stateMigration?.fromGraphLockPath !== resolvedOptions.graphLock?.path ? plan.stateMigration?.fromGraphLockPath : void 0),
+      stateRemoveKey: plan.stateMigration?.fromStateKey !== plan.stateKey ? plan.stateMigration?.fromStateKey : void 0,
       workspaceConfigPath: resolvedOptions.workspaceConfig?.path,
       workspaceConfig: resolvedOptions.workspaceConfig?.data
     };
@@ -1633,6 +1650,12 @@ async function commitJournalState(journal, transport, entries, now) {
     await writeInstallManifest(manifest, transport);
   }
   if (journal.graphLockPath && journal.graphLock) await writeGraphLock(journal.graphLockPath, journal.graphLock);
+  if (journal.stateRemoveKey && journal.stateRemoveKey !== journal.stateKey) {
+    await removeStateFiles(journal.targetRoot, journal.adapter, transport, {
+      installationType: journal.installationType,
+      stateKey: journal.stateRemoveKey
+    });
+  }
   if (journal.graphLockRemovePath) {
     declareMutationPath(journal.graphLockRemovePath);
     await rm2(journal.graphLockRemovePath, { force: true });
@@ -1680,6 +1703,15 @@ async function assertCommittedJournalState(journal, expectedManifest, transport)
   if (journal.graphLockRemovePath && await pathExists(journal.graphLockRemovePath)) {
     throw new Error(`Graph-lock removal postcheck failed for ${journal.graphLockRemovePath}.`);
   }
+  if (journal.stateRemoveKey && journal.stateRemoveKey !== journal.stateKey) {
+    const removedScope = { installationType: journal.installationType, stateKey: journal.stateRemoveKey };
+    if (await readInstallManifest(journal.targetRoot, journal.adapter, transport, removedScope)) {
+      throw new Error(`Legacy manifest removal postcheck failed for state ${journal.stateRemoveKey}.`);
+    }
+    if (await readSourceLock(journal.targetRoot, journal.adapter, transport, removedScope)) {
+      throw new Error(`Legacy source-lock removal postcheck failed for state ${journal.stateRemoveKey}.`);
+    }
+  }
   if (journal.workspaceConfigPath && journal.workspaceConfig) {
     const actual = JSON.parse(await readFile8(journal.workspaceConfigPath, "utf8"));
     if (canonicalJson2(actual) !== canonicalJson2(journal.workspaceConfig)) {
@@ -1811,6 +1843,16 @@ async function applyOperation(operation, context) {
     if (!operation.manifestHash || !operation.desiredHash) {
       throw new Error(`Invalid keep operation missing manifest/source hash: ${operation.relativeDestPath}`);
     }
+    if (operation.preserveInManifest === false) {
+      if (!await transport.pathExists(operation.destPath)) {
+        throw new Error(`Foreign keep destination disappeared after planning: ${operation.relativeDestPath}`);
+      }
+      const currentHash = await transport.hashPath(operation.destPath);
+      if (currentHash !== operation.currentHash || currentHash !== operation.manifestHash || currentHash !== operation.desiredHash) {
+        throw new Error(`Foreign keep destination changed after planning: ${operation.relativeDestPath}`);
+      }
+      return void 0;
+    }
     return manifestEntryForOperation(operation, {
       now,
       hash: operation.manifestHash,
@@ -2117,13 +2159,80 @@ function manifestEntryForOperation(operation, values) {
 async function assertBaseRevision(plan, transport) {
   const current = await readInstallManifest(plan.targetRoot, plan.adapter, transport, {
     installationType: plan.installationType,
-    stateKey: plan.stateKey
+    stateKey: plan.stateMigration?.fromStateKey ?? plan.stateKey
   });
   const currentRevision = current?.revision ?? null;
   if (currentRevision !== plan.baseRevision) {
     throw new Error(`Install manifest changed since planning for ${plan.adapter}; replan needed`);
   }
 }
+async function assertTargetStateFilePreconditions(plan, transport, graphLockWritePath) {
+  const expected = plan.targetStateFilePreconditions;
+  if (!expected) return;
+  if (graphLockWritePath && resolve3(graphLockWritePath) !== resolve3(expected.graphLockPath)) {
+    throw new Error(
+      `Graph-lock destination changed after planning: expected ${expected.graphLockPath}, found ${graphLockWritePath}; replan needed.`
+    );
+  }
+  let graphLockRevision = null;
+  if (await pathExists(expected.graphLockPath)) {
+    try {
+      const graphLock = await readGraphLock(expected.graphLockPath);
+      graphLockRevision = createHash4("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
+    } catch (error) {
+      throw new Error(
+        `Destination graph lock changed after planning at ${expected.graphLockPath}; replan needed: ` + (error instanceof Error ? error.message : String(error))
+      );
+    }
+  }
+  if (graphLockRevision !== expected.graphLockRevision) {
+    throw new Error(
+      `Destination graph lock changed after planning: expected ${expected.graphLockRevision ?? "missing"}, found ${graphLockRevision ?? "missing"}; replan needed.`
+    );
+  }
+  let sourceLockRevision;
+  try {
+    sourceLockRevision = computeSourceLockRevision(await readSourceLock(plan.targetRoot, plan.adapter, transport, {
+      installationType: plan.installationType,
+      stateKey: plan.stateKey
+    }));
+  } catch (error) {
+    throw new Error(
+      `Destination source lock changed after planning for ${plan.adapter}; replan needed: ` + (error instanceof Error ? error.message : String(error))
+    );
+  }
+  if (sourceLockRevision !== expected.sourceLockRevision) {
+    throw new Error(
+      `Destination source lock changed after planning: expected ${expected.sourceLockRevision ?? "missing"}, found ${sourceLockRevision ?? "missing"}; replan needed.`
+    );
+  }
+}
+async function assertStateMigrationPreconditions(plan, transport) {
+  const migration = plan.stateMigration;
+  if (!migration) return;
+  let graphLock;
+  try {
+    graphLock = await readGraphLock(migration.fromGraphLockPath);
+  } catch (error) {
+    throw new Error(
+      `Legacy graph lock changed since planning at ${migration.fromGraphLockPath}; replan needed: ` + (error instanceof Error ? error.message : String(error))
+    );
+  }
+  const graphDigest = createHash4("sha256").update(canonicalGraphLockJson(graphLock)).digest("hex");
+  if (graphDigest !== migration.fromGraphLockDigest) {
+    throw new Error(
+      `Legacy graph lock changed since planning: expected ${migration.fromGraphLockDigest}, found ${graphDigest}; replan needed.`
+    );
+  }
+  if (!migration.fromStateKey) return;
+  const currentSourceLock = await readSourceLock(plan.targetRoot, plan.adapter, transport, {
+    installationType: plan.installationType,
+    stateKey: migration.fromStateKey
+  });
+  if (canonicalJson2(currentSourceLock ?? null) !== canonicalJson2(migration.sourceLock ?? null)) {
+    throw new Error(`Legacy source lock changed since planning for ${plan.adapter}; replan needed.`);
+  }
+}
 async function assertExactMergeRemovalPreconditions(operations, transport) {
   for (const operation of operations) {
     if (!operation.exactMergeRemoval) continue;
@@ -2283,11 +2392,14 @@ export {
   canonicalizeGraphLock,
   computeTargetFingerprint,
   legacyUnownedWorkspaceOwner,
+  installManifestV2Schema,
   installManifestSchema,
   readInstallManifest,
   listInstallManifests,
   computeInstallManifestInventoryRevision,
+  computeSourceLockRevision,
   writeInstallManifest,
+  readSourceLock,
   normalizeTargetRoot,
   withManifestRevision,
   computeManifestRevision,