@hasna/instructions 0.4.25 → 0.4.27

package/dist/cli/index.js

@@ -7930,6 +7930,9 @@ function computeProjectContextSourceHash(value) {
   return `sha256:${sha2562(stableStringify(normalized))}`;
 }
 function parseProjectContextBundle(input) {
+  return parseProjectContextBundleInternal(input, true, true);
+}
+function parseProjectContextBundleInternal(input, allowLegacyHash, normalizeLegacyHash = false) {
   let encoded;
   try {
     const serialized = typeof input === "string" ? input : JSON.stringify(input);
@@ -7949,7 +7952,7 @@ function parseProjectContextBundle(input) {
     throw new ProjectContextError("PROJECT_CONTEXT_INVALID", "bundle is not valid JSON");
   }
   const candidateSchema = isRecord(value) ? value["schema"] : undefined;
-  if (typeof candidateSchema === "string" && candidateSchema !== PROJECT_CONTEXT_SCHEMA) {
+  if (typeof candidateSchema === "string" && !PROJECT_CONTEXT_SUPPORTED_SCHEMAS.includes(candidateSchema)) {
     if (/^hasna\.projects\.project_context_bundle\.v[0-9]+$/.test(candidateSchema)) {
       throw new ProjectContextError("PROJECT_CONTEXT_UNSUPPORTED_VERSION", `unsupported bundle schema ${candidateSchema}`);
     }
@@ -7966,10 +7969,11 @@ function parseProjectContextBundle(input) {
   validateIdentityConsistency(bundle);
   rejectCredentialLikeBundle(bundle);
   const expected = computeProjectContextSourceHash(bundle);
-  if (bundle.hash !== expected) {
+  const matchesLegacyHash = bundle.hash !== expected && allowLegacyHash && bundle.hash === computeLegacyProjectContextSourceHash(bundle);
+  if (bundle.hash !== expected && !matchesLegacyHash) {
     throw new ProjectContextError("PROJECT_CONTEXT_HASH_MISMATCH", "bundle hash does not match its canonical allowlisted payload");
   }
-  return bundle;
+  return matchesLegacyHash && normalizeLegacyHash ? { ...bundle, hash: expected } : bundle;
 }
 function planProjectContext(input) {
   const workspaceRoot = assertSafeWorkspaceRoot(input.workspace_root);
@@ -8217,6 +8221,8 @@ function applyProjectContext(options) {
         content: `${JSON.stringify(sessionManifest, null, 2)}
 `
       };
+      const manifestContent = `${JSON.stringify(buildManifest(plan, now3), null, 2)}
+`;
       options.test_hooks?.before_compare?.({ attempt, plan });
       if (!hashesStillMatch(plan.expected_hashes, workspaceRoot)) {
         if (attempt === 0) {
@@ -8229,7 +8235,15 @@ function applyProjectContext(options) {
         return resultForPlan(plan, true, raceRetries, null);
       assertWorkspaceLockHeld(lockPath, lock, workspaceRoot);
       try {
-        snapshotPath = writeMetadataSnapshot(plan, now3);
+        const metadataSnapshotPath = writeMetadataSnapshot(plan, now3);
+        const rollbackSnapshotPath = writeProjectContextRollbackSnapshot(plan, now3, [
+          { path: plan.fragment_path, content: plan.fragment, role: "fragment" },
+          { path: plan.target_path, content: plan.target_content, role: "index" },
+          { path: plan.cache_path, content: cacheContent, role: "config" },
+          { path: sessionOutput.path, content: sessionOutput.content, role: "manifest" },
+          { path: plan.manifest_path, content: manifestContent, role: "manifest" }
+        ]);
+        snapshotPath = rollbackSnapshotPath ?? metadataSnapshotPath;
         atomicWriteFile(plan.fragment_path, plan.fragment, workspaceRoot, 420, expectedPlanHash(plan, plan.fragment_path), undefined, options.test_hooks?.atomic_exchange_unavailable, undefined, options.test_hooks?.portable_create_only);
         options.test_hooks?.after_fragment?.({ attempt, plan });
         assertWorkspaceLockHeld(lockPath, lock, workspaceRoot);
@@ -8243,9 +8257,7 @@ function applyProjectContext(options) {
         options.test_hooks?.before_manifest?.({ attempt, plan });
         assertWorkspaceLockHeld(lockPath, lock, workspaceRoot);
         assertRenderedOutputsStable(plan, cacheContent, sessionOutput);
-        const manifest = buildManifest(plan, now3);
-        atomicWriteFile(plan.manifest_path, `${JSON.stringify(manifest, null, 2)}
-`, workspaceRoot, 384, expectedPlanHash(plan, plan.manifest_path), undefined, options.test_hooks?.atomic_exchange_unavailable, undefined, options.test_hooks?.portable_create_only);
+        atomicWriteFile(plan.manifest_path, manifestContent, workspaceRoot, 384, expectedPlanHash(plan, plan.manifest_path), undefined, options.test_hooks?.atomic_exchange_unavailable, undefined, options.test_hooks?.portable_create_only);
         return resultForPlan(plan, false, raceRetries, snapshotPath);
       } catch (error) {
         if (error instanceof ProjectContextHashRace && attempt === 0) {
@@ -8336,10 +8348,12 @@ function resolveBundleForApply(options, workspaceRoot, now3) {
   if (cache.project_id !== options.expected_project_id || cache.bundle.project.id !== options.expected_project_id) {
     throw new ProjectContextError("PROJECT_CONTEXT_CACHE_ID_MISMATCH", "cached project context belongs to a different project");
   }
-  const bundle = parseProjectContextBundle(cache.bundle);
-  if (bundle.revision !== cache.revision || bundle.hash !== cache.hash) {
+  const cachedBundle = cache.bundle;
+  if (cachedBundle.revision !== cache.revision || cachedBundle.hash !== cache.hash) {
     throw new ProjectContextError("PROJECT_CONTEXT_CACHE_INVALID", "cached revision or hash metadata is inconsistent");
   }
+  const canonicalHash = computeProjectContextSourceHash(cachedBundle);
+  const bundle = cachedBundle.hash === canonicalHash ? cachedBundle : { ...cachedBundle, hash: canonicalHash };
   const ageSeconds = Math.max(staleCacheAgeInSeconds(bundle.generated_at, now3, "bundle generated_at"), staleCacheAgeInSeconds(cache.cached_at, now3, "cache cached_at"));
   const maxAge = normalizeMaxStaleAge(options.max_stale_age_seconds);
   if (ageSeconds > maxAge) {
@@ -8436,11 +8450,13 @@ function parseManagedBlock(content, force) {
   if (structurallyInvalid) {
     if (!force)
       throw new ProjectContextError("MANAGED_BLOCK_INVALID", "managed project-context markers are duplicate, nested, malformed, or unbalanced");
+    const firstMarkerRange = markerCommentRange(markerLines[0]);
+    const lastMarkerRange = markerCommentRange(markerLines[markerLines.length - 1]);
     return {
       block: null,
       forceRange: {
-        start: markerLines[0].start,
-        end: lineContentEnd(markerLines[markerLines.length - 1])
+        start: firstMarkerRange?.start ?? markerLines[0].start,
+        end: lastMarkerRange?.end ?? lineContentEnd(markerLines[markerLines.length - 1])
       }
     };
   }
@@ -8471,6 +8487,21 @@ function parseManagedBlock(content, force) {
     forceRange: null
   };
 }
+function markerCommentRange(line) {
+  const canonicalMarker = line.text.indexOf(PROJECT_CONTEXT_MANAGED_COMMENT);
+  const legacyMarker = /@hasna\/configs project context/i.exec(line.text)?.index ?? -1;
+  const marker = canonicalMarker >= 0 ? canonicalMarker : legacyMarker;
+  if (marker < 0)
+    return null;
+  const commentStart = line.text.lastIndexOf("<!--", marker);
+  const commentEnd = line.text.indexOf("-->", marker);
+  if (commentStart < 0 || commentEnd < 0)
+    return null;
+  return {
+    start: line.start + commentStart,
+    end: line.start + commentEnd + "-->".length
+  };
+}
 function parseMarkerLine(text) {
   const line = text.replace(/[\r\n]+$/, "");
   const canonical = line.match(/^<!-- Managed by @hasna\/configs project context (BEGIN|END) id=([A-Za-z0-9][A-Za-z0-9._:@+-]*) revision=([A-Za-z0-9%._~+-]+) hash=(sha256:[a-f0-9]{64}) -->$/);
@@ -8492,8 +8523,14 @@ function parseMarkerLine(text) {
 }
 function replaceOrAppendManagedBlock(content, block, parsed, legacy) {
   const range = parsed.block ?? parsed.forceRange ?? legacy;
-  if (range)
-    return `${content.slice(0, range.start)}${block}${content.slice(range.end)}`;
+  if (range) {
+    const before = content.slice(0, range.start);
+    const after = content.slice(range.end);
+    const eol2 = preferredEol(content);
+    const beforeSeparator = before && !/[\r\n]$/.test(before) ? eol2 : "";
+    const afterSeparator = after && !/^[\r\n]/.test(after) ? eol2 : "";
+    return `${before}${beforeSeparator}${block}${afterSeparator}${after}`;
+  }
   if (!content)
     return `${block}
 `;
@@ -8537,13 +8574,18 @@ function findLegacyCodewithWorkspaceSection(workspaceRoot, runtime, content, bun
 }
 function assertRevisionOrdering(plan, force) {
   const observations = [];
+  const cache = readProjectContextCache(plan.cache_path, plan.workspace_root);
+  const canonicalCacheHash = cache === null ? null : computeProjectContextSourceHash(cache.bundle);
+  const normalizePersistedHash = (revision, hash) => cache !== null && canonicalCacheHash !== null && revision === cache.revision && hash === cache.hash ? canonicalCacheHash : hash;
   const manifest = readProjectContextManifest(plan.manifest_path, plan.workspace_root);
   if (manifest) {
+    const manifestHashHasRecoveryProof = manifest.projectContext.hash === plan.bundle.hash || metadataSnapshotMatchesManifest(plan, manifest);
+    const canonicalStateAlreadyInstalled = cache !== null && canonicalCacheHash === plan.bundle.hash && cache.project_id === plan.bundle.project.id && cache.revision === plan.bundle.revision && plan.marker !== null && plan.marker.id === plan.bundle.project.id && plan.marker.revision === plan.bundle.revision && plan.marker.hash === plan.bundle.hash && existsSync4(plan.fragment_path) && fragmentMatchesBundle(plan.fragment_path, plan.bundle, plan.workspace_root) && manifestHashHasRecoveryProof;
     observations.push({
       source: "manifest",
       id: manifest.projectContext.projectId,
       revision: manifest.projectContext.revision,
-      hash: manifest.projectContext.hash
+      hash: canonicalStateAlreadyInstalled && manifest.projectContext.projectId === plan.bundle.project.id && manifest.projectContext.revision === plan.bundle.revision ? plan.bundle.hash : normalizePersistedHash(manifest.projectContext.revision, manifest.projectContext.hash)
     });
     const fragmentEntry = manifest.files.find((file) => file.relativePath === PROJECT_CONTEXT_FRAGMENT_PATH);
     if (fragmentEntry && existsSync4(plan.fragment_path)) {
@@ -8553,11 +8595,16 @@ function assertRevisionOrdering(plan, force) {
       }
     }
   }
-  const cache = readProjectContextCache(plan.cache_path, plan.workspace_root);
   if (cache)
-    observations.push({ source: "cache", id: cache.project_id, revision: cache.revision, hash: cache.hash });
-  if (plan.marker)
-    observations.push({ source: "marker", id: plan.marker.id, revision: plan.marker.revision, hash: plan.marker.hash });
+    observations.push({ source: "cache", id: cache.project_id, revision: cache.revision, hash: canonicalCacheHash });
+  if (plan.marker) {
+    observations.push({
+      source: "marker",
+      id: plan.marker.id,
+      revision: plan.marker.revision,
+      hash: normalizePersistedHash(plan.marker.revision, plan.marker.hash)
+    });
+  }
   for (const observation of observations) {
     if (observation.id !== plan.bundle.project.id) {
       throw new ProjectContextError("PROJECT_CONTEXT_IDENTITY_CONFLICT", `${observation.source} belongs to another project`);
@@ -8677,6 +8724,10 @@ function buildSessionCompatibilityManifest(plan, now3) {
   };
   const targetOwner = isRecord(existing["targetOwner"]) ? existing["targetOwner"] : {};
   const adapterMode = plan.native_imports ? "native-imports" : "flattened-markdown";
+  const existingProjectContext = isRecord(existing["projectContext"]) ? existing["projectContext"] : null;
+  const existingProjectContextHash = existingProjectContext === null ? null : safeLegacyMetadataString(existingProjectContext["hash"], null);
+  const existingSourceHash = typeof existing["sourceHash"] === "string" ? existing["sourceHash"] : null;
+  const sourceHash = existingProjectContextHash === plan.bundle.hash && existingSourceHash !== null ? existingSourceHash : sha2562(stableStringify({ previous: existingSourceHash, projectContext: plan.bundle.hash }));
   return credentialSafeSessionManifest({
     schema: SESSION_RENDER_SCHEMA,
     tool,
@@ -8700,7 +8751,7 @@ function buildSessionCompatibilityManifest(plan, now3) {
     blockers: [],
     generatedAt: now3.toISOString(),
     env: sanitizeLegacyEnvironment(existing["env"]),
-    sourceHash: sha2562(stableStringify({ previous: typeof existing["sourceHash"] === "string" ? existing["sourceHash"] : null, projectContext: plan.bundle.hash })),
+    sourceHash,
     sources,
     skippedSources: sanitizeLegacySkippedSources(existing["skippedSources"]),
     files: [...files.filter((file) => file["relativePath"] !== targetRelativePath), updatedTarget],
@@ -8905,7 +8956,7 @@ function projectContextManifestSource(cachePath, runtime, bundle) {
     rules: [],
     renderedPayloadSha256: sha2562(JSON.stringify(bundle)),
     provenance: {
-      schema: PROJECT_CONTEXT_SCHEMA,
+      schema: bundle.schema,
       projectId: bundle.project.id,
       revision: bundle.revision,
       hash: bundle.hash
@@ -8914,7 +8965,7 @@ function projectContextManifestSource(cachePath, runtime, bundle) {
 }
 function manifestProjectContext(plan) {
   return {
-    schema: PROJECT_CONTEXT_SCHEMA,
+    schema: plan.bundle.schema,
     projectId: plan.bundle.project.id,
     revision: plan.bundle.revision,
     hash: plan.bundle.hash,
@@ -8956,6 +9007,77 @@ function writeMetadataSnapshot(plan, now3) {
 `, plan.workspace_root, 384);
   return snapshotPath;
 }
+function metadataSnapshotMatchesManifest(plan, manifest) {
+  const snapshotDir = resolve(plan.workspace_root, ...PROJECT_CONTEXT_SNAPSHOT_DIR.split("/"));
+  const snapshotPath = resolve(snapshotDir, `${safeFilename(manifest.projectContext.revision)}-${manifest.projectContext.hash.slice(-12)}.json`);
+  if (!existsSync4(snapshotPath))
+    return false;
+  const record = readJsonRecord(snapshotPath, plan.workspace_root);
+  const result = projectContextMetadataSnapshotSchema.safeParse(record);
+  if (!result.success)
+    return false;
+  if (result.data.projectId !== manifest.projectContext.projectId || result.data.revision !== manifest.projectContext.revision || result.data.hash !== manifest.projectContext.hash || result.data.status !== manifest.projectContext.status)
+    return false;
+  const sortFiles = (files) => [...files].sort((left, right) => left.relativePath.localeCompare(right.relativePath));
+  const snapshotFiles = sortFiles(result.data.files);
+  const manifestFiles = sortFiles(manifest.files.map((file) => ({
+    relativePath: file.relativePath,
+    role: file.role,
+    sha256: file.sha256
+  })));
+  return JSON.stringify(snapshotFiles) === JSON.stringify(manifestFiles);
+}
+function writeProjectContextRollbackSnapshot(plan, now3, outputs) {
+  const targetExpectedHash = expectedPlanHash(plan, plan.target_path);
+  if (targetExpectedHash === sha2562(plan.target_content))
+    return null;
+  const files = outputs.flatMap((output) => {
+    const expectedHash = expectedPlanHash(plan, output.path);
+    if (expectedHash === null)
+      return [];
+    const content = readUtf8RegularFile(output.path, plan.workspace_root, managedObservationMaxBytes(relativePosix(plan.workspace_root, output.path)));
+    if (sha2562(content) !== expectedHash) {
+      throw new ProjectContextHashRace(`managed path changed while creating rollback evidence: ${relativePosix(plan.workspace_root, output.path)}`);
+    }
+    return [{
+      path: output.path,
+      relativePath: relativePosix(plan.workspace_root, output.path),
+      role: output.role,
+      sha256: expectedHash,
+      content
+    }];
+  });
+  const afterFiles = outputs.map((output) => {
+    const previousHash = expectedPlanHash(plan, output.path);
+    const nextHash = sha2562(output.content);
+    return {
+      path: output.path,
+      relativePath: relativePosix(plan.workspace_root, output.path),
+      role: output.role,
+      action: previousHash === null ? "create" : previousHash === nextHash ? "unchanged" : "update",
+      sha256: nextHash
+    };
+  });
+  const snapshotDir = resolve(plan.workspace_root, ...SESSION_RENDER_SNAPSHOT_RELATIVE_DIR.split("/"));
+  ensureSafeDirectory(snapshotDir, plan.workspace_root, 448);
+  const timestamp = now3.toISOString().replace(/[:.]/g, "-");
+  const snapshotPath = resolve(snapshotDir, `${timestamp}-${randomUUID6()}.json`);
+  const snapshot = {
+    schema: "hasna.configs.session-render-snapshot/v2",
+    createdAt: now3.toISOString(),
+    tool: manifestTool(plan.runtime),
+    profile: "project-context",
+    targetHome: plan.workspace_root,
+    targetKind: "project-root",
+    manifestPath: plan.manifest_path,
+    previousManifest: null,
+    files,
+    afterFiles
+  };
+  atomicWriteFile(snapshotPath, `${JSON.stringify(snapshot, null, 2)}
+`, plan.workspace_root, 384, null);
+  return snapshotPath;
+}
 function readProjectContextManifest(path, workspaceRoot) {
   if (!existsSync4(path))
     return null;
@@ -8979,7 +9101,7 @@ function readProjectContextCache(path, workspaceRoot) {
   if (!result.success) {
     throw new ProjectContextError("PROJECT_CONTEXT_CACHE_INVALID", "cache is malformed or incompatible");
   }
-  const bundle = parseProjectContextBundle(result.data.bundle);
+  const bundle = parseProjectContextBundleInternal(result.data.bundle, true);
   if (result.data.project_id !== bundle.project.id || result.data.revision !== bundle.revision || result.data.hash !== bundle.hash) {
     throw new ProjectContextError("PROJECT_CONTEXT_CACHE_INVALID", "cache metadata does not match its bundle");
   }
@@ -10292,23 +10414,36 @@ function removeHashForFingerprint(value) {
     return value;
   const copy = {};
   for (const [key, item] of Object.entries(value)) {
-    if (key === "hash")
+    if (key === "generated_at" || key === "hash")
       continue;
     copy[key] = item;
   }
   return copy;
 }
+function computeLegacyProjectContextSourceHash(value) {
+  if (!isRecord(value))
+    return `sha256:${sha2562(stableStringify(value))}`;
+  const copy = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (key === "hash")
+      continue;
+    copy[key] = item;
+  }
+  return `sha256:${sha2562(stableStringify(copy))}`;
+}
 function sha2562(content) {
   return createHash2("sha256").update(content).digest("hex");
 }
 function isRecord(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
-var PROJECT_CONTEXT_SCHEMA = "hasna.projects.project_context_bundle.v1", PROJECT_CONTEXT_MAX_INPUT_BYTES, PROJECT_CONTEXT_MAX_RENDERED_BYTES, PROJECT_CONTEXT_MAX_APPROX_TOKENS = 1000, PROJECT_CONTEXT_MAX_COMMANDS = 6, PROJECT_CONTEXT_MAX_WARNINGS = 3, PROJECT_CONTEXT_FRAGMENT_PATH = ".hasna/instructions/project-context.md", PROJECT_CONTEXT_MANIFEST_PATH = ".hasna/project-context-manifest.json", PROJECT_CONTEXT_CACHE_PATH = ".hasna/project-context-cache.json", PROJECT_CONTEXT_LOCK_PATH = ".hasna/project-context.lock", PROJECT_CONTEXT_SNAPSHOT_DIR = ".hasna/project-context-snapshots", PROJECT_CONTEXT_CACHE_SCHEMA = "hasna.instructions.project-context-cache/v1", PROJECT_CONTEXT_MANAGED_COMMENT = "Managed by @hasna/configs project context", SESSION_COMPATIBILITY_MANIFEST_MAX_BYTES, FOREIGN_INPUT_MAX_BYTES, SESSION_MANAGED_OUTPUT_MAX_BYTES, SESSION_MANAGED_INPUT_MAX_BYTES, SESSION_MANAGED_OUTPUT_PATHS, SESSION_MANAGED_OUTPUT_WARN_BYTES, PROJECT_CONTEXT_LOCK_STALE_MS, LEGACY_CONFIGS_PACKAGE = "@hasna/configs", LEGACY_CONFIGS_COMPAT_VERSION = "0.2.45", LEGACY_CONFIGS_EXECUTABLE = "configs", PROJECT_KINDS, PROJECT_STATUSES, LINK_STATES, RESOLUTION_SOURCES, safeId, nullableId, producerSlug, producerName, safeOptionalDisplay, isoTimestamp, revisionSchema, hashSchema, absolutePath, commandArg, commandSchema, projectContextBundleSchema, storedManifestProjectContextSchema, storedManifestFileSchema, storedManifestObservationSchema, projectContextCacheSchema, ProjectContextError, ProjectContextHashRace, anchoredFsOps, atomicExchange, atomicExchangeLibraries;
+var PROJECT_CONTEXT_SCHEMA = "hasna.projects.project_context_bundle.v1", PROJECT_CONTEXT_SCHEMA_V2 = "hasna.projects.project_context_bundle.v2", PROJECT_CONTEXT_SUPPORTED_SCHEMAS, projectContextSchema, PROJECT_CONTEXT_MAX_INPUT_BYTES, PROJECT_CONTEXT_MAX_RENDERED_BYTES, PROJECT_CONTEXT_MAX_APPROX_TOKENS = 1000, PROJECT_CONTEXT_MAX_COMMANDS = 6, PROJECT_CONTEXT_MAX_WARNINGS = 3, PROJECT_CONTEXT_FRAGMENT_PATH = ".hasna/instructions/project-context.md", PROJECT_CONTEXT_MANIFEST_PATH = ".hasna/project-context-manifest.json", PROJECT_CONTEXT_CACHE_PATH = ".hasna/project-context-cache.json", PROJECT_CONTEXT_LOCK_PATH = ".hasna/project-context.lock", PROJECT_CONTEXT_SNAPSHOT_DIR = ".hasna/project-context-snapshots", PROJECT_CONTEXT_CACHE_SCHEMA = "hasna.instructions.project-context-cache/v1", PROJECT_CONTEXT_MANAGED_COMMENT = "Managed by @hasna/configs project context", SESSION_COMPATIBILITY_MANIFEST_MAX_BYTES, FOREIGN_INPUT_MAX_BYTES, SESSION_MANAGED_OUTPUT_MAX_BYTES, SESSION_MANAGED_INPUT_MAX_BYTES, SESSION_MANAGED_OUTPUT_PATHS, SESSION_MANAGED_OUTPUT_WARN_BYTES, PROJECT_CONTEXT_LOCK_STALE_MS, LEGACY_CONFIGS_PACKAGE = "@hasna/configs", LEGACY_CONFIGS_COMPAT_VERSION = "0.2.45", LEGACY_CONFIGS_EXECUTABLE = "configs", PROJECT_KINDS, PROJECT_STATUSES, LINK_STATES, RESOLUTION_SOURCES, safeId, nullableId, producerSlug, producerName, safeOptionalDisplay, isoTimestamp, revisionSchema, hashSchema, absolutePath, commandArg, commandSchema, projectContextBundleSchema, storedManifestProjectContextSchema, storedManifestFileSchema, storedManifestObservationSchema, projectContextMetadataSnapshotSchema, projectContextCacheSchema, ProjectContextError, ProjectContextHashRace, anchoredFsOps, atomicExchange, atomicExchangeLibraries;
 var init_project_context = __esm(() => {
   init_zod();
   init_redact();
   init_session_render_contract();
+  PROJECT_CONTEXT_SUPPORTED_SCHEMAS = [PROJECT_CONTEXT_SCHEMA, PROJECT_CONTEXT_SCHEMA_V2];
+  projectContextSchema = exports_external.enum(PROJECT_CONTEXT_SUPPORTED_SCHEMAS);
   PROJECT_CONTEXT_MAX_INPUT_BYTES = 8 * 1024;
   PROJECT_CONTEXT_MAX_RENDERED_BYTES = 4 * 1024;
   SESSION_COMPATIBILITY_MANIFEST_MAX_BYTES = 8 * 1024 * 1024;
@@ -10356,7 +10491,7 @@ var init_project_context = __esm(() => {
     argv: exports_external.array(commandArg).min(1).max(8)
   }).strict();
   projectContextBundleSchema = exports_external.object({
-    schema: exports_external.literal(PROJECT_CONTEXT_SCHEMA),
+    schema: projectContextSchema,
     generated_at: isoTimestamp,
     hash: hashSchema,
     revision: revisionSchema,
@@ -10404,7 +10539,7 @@ var init_project_context = __esm(() => {
     commands: exports_external.array(commandSchema).max(PROJECT_CONTEXT_MAX_COMMANDS)
   }).strict();
   storedManifestProjectContextSchema = exports_external.object({
-    schema: exports_external.literal(PROJECT_CONTEXT_SCHEMA),
+    schema: projectContextSchema,
     projectId: safeId,
     revision: revisionSchema,
     hash: hashSchema,
@@ -10444,6 +10579,25 @@ var init_project_context = __esm(() => {
       });
     }
   });
+  projectContextMetadataSnapshotSchema = exports_external.object({
+    schema: exports_external.literal("hasna.configs.session-render-snapshot/v1"),
+    kind: exports_external.literal("project-context-metadata"),
+    createdAt: isoTimestamp,
+    projectId: safeId,
+    revision: revisionSchema,
+    hash: hashSchema,
+    status: exports_external.enum(["fresh", "stale-source", "stale-cache"]),
+    files: exports_external.array(exports_external.object({
+      relativePath: exports_external.enum([
+        PROJECT_CONTEXT_FRAGMENT_PATH,
+        "CLAUDE.md",
+        ".codewith/CODEWITH.md",
+        "AGENTS.md"
+      ]),
+      role: exports_external.enum(["fragment", "index"]),
+      sha256: exports_external.string().regex(/^[a-f0-9]{64}$/)
+    }).strict()).min(1).max(2)
+  }).strict();
   projectContextCacheSchema = exports_external.object({
     schema: exports_external.literal(PROJECT_CONTEXT_CACHE_SCHEMA),
     cached_at: isoTimestamp,
@@ -10656,10 +10810,13 @@ function sourceFingerprint(source) {
     metadata: canonicalFingerprintValue(source.metadata ?? null)
   };
 }
-function slug(value) {
+function normalizeSessionInstructionSourceId(value) {
   const s = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
   return s || "instruction";
 }
+function slug(value) {
+  return normalizeSessionInstructionSourceId(value);
+}
 function yamlQuote2(value) {
   return `"${value.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
 }
@@ -10778,12 +10935,17 @@ function normalizeSources(sources, tool, allowEmptySources) {
     }
     return normalized2;
   });
+  const originalOrder = [...normalized].sort(compareSessionInstructionSources);
   const deduplicated = deduplicateSemanticPolicySources(normalized);
-  const ordered = deduplicated.selected.sort((a, b) => SESSION_LAYER_RANK[a.resolvedLayer] - SESSION_LAYER_RANK[b.resolvedLayer] || a.resolvedOrder - b.resolvedOrder || a.id.localeCompare(b.id));
+  const ordered = deduplicated.selected.sort(compareSessionInstructionSources);
+  validateTargetedReplacementSources(originalOrder, ordered, deduplicated.skipped);
   rejectDuplicateSourceSlugs(ordered);
   rejectDuplicateRulePaths(ordered);
   return { sources: ordered, skipped: deduplicated.skipped };
 }
+function compareSessionInstructionSources(a, b) {
+  return SESSION_LAYER_RANK[a.resolvedLayer] - SESSION_LAYER_RANK[b.resolvedLayer] || a.resolvedOrder - b.resolvedOrder || a.id.localeCompare(b.id);
+}
 function semanticPolicyIntegrity(body) {
   return sha2563(body) === AGENT_OPERATING_RULES_PAYLOAD_SHA256 ? "pinned-digest" : "unverified-self-declared";
 }
@@ -10910,7 +11072,52 @@ function filterProviderOnlyBlocks(content, tool) {
   return output.join(`
 `);
 }
-function composeSources(sources) {
+function targetedReplacementTarget(source) {
+  if (source.replacementScope == null)
+    return null;
+  if (source.resolvedMerge !== "replace") {
+    throw new Error(`Session instruction source "${source.id}" uses replacement scope "${source.replacementScope}" ` + `with merge=${source.resolvedMerge}; replacement scopes require merge=replace, not append.`);
+  }
+  const scope = source.replacementScope.trim();
+  if (!scope.startsWith("source:")) {
+    throw new Error(`Invalid replacement scope "${source.replacementScope}" for source "${source.id}"; ` + 'expected "source:<normalized-source-id>".');
+  }
+  const target = scope.slice("source:".length);
+  if (!target || target !== slug(target)) {
+    throw new Error(`Invalid replacement scope "${source.replacementScope}" for source "${source.id}"; ` + "the target must be a non-empty normalized source id.");
+  }
+  return target;
+}
+function validateTargetedReplacementSources(originalSources, selectedSources, deduplicatedSources) {
+  for (let replacerIndex = 0;replacerIndex < originalSources.length; replacerIndex++) {
+    const replacer = originalSources[replacerIndex];
+    const targetNormalizedId = targetedReplacementTarget(replacer);
+    if (targetNormalizedId === null)
+      continue;
+    const matches = originalSources.filter((source) => source.normalizedId === targetNormalizedId);
+    if (matches.length === 0) {
+      throw new Error(`Targeted replacement source "${replacer.id}" names missing source "${targetNormalizedId}".`);
+    }
+    if (matches.length > 1) {
+      throw new Error(`Targeted replacement source "${replacer.id}" is ambiguous after normalization: ` + `"${targetNormalizedId}" matches ${matches.map((source) => `"${source.id}"`).join(", ")}.`);
+    }
+    const target = matches[0];
+    const targetIndex = originalSources.indexOf(target);
+    if (targetIndex >= replacerIndex) {
+      throw new Error(`Targeted replacement source "${replacer.id}" must name an earlier source; ` + `"${target.id}" is later than or identical to the replacer.`);
+    }
+    if (target.nonOverridable) {
+      throw new Error(`Targeted replacement source "${replacer.id}" cannot replace non-overridable source "${target.id}".`);
+    }
+    if (!selectedSources.some((source) => source.id === replacer.id)) {
+      throw new Error(`Targeted replacement source "${replacer.id}" was removed by semantic-policy deduplication before composition.`);
+    }
+    if (deduplicatedSources.some((source) => source.id === target.id)) {
+      throw new Error(`Targeted replacement source "${replacer.id}" cannot claim success because target "${target.id}" ` + "was removed by semantic-policy deduplication before composition.");
+    }
+  }
+}
+function composeBroadReplaceSources(sources) {
   let start = -1;
   for (let i = 0;i < sources.length; i++) {
     if (sources[i].resolvedMerge === "replace")
@@ -10924,6 +11131,53 @@ function composeSources(sources) {
   const skipped = earlier.filter((source) => !source.nonOverridable).map((source) => skippedSource(source, `superseded by "${replacer.id}": a replace-merge source discards earlier overridable instruction layers`));
   return { sources: [...protectedSources, ...sources.slice(start)], skipped };
 }
+function composeSources(sources) {
+  const hasTargetedReplacement = sources.some((source) => source.replacementScope !== undefined);
+  if (!hasTargetedReplacement)
+    return composeBroadReplaceSources(sources);
+  const selected = [];
+  const skipped = [];
+  for (const source of sources) {
+    const targetNormalizedId = targetedReplacementTarget(source);
+    if (targetNormalizedId !== null) {
+      const targetIndex = selected.findIndex((candidate) => candidate.normalizedId === targetNormalizedId);
+      if (targetIndex < 0) {
+        throw new Error(`Targeted replacement source "${source.id}" cannot replace "${targetNormalizedId}": ` + "the earlier target was already removed.");
+      }
+      const target = selected[targetIndex];
+      if (target.nonOverridable) {
+        throw new Error(`Targeted replacement source "${source.id}" cannot replace non-overridable source "${target.id}".`);
+      }
+      selected.splice(targetIndex, 1);
+      skipped.push(skippedSource(target, `superseded by "${source.id}": targeted replacement ${source.replacementScope} ` + `removed exactly source "${target.id}"`));
+      selected.push({
+        ...source,
+        provenance: {
+          ...source.provenance ?? {},
+          targetedReplacement: {
+            scope: source.replacementScope,
+            targetSourceId: target.id,
+            targetNormalizedSourceId: target.normalizedId
+          }
+        }
+      });
+      continue;
+    }
+    if (source.resolvedMerge === "replace") {
+      const retained = selected.filter((candidate) => candidate.nonOverridable);
+      for (const candidate of selected) {
+        if (candidate.nonOverridable)
+          continue;
+        skipped.push(skippedSource(candidate, `superseded by "${source.id}": a replace-merge source discards earlier overridable instruction layers`));
+      }
+      selected.length = 0;
+      selected.push(...retained, source);
+      continue;
+    }
+    selected.push(source);
+  }
+  return { sources: selected, skipped };
+}
 function sectionForSource(source) {
   const parts = [
     `<!-- ${SESSION_RENDER_MANAGED_MARKER}. Do not edit this generated file directly. -->`,
@@ -15764,7 +16018,7 @@ function parseSessionLayer(value) {
     return value;
   throw new Error(`Invalid source layer "${value}"`);
 }
-function parseSessionSource(value, order, replaceIds) {
+function parseSessionSource(value, order) {
   const idx = value.indexOf("=");
   let id = idx > 0 ? value.slice(0, idx).trim() : "";
   const path = idx > 0 ? value.slice(idx + 1).trim() : value.trim();
@@ -15787,9 +16041,39 @@ function parseSessionSource(value, order, replaceIds) {
     id: resolvedId,
     label: id ? resolvedId : source.label ?? resolvedId,
     layer,
-    merge: replaceIds.has(resolvedId) ? "replace" : "append"
+    merge: "append"
   };
 }
+function parseSessionSourceReplacement(value) {
+  const trimmed = value.trim();
+  const separator = trimmed.indexOf("=");
+  const replacerId = (separator >= 0 ? trimmed.slice(0, separator) : trimmed).trim();
+  if (!replacerId) {
+    throw new Error(`Invalid --replace-source "${value}" (expected replacer-id or replacer-id=target-source-id)`);
+  }
+  if (separator < 0)
+    return { replacerId };
+  const targetId = trimmed.slice(separator + 1).trim();
+  if (!targetId) {
+    throw new Error(`Invalid --replace-source "${value}" (target source id is required after "=")`);
+  }
+  return {
+    replacerId,
+    replacementScope: `source:${normalizeSessionInstructionSourceId(targetId)}`
+  };
+}
+function sessionSourceReplacements(values) {
+  const replacements = new Map;
+  for (const value of values) {
+    const replacement = parseSessionSourceReplacement(value);
+    const existing = replacements.get(replacement.replacerId);
+    if (existing && existing.replacementScope !== replacement.replacementScope) {
+      throw new Error(`Conflicting --replace-source values for "${replacement.replacerId}": ` + `${existing.replacementScope ?? "broad"} and ${replacement.replacementScope ?? "broad"}.`);
+    }
+    replacements.set(replacement.replacerId, replacement);
+  }
+  return replacements;
+}
 function readSessionInstructionSourceFile(path) {
   const stat = lstatSync4(path);
   if (stat.isSymbolicLink()) {
@@ -15820,8 +16104,8 @@ function parseLayeredReference(value) {
   return { id: trimmed };
 }
 async function collectSessionSources(opts, tool, store) {
-  const replaceIds = new Set(opts.replaceSource ?? []);
-  const sources = (opts.source ?? []).map((value, index) => parseSessionSource(value, index, replaceIds));
+  const replacements = sessionSourceReplacements(opts.replaceSource ?? []);
+  const sources = (opts.source ?? []).map((value, index) => parseSessionSource(value, index));
   for (const value of opts.config ?? []) {
     const { layer, id } = parseLayeredReference(value);
     sources.push(sourceFromConfig(await store.getConfig(id), sources.length, layer));
@@ -15833,7 +16117,16 @@ async function collectSessionSources(opts, tool, store) {
     const parsed = JSON.parse(readFileSync12(path, "utf-8"));
     sources.push(...sourcesFromIdentityExport(parsed, { path, tool, orderOffset: sources.length }));
   }
-  return sources.map((source) => replaceIds.has(source.id) ? { ...source, merge: "replace" } : source);
+  return sources.map((source) => {
+    const replacement = replacements.get(source.id);
+    if (!replacement)
+      return source;
+    return {
+      ...source,
+      merge: "replace",
+      replacementScope: replacement.replacementScope
+    };
+  });
 }
 async function checkGlobalSourceCoverage(plan, store) {
   const registryConfigs = await store.listConfigs({});
@@ -16576,7 +16869,7 @@ projectContextCmd.command("apply").description("Atomically write project context
   }
 });
 var sessionCmd = program.command("session").description("Plan and apply session-scoped agent instruction files");
-sessionCmd.command("plan").description("Produce a dry-run render plan for profile-scoped instruction injection").requiredOption("--tool <tool>", `target tool (${SESSION_RENDER_TOOLS.join("|")})`).requiredOption("--profile <profile>", "account/profile name that owns the rendered instruction home").option("--target-home <path>", "override generated profile-scoped target home").option("--project-root <path>", "repository root for project-scoped adapters such as Cursor").option("--session-id <id>", "session id to include in the manifest").option("--source <layer:id=path>", `instruction source file; layers: ${SESSION_SOURCE_LAYER_HELP}`, collectOption, []).option("--config <layer:id-or-slug>", "stored config source by id/slug; repeatable; layer aliases match --source", collectOption, []).option("--identity-export <path>", "OpenIdentities configs instruction export JSON; repeatable", collectOption, []).option("--replace-source <id>", "source id that replaces earlier layers instead of appending", collectOption, []).option("--codewith-native-imports", "select the gated Codewith native @ import adapter").option("--allow-empty-sources", "allow an explicit empty render plan").option("--check-global-coverage", "warn (non-fatal) when a registered, non-retired global-* source is absent from this render's --config list; expected is read fresh from the registry, independent of this plan (todos 102d6d0a)").option("--json", "output dry-run JSON").action(async (opts) => {
+sessionCmd.command("plan").description("Produce a dry-run render plan for profile-scoped instruction injection").requiredOption("--tool <tool>", `target tool (${SESSION_RENDER_TOOLS.join("|")})`).requiredOption("--profile <profile>", "account/profile name that owns the rendered instruction home").option("--target-home <path>", "override generated profile-scoped target home").option("--project-root <path>", "repository root for project-scoped adapters such as Cursor").option("--session-id <id>", "session id to include in the manifest").option("--source <layer:id=path>", `instruction source file; layers: ${SESSION_SOURCE_LAYER_HELP}`, collectOption, []).option("--config <layer:id-or-slug>", "stored config source by id/slug; repeatable; layer aliases match --source", collectOption, []).option("--identity-export <path>", "OpenIdentities configs instruction export JSON; repeatable", collectOption, []).option("--replace-source <replacer-id>[=<target-source-id>]", "source id that broadly replaces earlier layers, or targets one earlier source", collectOption, []).option("--codewith-native-imports", "select the gated Codewith native @ import adapter").option("--allow-empty-sources", "allow an explicit empty render plan").option("--check-global-coverage", "warn (non-fatal) when a registered, non-retired global-* source is absent from this render's --config list; expected is read fresh from the registry, independent of this plan (todos 102d6d0a)").option("--json", "output dry-run JSON").action(async (opts) => {
   try {
     const tool = opts.tool;
     if (!SESSION_RENDER_TOOLS.includes(tool)) {
@@ -16632,7 +16925,7 @@ sessionCmd.command("plan").description("Produce a dry-run render plan for profil
     process.exit(1);
   }
 });
-sessionCmd.command("apply").description("Write a session render plan to its managed target home or explicit project root").requiredOption("--tool <tool>", `target tool (${SESSION_RENDER_TOOLS.join("|")})`).requiredOption("--profile <profile>", "account/profile name that owns the rendered instruction home").option("--target-home <path>", "override generated profile-scoped target home").option("--project-root <path>", "repository root for project-scoped adapters such as Cursor").option("--session-id <id>", "session id to include in the manifest").option("--source <layer:id=path>", `instruction source file; layers: ${SESSION_SOURCE_LAYER_HELP}`, collectOption, []).option("--config <layer:id-or-slug>", "stored config source by id/slug; repeatable; layer aliases match --source", collectOption, []).option("--identity-export <path>", "OpenIdentities configs instruction export JSON; repeatable", collectOption, []).option("--replace-source <id>", "source id that replaces earlier layers instead of appending", collectOption, []).option("--codewith-native-imports", "select the gated Codewith native @ import adapter").option("--allow-empty-sources", "allow an explicit empty render").option("--check-global-coverage", "warn (non-fatal) when a registered, non-retired global-* source is absent from this render's --config list; expected is read fresh from the registry, independent of this plan (todos 102d6d0a)").option("--dry-run", "preview writes and conflicts without writing").option("--force", "overwrite existing unmanaged files").option("--json", "output apply JSON").action(async (opts) => {
+sessionCmd.command("apply").description("Write a session render plan to its managed target home or explicit project root").requiredOption("--tool <tool>", `target tool (${SESSION_RENDER_TOOLS.join("|")})`).requiredOption("--profile <profile>", "account/profile name that owns the rendered instruction home").option("--target-home <path>", "override generated profile-scoped target home").option("--project-root <path>", "repository root for project-scoped adapters such as Cursor").option("--session-id <id>", "session id to include in the manifest").option("--source <layer:id=path>", `instruction source file; layers: ${SESSION_SOURCE_LAYER_HELP}`, collectOption, []).option("--config <layer:id-or-slug>", "stored config source by id/slug; repeatable; layer aliases match --source", collectOption, []).option("--identity-export <path>", "OpenIdentities configs instruction export JSON; repeatable", collectOption, []).option("--replace-source <replacer-id>[=<target-source-id>]", "source id that broadly replaces earlier layers, or targets one earlier source", collectOption, []).option("--codewith-native-imports", "select the gated Codewith native @ import adapter").option("--allow-empty-sources", "allow an explicit empty render").option("--check-global-coverage", "warn (non-fatal) when a registered, non-retired global-* source is absent from this render's --config list; expected is read fresh from the registry, independent of this plan (todos 102d6d0a)").option("--dry-run", "preview writes and conflicts without writing").option("--force", "overwrite existing unmanaged files").option("--json", "output apply JSON").action(async (opts) => {
   try {
     const tool = opts.tool;
     if (!SESSION_RENDER_TOOLS.includes(tool)) {
@@ -17325,7 +17618,7 @@ program.command("watch").description("Watch known config files for changes and a
   setInterval(tick, interval);
   await new Promise(() => {});
 });
-program.command("report").description("Summary of stored configs, drift, and ecosystem health").option("--json", "output as JSON").option("--markdown", "output as markdown").action(async () => {
+program.command("report").description("Summary of stored configs, drift, and ecosystem health").option("--json", "output as JSON").option("--markdown", "output as markdown").action(async (opts) => {
   const store = resolveConfigStore();
   const stats = await store.getConfigStats();
   const allConfigs = await store.listConfigs();
@@ -17351,6 +17644,32 @@ program.command("report").description("Summary of stored configs, drift, and eco
   for (const c of allConfigs)
     byAgent[c.agent] = (byAgent[c.agent] || 0) + 1;
   const projectConfigs = allConfigs.filter((c) => c.target_path && !c.target_path.startsWith("~/."));
+  if (opts.json) {
+    printJson({
+      schema_version: 1,
+      configs: {
+        total: allConfigs.length,
+        files: fileConfigs.length,
+        references: refConfigs.length,
+        templates: templates.length,
+        project: projectConfigs.length
+      },
+      profiles: {
+        total: profiles.length
+      },
+      drift: {
+        drifted,
+        missing
+      },
+      secrets: {
+        findings: 0,
+        policy: "redacted_on_ingest"
+      },
+      by_agent: byAgent,
+      by_category: Object.fromEntries(Object.entries(stats).filter(([key]) => key !== "total").map(([key, value]) => [key, Number(value)]))
+    });
+    return;
+  }
   console.log(chalk.bold(`configs report
 `));
   console.log(`  Total:       ${allConfigs.length} configs (${fileConfigs.length} files, ${refConfigs.length} references)`);