@piagent/platform 1.1.6 → 1.1.8

package/packages/piagent-core/capabilities/project-profile.js

@@ -0,0 +1,83 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// A project profile can either state its whole policy or name the adapter it
+// takes that policy from.
+//
+// Stating the whole policy freezes it. The adapters ship with the platform and
+// are corrected by it, but a project that copied one at onboarding time keeps
+// the copy forever, so a global update leaves every existing project on the old
+// rules. `extends` makes the policy a reference instead: the project keeps the
+// parts that are about the project, and the installed platform supplies the
+// rest.
+//
+// Profiles written before this existed carry no `extends` and keep working
+// exactly as they did, self-contained.
+
+const ADAPTER_NAME = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+export class ProjectProfileError extends Error {}
+
+export function adapterProfileFile(platformRoot, name) {
+  if (typeof name !== "string") return undefined;
+  const trimmed = name.trim();
+  // The name indexes a directory inside the installed platform, so it is
+  // restricted to a plain slug rather than sanitised after the fact.
+  if (!ADAPTER_NAME.test(trimmed)) return undefined;
+  const candidate = path.join(platformRoot, "adapters", trimmed, "profile.json");
+  return fs.existsSync(candidate) ? candidate : undefined;
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolve a stored project profile document against the installed adapters.
+ * Returns the document to enforce, plus the adapter it came from when one was
+ * named. Any key the project states replaces the adapter's key whole — there is
+ * no per-entry merging of lists, because a half-merged protectedPaths is harder
+ * to reason about than a stated one.
+ */
+export function resolveProjectProfileDocument(platformRoot, stored) {
+  if (!stored || typeof stored !== "object" || Array.isArray(stored)) {
+    return { profile: stored, base: undefined };
+  }
+  if (stored.extends === undefined) return { profile: stored, base: undefined };
+
+  const file = adapterProfileFile(platformRoot, stored.extends);
+  if (!file) {
+    throw new ProjectProfileError(
+      `project profile extends "${String(stored.extends)}", which is not an adapter in the installed platform`
+    );
+  }
+  const adapter = readJson(file);
+  if (!adapter) throw new ProjectProfileError(`adapter profile is unreadable: ${file}`);
+
+  const { extends: base, ...overrides } = stored;
+  return { profile: { ...adapter, ...overrides }, base };
+}
+
+export function readProjectProfileDocument(platformRoot, profilePath) {
+  const stored = readJson(profilePath);
+  if (stored === undefined) return { stored: undefined, profile: undefined, base: undefined };
+  const { profile, base } = resolveProjectProfileDocument(platformRoot, stored);
+  return { stored, profile, base };
+}
+
+/**
+ * The document a project stores when it takes its policy from an adapter: what
+ * identifies this project, and nothing the platform already knows.
+ */
+export function buildExtendingProfile(base, projectId, displayName) {
+  return {
+    schemaVersion: 1,
+    extends: base,
+    projectId,
+    displayName
+  };
+}

package/packages/piagent-core/extensions/piagent-guard.ts

@@ -40,9 +40,12 @@ import {
   redactSensitiveText
 } from "./redaction-core.js";
 import { detectProfileName } from "./project-shape.js";
+import { evaluateUpdateCheck, readUpdateCache, startUpdateProbe } from "./update-check.js";
+import { buildExtendingProfile, resolveProjectProfileDocument } from "../capabilities/project-profile.js";
 import {
   resolveCapabilityProfileDocument,
   verifyCapabilityLock,
+  writeJsonAtomic,
   writeProfileLockAtomic
 } from "../capabilities/capability-core.js";
 import { resolveCapabilitySourceRoots } from "../capabilities/capability-sources.js";
@@ -417,6 +420,28 @@ const DEFAULT_POLICY: BasePolicy = {
   orchestrationPolicy: DEFAULT_ORCHESTRATION_POLICY
 };
 
+// Which platform supplies the adapters is fixed by where this file is installed,
+// so it is resolved once here rather than threaded through every profile load.
+const PLATFORM_ROOT = findPlatformRoot(path.dirname(fileURLToPath(import.meta.url)));
+const UPDATE_CHECK_MODULE = fileURLToPath(new URL("./update-check.js", import.meta.url));
+
+// The installed version, read from the package this file ships in. A maintainer
+// working in the repository is not running a release and has nothing to update
+// to, so the checkout is recognised by the one thing a published copy never
+// carries and told nothing.
+function installedPlatformVersion(): string | undefined {
+  if (fs.existsSync(path.join(PLATFORM_ROOT, ".git"))) return undefined;
+  return readJsonFile<{ version?: string }>(path.join(PLATFORM_ROOT, "package.json"))?.version;
+}
+
+function updateAvailabilityNotice(): string | undefined {
+  const installed = installedPlatformVersion();
+  if (!installed) return undefined;
+  const decision = evaluateUpdateCheck({ installed, cache: readUpdateCache(), now: Date.now() });
+  if (decision.probe) startUpdateProbe(UPDATE_CHECK_MODULE);
+  return decision.notice;
+}
+
 function loadPolicy(extensionDir: string): BasePolicy {
   const root = findPackageRoot(extensionDir);
   return readJsonFile<BasePolicy>(path.join(root, "policies", "base-policy.json")) ?? DEFAULT_POLICY;
@@ -433,17 +458,38 @@ function fallbackProfile(cwd: string, mode = "unprofiled"): ProjectProfile {
   };
 }
 
+// A profile that names an adapter this platform does not have cannot be
+// enforced, and the unprofiled shape carries no readOnlyPaths — falling back to
+// it would quietly hand write access to whatever the profile was protecting. The
+// session stays readable and says why instead.
+function unresolvedProfile(cwd: string, reason: string): ProjectProfile {
+  return {
+    ...fallbackProfile(cwd, "unresolved-profile-base"),
+    permissionProfile: "read-only",
+    unresolvedReason: reason
+  } as ProjectProfile;
+}
+
+function resolveStoredProfile(stored: ProjectProfile | undefined, cwd: string, missingMode: string): ProjectProfile {
+  if (!stored) return fallbackProfile(cwd, missingMode);
+  try {
+    return resolveProjectProfileDocument(PLATFORM_ROOT, stored).profile as ProjectProfile;
+  } catch (error) {
+    return unresolvedProfile(cwd, error instanceof Error ? error.message : String(error));
+  }
+}
+
 function loadProfile(cwd: string, projectTrusted = false): ProjectProfile {
   const explicit = process.env.PIAGENT_PROFILE;
   if (explicit && explicit.trim().length > 0) {
-    return readJsonFile<ProjectProfile>(explicit) ?? fallbackProfile(cwd, "explicit-profile-unreadable");
+    return resolveStoredProfile(readJsonFile<ProjectProfile>(explicit), cwd, "explicit-profile-unreadable");
   }
 
   if (!projectTrusted) {
     return fallbackProfile(cwd, "unprofiled-global-package");
   }
 
-  return readJsonFile<ProjectProfile>(path.join(cwd, ".pi", "piagent-profile.json")) ?? fallbackProfile(cwd, projectTrusted ? "unprofiled" : "unprofiled-global-package");
+  return resolveStoredProfile(readJsonFile<ProjectProfile>(path.join(cwd, ".pi", "piagent-profile.json")), cwd, "unprofiled");
 }
 
 function loadProfileFromContext(ctx: ExtensionContext): ProjectProfile {
@@ -530,6 +576,7 @@ function capabilitySourceRoots(
 type ProjectCapabilityState = {
   ok: boolean;
   reason?: string;
+  repinned?: string;
   filesystemRead?: string[];
   filesystemWrite?: string[];
 };
@@ -539,8 +586,18 @@ function verifyProjectCapabilityState(extensionDir: string, cwd: string, project
   if (!projectTrusted) return { ok: true };
   const profilePath = projectProfilePath(cwd);
   if (!fs.existsSync(profilePath)) return { ok: true };
-  const profile = readJsonFile<ProjectProfile>(profilePath);
-  if (!profile || !Array.isArray(profile.capabilityPacks)) return { ok: true };
+  // Which packs a project selects can come from the adapter it extends, so the
+  // question has to be asked of the resolved document. Asking the stored one
+  // would skip the lock entirely for every project that references an adapter.
+  const stored = readJsonFile<ProjectProfile>(profilePath);
+  if (!stored) return { ok: true };
+  let profile: ProjectProfile;
+  try {
+    profile = resolveProjectProfileDocument(PLATFORM_ROOT, stored).profile as ProjectProfile;
+  } catch (error) {
+    return { ok: false, reason: error instanceof Error ? error.message : String(error) };
+  }
+  if (!Array.isArray(profile.capabilityPacks)) return { ok: true };
   const lockPath = path.join(cwd, ".pi", "piagent-profile.lock.json");
   if (!fs.existsSync(lockPath)) return { ok: false, reason: "Capability lock is missing. Reapply the project profile." };
   const lock = readJsonFile<Record<string, unknown>>(lockPath);
@@ -550,13 +607,30 @@ function verifyProjectCapabilityState(extensionDir: string, cwd: string, project
       packageSource: projectPackageSource(cwd),
       extraRoots: capabilitySourceRoots(cwd, profile)
     });
-    return verification.ok
-      ? {
-          ok: true,
-          filesystemRead: verification.expected.permissions.filesystemRead,
-          filesystemWrite: verification.expected.permissions.filesystemWrite
-        }
-      : { ok: false, reason: "Capability lock does not match the active profile, package source, or installed platform." };
+    if (verification.status === "blocked") {
+      return {
+        ok: false,
+        reason: `Capability lock does not match what this project agreed to: ${verification.reasons.join("; ")}. Reapply the project profile.`
+      };
+    }
+    const granted = {
+      filesystemRead: verification.expected.permissions.filesystemRead,
+      filesystemWrite: verification.expected.permissions.filesystemWrite
+    };
+    if (verification.status !== "repin") return { ok: true, ...granted };
+
+    // The grant is unchanged and only the platform build moved. Record the new
+    // build instead of stopping the session, which is what turned every release
+    // into a chore in every project.
+    try {
+      writeJsonAtomic(lockPath, verification.expected);
+    } catch (error) {
+      return {
+        ok: false,
+        reason: `Capability lock is behind the installed platform and could not be rewritten: ${error instanceof Error ? error.message : String(error)}`
+      };
+    }
+    return { ok: true, repinned: verification.reasons.join("; "), ...granted };
   } catch (error) {
     return { ok: false, reason: `Capability validation failed: ${error instanceof Error ? error.message : String(error)}` };
   }
@@ -2854,12 +2928,18 @@ function buildTechStackManifest(profileName: string, selectedOptions: TechOption
   };
 }
 
+// `profile` is the document the project stores. When it names an adapter, the
+// lock is resolved against that adapter but still records the stored document,
+// so a later platform correction is not a lock the project has to re-agree to.
 function writeProfileDocumentWithLock(extensionDir: string, cwd: string, profile: ProjectProfile): ProjectProfile {
   const target = projectProfilePath(cwd);
-  const capabilityLock = resolveCapabilityProfileDocument(findPlatformRoot(extensionDir), profile, {
+  const platformRoot = findPlatformRoot(extensionDir);
+  const resolved = resolveProjectProfileDocument(platformRoot, profile).profile as ProjectProfile;
+  const capabilityLock = resolveCapabilityProfileDocument(platformRoot, resolved, {
     profileFile: "piagent-profile.json",
+    storedProfile: profile,
     packageSource: projectPackageSource(cwd),
-    extraRoots: capabilitySourceRoots(cwd, profile)
+    extraRoots: capabilitySourceRoots(cwd, resolved)
   });
   fs.mkdirSync(path.dirname(target), { recursive: true });
   writeProfileLockAtomic(target, profile, path.join(cwd, ".pi", "piagent-profile.lock.json"), capabilityLock);
@@ -2909,7 +2989,7 @@ function writeTechStackSelection(
   };
   writeProfileDocumentWithLock(extensionDir, cwd, profile);
   ensureProjectContextPlaceholder(cwd);
-  return { profile, manifest };
+  return { profile: resolveProjectProfileDocument(findPlatformRoot(extensionDir), profile).profile as ProjectProfile, manifest };
 }
 
 function normalizeTechSelections(cwd: string, profileName: string, selections: Record<string, unknown> = {}, fillRecommended = true): {
@@ -3033,20 +3113,24 @@ function buildProfileFromAdapter(extensionDir: string, cwd: string, profileName:
   const profile = readJsonFile<ProjectProfile>(source);
   if (!profile) throw new Error(`Profile unreadable: ${profileName}`);
   const projectName = path.basename(cwd);
-  return {
-    ...profile,
-    projectId: projectId ? slugify(projectId) : slugify(projectName),
-    displayName: displayName?.trim() || titleize(projectName)
-  };
+  // The project records which adapter it follows, not a copy of that adapter's
+  // rules. A copy stops receiving corrections the moment it is written.
+  return buildExtendingProfile(
+    profileName,
+    projectId ? slugify(projectId) : slugify(projectName),
+    displayName?.trim() || titleize(projectName)
+  ) as ProjectProfile;
 }
 
 function writeProfileFromAdapter(extensionDir: string, cwd: string, profileName: string, overwrite = false, projectId?: string, displayName?: string): ProjectProfile {
   const target = projectProfilePath(cwd);
   if (fs.existsSync(target) && !overwrite) throw new Error(".pi/piagent-profile.json already exists. Pass overwrite=true to replace it.");
-  const personalized = buildProfileFromAdapter(extensionDir, cwd, profileName, projectId, displayName);
-  writeProfileDocumentWithLock(extensionDir, cwd, personalized);
+  const stored = buildProfileFromAdapter(extensionDir, cwd, profileName, projectId, displayName);
+  writeProfileDocumentWithLock(extensionDir, cwd, stored);
   ensureProjectContextPlaceholder(cwd);
-  return personalized;
+  // Store the reference, hand back the document it resolves to: callers report
+  // and trace what is now in force, not the four lines that point at it.
+  return resolveProjectProfileDocument(findPlatformRoot(extensionDir), stored).profile as ProjectProfile;
 }
 
 function readTask(cwd: string, taskId: string): TaskContract | undefined {
@@ -3659,12 +3743,19 @@ export default function piagentGuard(pi: ExtensionAPI) {
     const permissionHint = ` permission=${permissionProfile.mode}`;
     ctx.ui.notify(`Piagent Pi guard loaded: ${name}${profileHint}${permissionHint}${contextHint}`, preflight.recommendation === "fresh-session" ? "warning" : "info");
     if (!capabilityState.ok) ctx.ui.notify(capabilityState.reason ?? "Capability validation failed.", "warning");
+    if (capabilityState.repinned) {
+      ctx.ui.notify(`Capability lock re-pinned: ${capabilityState.repinned}. The capabilities this project grants are unchanged.`, "info");
+    }
     const legacyWarning = legacyProjectStateWarning(ctx.cwd);
     if (legacyWarning) ctx.ui.notify(legacyWarning, "warning");
     if (permissionProfile.warning) ctx.ui.notify(permissionProfile.warning, "warning");
     if (permissionProfile.mode === "trusted-full-access") {
       ctx.ui.notify("Piagent permission profile trusted-full-access is active; protected paths, secret redaction, and destructive/external confirmations remain enforced.", "warning");
     }
+    // Last, so a release announcement never pushes a security warning out of
+    // the first thing the operator reads.
+    const updateNotice = updateAvailabilityNotice();
+    if (updateNotice) ctx.ui.notify(updateNotice, "info");
   });
 
   pi.on("input", async (event, ctx) => {
@@ -4675,10 +4766,12 @@ export default function piagentGuard(pi: ExtensionAPI) {
       entry.context7.digest = snapshot.digest;
       manifest.updatedAt = nowIso();
       fs.writeFileSync(techStackPath(ctx.cwd), `${JSON.stringify(manifest, null, 2)}\n`);
-      const profile = loadProfileFromContext(ctx);
-      if (profile.techStack) {
-        profile.techStack.updatedAt = manifest.updatedAt;
-        writeProfileDocumentWithLock(extensionDir, ctx.cwd, profile);
+      // Write back the document the project stores, not the resolved one: saving
+      // the resolved copy would inline the adapter and stop it following.
+      const stored = readJsonFile<ProjectProfile>(projectProfilePath(ctx.cwd));
+      if (stored?.techStack) {
+        stored.techStack.updatedAt = manifest.updatedAt;
+        writeProfileDocumentWithLock(extensionDir, ctx.cwd, stored);
       }
       appendTrace(ctx.cwd, { event: "profile_tech_context_record", techId, role: entry.role, libraryId: snapshot.resolvedLibraryId });
       appendSessionTrace(pi, { event: "profile_tech_context_record", techId, role: entry.role, libraryId: snapshot.resolvedLibraryId });

package/packages/piagent-core/extensions/update-check.js

@@ -0,0 +1,170 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+// Telling someone a new release exists is only useful if it costs them nothing.
+// A session start that waits on the registry pays a network round trip every
+// time Pi opens, for information that changes a few times a month, so the check
+// never runs in the session's path: the session reads a cache file and, when
+// that cache is old, leaves a detached process behind to refresh it. The notice
+// lands on this session if the cache already knew, and on the next one if it did
+// not.
+//
+// Everything read here comes from outside the process — a registry response and
+// a file any local process can write — so the only value that ever reaches the
+// terminal is a version string that matched RELEASE_VERSION. A registry that
+// answers with a sentence, or a cache someone edited to carry one, produces no
+// notice rather than a line of attacker-chosen text in the operator's terminal.
+
+const HELPER_PACKAGE = "@piagent/platform";
+const CACHE_FILE = "piagent-update-check.json";
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const PROBE_TIMEOUT_MS = 10_000;
+const MAX_CACHE_BYTES = 4096;
+const RELEASE_VERSION = /^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/;
+
+/** @param {string} [home] @returns {string|undefined} */
+export function updateCacheFile(home) {
+  const base = home ?? os.homedir();
+  if (typeof base !== "string" || base.length === 0) return undefined;
+  return path.join(base, ".pi", CACHE_FILE);
+}
+
+/**
+ * A release version and nothing else. Prereleases and build metadata are
+ * rejected rather than parsed: this decides what to tell someone to install, and
+ * nudging an operator onto a prerelease is not what the notice is for.
+ * @param {unknown} value @returns {string|undefined}
+ */
+export function releaseVersion(value) {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return RELEASE_VERSION.test(trimmed) ? trimmed : undefined;
+}
+
+/**
+ * Compare two release versions numerically. `1.1.10` is after `1.1.9`, which
+ * string ordering gets backwards.
+ * @param {string} left @param {string} right @returns {number}
+ */
+export function compareReleaseVersions(left, right) {
+  const leftParts = left.split(".").map(Number);
+  const rightParts = right.split(".").map(Number);
+  for (let index = 0; index < 3; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] < rightParts[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+/** @param {string} [home] @returns {{latest?: string, checkedAt?: number}} */
+export function readUpdateCache(home) {
+  const file = updateCacheFile(home);
+  if (!file) return {};
+  try {
+    // A cache larger than this is not something this code wrote.
+    if (fs.statSync(file).size > MAX_CACHE_BYTES) return {};
+    const document = JSON.parse(fs.readFileSync(file, "utf8"));
+    const checkedAt = Date.parse(document?.checkedAt);
+    return {
+      latest: releaseVersion(document?.latest),
+      checkedAt: Number.isFinite(checkedAt) ? checkedAt : undefined
+    };
+  } catch {
+    return {};
+  }
+}
+
+/** @param {string|undefined} home @param {string} latest @param {number} now @returns {boolean} */
+export function writeUpdateCache(home, latest, now) {
+  const file = updateCacheFile(home);
+  const version = releaseVersion(latest);
+  if (!file || !version) return false;
+  const document = {
+    schemaVersion: 1,
+    package: HELPER_PACKAGE,
+    latest: version,
+    checkedAt: new Date(now).toISOString()
+  };
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, `${JSON.stringify(document, null, 2)}\n`);
+    fs.renameSync(temporary, file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * What the session should do about updates, decided from state alone so it can
+ * be tested without a registry or a clock.
+ * @param {{installed?: string, cache?: {latest?: string, checkedAt?: number}, now: number, env?: Record<string, string|undefined>}} options
+ * @returns {{notice?: string, probe: boolean}}
+ */
+export function evaluateUpdateCheck(options) {
+  const env = options.env ?? process.env;
+  if (env.PIAGENT_NO_UPDATE_CHECK?.trim()) return { probe: false };
+
+  const installed = releaseVersion(options.installed);
+  const cache = options.cache ?? {};
+  const latest = releaseVersion(cache.latest);
+  const probe = !(typeof cache.checkedAt === "number" && options.now - cache.checkedAt < CACHE_TTL_MS);
+
+  if (!installed || !latest || compareReleaseVersions(latest, installed) <= 0) return { probe };
+  return {
+    probe,
+    notice: `Piagent update available: ${installed} -> ${latest}. Run \`piagent-update\` to move this machine to it.`
+  };
+}
+
+/**
+ * Leave the refresh behind and return. The child is detached with no inherited
+ * stdio, so nothing it does can hold the session open or write into the
+ * terminal.
+ * @param {string} moduleFile @param {{spawn?: typeof spawn}} [options]
+ * @returns {boolean}
+ */
+export function startUpdateProbe(moduleFile, options = {}) {
+  try {
+    const child = (options.spawn ?? spawn)(process.execPath, [moduleFile, "--probe"], {
+      detached: true,
+      stdio: "ignore",
+      windowsHide: true
+    });
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** @returns {string|undefined} */
+function fetchLatestVersion() {
+  const result = spawnSync("npm", ["view", HELPER_PACKAGE, "version", "--json"], {
+    encoding: "utf8",
+    timeout: PROBE_TIMEOUT_MS,
+    windowsHide: true
+  });
+  if (result.status !== 0 || typeof result.stdout !== "string") return undefined;
+  try {
+    return releaseVersion(JSON.parse(result.stdout));
+  } catch {
+    return undefined;
+  }
+}
+
+/** @param {{now?: number, home?: string, fetch?: () => string|undefined}} [options] @returns {boolean} */
+export function runUpdateProbe(options = {}) {
+  const latest = (options.fetch ?? fetchLatestVersion)();
+  // A registry that could not be reached leaves the cache alone, so the next
+  // session retries instead of recording "no update" as if it had been checked.
+  if (!latest) return false;
+  return writeUpdateCache(options.home, latest, options.now ?? Date.now());
+}
+
+if (process.argv[2] === "--probe" && process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  runUpdateProbe();
+}

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.1.6",
+  "version": "1.1.8",
   "type": "module",
   "private": true,
   "license": "MIT",

package/schemas/project-profile.schema.json

@@ -6,19 +6,37 @@
   "required": [
     "schemaVersion",
     "projectId",
-    "displayName",
-    "mode",
-    "rootMarkers",
-    "protectedPaths",
-    "requiredContext",
-    "verifyCommands",
-    "mcpCapabilities"
+    "displayName"
   ],
+  "if": {
+    "required": [
+      "extends"
+    ]
+  },
+  "then": {
+    "description": "A profile that names an adapter stores identity plus overrides. Every policy field it omits comes from the installed adapter at runtime, so none of them are required here."
+  },
+  "else": {
+    "required": [
+      "mode",
+      "rootMarkers",
+      "protectedPaths",
+      "requiredContext",
+      "verifyCommands",
+      "mcpCapabilities"
+    ]
+  },
   "properties": {
     "schemaVersion": {
       "type": "integer",
       "const": 1
     },
+    "extends": {
+      "description": "Name of a built-in adapter under adapters/ in the installed platform. Its profile is the base; every other key in this file replaces the adapter's key of the same name.",
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z0-9][a-z0-9-]*$"
+    },
     "projectId": {
       "type": "string",
       "minLength": 1,

package/scripts/capability-catalog.mjs

@@ -20,6 +20,10 @@ import {
   validateCapabilitySources,
   vendorRemoteSource
 } from "../packages/piagent-core/capabilities/capability-sources.js";
+import {
+  buildExtendingProfile,
+  resolveProjectProfileDocument
+} from "../packages/piagent-core/capabilities/project-profile.js";
 
 const platformRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const catalogPath = path.join(platformRoot, "catalog", "capabilities.json");
@@ -28,7 +32,7 @@ function usage() {
   process.stdout.write(`Usage:
   piagent-capabilities catalog [--check | --write]
   piagent-capabilities resolve --profile <profile.json> [--output <lock.json>] [--package-source <source>]
-  piagent-capabilities apply-profile --profile <source.json> --target <piagent-profile.json> [--package-source <source>] [--force]
+  piagent-capabilities apply-profile --profile <source.json> --target <piagent-profile.json> [--extends <adapter>] [--package-source <source>] [--force]
   piagent-capabilities doctor [--profile <profile.json>] [--lock <lock.json>] [--package-source <source>]
   piagent-capabilities vendor --profile <profile.json> [--source <name>]
   piagent-capabilities validate-source --package-source <source>
@@ -58,7 +62,7 @@ function parseArguments(values) {
       output.flags.set(value, true);
       continue;
     }
-    if (!["--profile", "--output", "--target", "--lock", "--file", "--package-source", "--source"].includes(value)) throw new CapabilityValidationError(`unknown option ${value}`);
+    if (!["--profile", "--extends", "--output", "--target", "--lock", "--file", "--package-source", "--source"].includes(value)) throw new CapabilityValidationError(`unknown option ${value}`);
     if (output.flags.has(value)) throw new CapabilityValidationError(`duplicate option ${value}`);
     const next = values[index + 1];
     if (!next || next.startsWith("--")) throw new CapabilityValidationError(`${value} requires a value`);
@@ -157,7 +161,7 @@ function runResolve(flags) {
 }
 
 function runApplyProfile(flags) {
-  assertAllowedFlags(flags, new Set(["--profile", "--target", "--package-source", "--force"]));
+  assertAllowedFlags(flags, new Set(["--profile", "--extends", "--target", "--package-source", "--force"]));
   const source = requireExistingFile(flags.get("--profile"), "--profile");
   const targetValue = flags.get("--target");
   if (!targetValue) throw new CapabilityValidationError("--target is required");
@@ -166,17 +170,27 @@ function runApplyProfile(flags) {
   const parent = fs.realpathSync(path.dirname(target));
   const normalizedTarget = path.join(parent, path.basename(target));
   if (fs.existsSync(normalizedTarget) && !flags.has("--force")) throw new CapabilityValidationError("target profile already exists; pass --force to replace it");
-  const profile = readJson(source);
+  const adapter = readJson(source);
+  const base = flags.get("--extends");
+  // With --extends the project records which adapter it follows and keeps only
+  // its own identity, so a later platform correction reaches it. Without it the
+  // source document is copied whole, which is what a caller supplying its own
+  // profile file wants.
+  const stored = base === undefined
+    ? adapter
+    : buildExtendingProfile(base, adapter.projectId, adapter.displayName);
+  const profile = resolveProjectProfileDocument(platformRoot, stored).profile;
   const packageSource = flags.get("--package-source") ?? "workspace";
   const lock = resolveCapabilityProfileDocument(platformRoot, profile, {
     profileFile: path.basename(normalizedTarget),
+    storedProfile: stored,
     packageSource,
     extraRoots: profile.capabilitySources === undefined
       ? undefined
       : resolveCapabilitySourceRoots(projectRootForProfile(normalizedTarget), profile.capabilitySources)
   });
   const lockTarget = path.join(parent, "piagent-profile.lock.json");
-  writeProfileLockAtomic(normalizedTarget, profile, lockTarget, lock);
+  writeProfileLockAtomic(normalizedTarget, stored, lockTarget, lock);
   process.stdout.write(`${JSON.stringify({ ok: true, profile: normalizedTarget, lock: lockTarget, packs: lock.packs.length })}\n`);
 }
 
@@ -210,11 +224,18 @@ function runDoctor(flags) {
       const verification = verifyCapabilityLock(platformRoot, profile, readJson(lockFile), { packageSource, extraRoots });
       report.lock = {
         path: lockFile,
-        current: verification.ok,
+        current: verification.status === "current",
+        status: verification.status,
+        reasons: verification.reasons,
         expectedDigest: verification.expectedDigest,
         actualDigest: verification.actualDigest
       };
-      if (!verification.ok) throw new CapabilityValidationError("capability lock is stale or has been modified");
+      // A re-pinnable lock is behind the installed build but grants exactly what
+      // it agreed to, so it is reported rather than treated as a failure. The
+      // guard rewrites it on the next session.
+      if (verification.status === "blocked") {
+        throw new CapabilityValidationError(`capability lock no longer matches what the project agreed to: ${verification.reasons.join("; ")}`);
+      }
     }
   } else if (flags.has("--lock")) {
     throw new CapabilityValidationError("--lock requires --profile");

package/scripts/init-project.sh

@@ -219,6 +219,13 @@ if [[ "$FORCE_PROFILE" == true || ! -f "$PROFILE_TARGET" ]]; then
     --target "$PROFILE_TARGET"
     --package-source "$PACKAGE_SOURCE"
   )
+  # A built-in adapter is referenced, not copied, so a later platform correction
+  # reaches this project. A caller supplying its own profile file still gets that
+  # file written whole.
+  if [[ "$PROFILE_PATH" == "$PLATFORM_ROOT/adapters/"*"/profile.json" ]]; then
+    adapter_name="${PROFILE_PATH#"$PLATFORM_ROOT/adapters/"}"
+    apply_profile_args+=(--extends "${adapter_name%/profile.json}")
+  fi
   if [[ "$FORCE_PROFILE" == true ]]; then
     apply_profile_args+=(--force)
   fi