aienvmp 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.7
+
+- Added stale open intent warnings for long-running environment change plans.
+- Added stale handoff warnings when environment changes happen after the last recorded AI handoff.
+- Added optional `aienvmp handoff --record --actor <agent:id>` timeline entries.
+
 ## 0.1.6
 
 - Added optional `sync --deep` / `scan --deep` read-only global tool inventory.

package/README.md

@@ -18,6 +18,7 @@ Core loop: scan the env, give AI a preflight context, and hand off safe next ste
 npx aienvmp sync
 npx aienvmp context
 npx aienvmp handoff
+npx aienvmp handoff --record --actor agent:codex
 ```
 
 Optional deeper read-only inventory:
@@ -65,7 +66,8 @@ aienvmp doctor --ci       # strict CI check
 - simple by default
 - AI-first
 - lightweight
-- non-blocking unless strict mode is requested
+- one advisory engine, optional enforcement with `doctor --ci`
+- non-blocking unless strict mode is explicitly requested
 
 ## Development
 

package/ROADMAP.md

@@ -6,6 +6,7 @@
 
 - Strengthen trust states: observed, planned, changed, review, verified, stale
 - Detect multi-agent environment intent conflicts
+- Keep one advisory decision engine with optional strict enforcement
 - Stabilize `.aienvmp/manifest.json` and JSON command schemas
 - Keep `sync`, `context`, and `handoff` as the simple core flow
 - Improve the dashboard for 10-second human review
@@ -20,9 +21,8 @@
   - richer summaries for `npm -g`, `pipx list`, `uv tool list`, and Homebrew
   - optional `--deep` scanners for more toolchains
 - Conflict detection:
-  - stale unresolved intents
-  - recent runtime changes without a fresh handoff
   - package manager policy vs lockfile mismatch
+  - monorepo/project boundary aware intent targets
 - CI mode:
   - stable exit codes
   - GitHub Action example

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aienvmp",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "AI-first environment maps and lightweight runtime SBOMs for shared development machines.",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -76,7 +76,7 @@ function printUsage() {
 Usage:
   aienvmp sync [--dir .] [--json] [--quiet] [--deep]
   aienvmp context [--dir .] [--json]
-  aienvmp handoff [--dir .] [--json]
+  aienvmp handoff [--dir .] [--json] [--record --actor agent:id]
 
 Common:
   aienvmp sync      update AIENV.md, manifest, ledger, intents, and dashboard

package/src/commands/handoff.js

@@ -1,9 +1,10 @@
 import { diagnose } from "../doctor.js";
-import { readJson } from "../fsutil.js";
+import { appendJsonLine, readJson } from "../fsutil.js";
 import { loadPolicy, policyWarnings } from "../policy.js";
 import { intentsPath, manifestPath, timelinePath, workspaceDir } from "../paths.js";
 import { renderHandoff } from "../render.js";
 import { openIntents, readJsonl, readTimeline } from "../timeline.js";
+import { changedTrust } from "../trust.js";
 
 export async function handoffWorkspace(args) {
   const dir = workspaceDir(args);
@@ -14,6 +15,9 @@ export async function handoffWorkspace(args) {
   const policy = await loadPolicy(dir);
   const warnings = [...diagnose(manifest, { timeline, intents }), ...policyWarnings(manifest, policy)];
   const handoff = buildHandoff(manifest, timeline, warnings, intents, policy);
+  if (args.record) {
+    await recordHandoff(timelinePath(dir), handoff, args.actor || "agent:unknown");
+  }
 
   if (args.json) {
     console.log(JSON.stringify(handoff, null, 2));
@@ -23,6 +27,19 @@ export async function handoffWorkspace(args) {
   return handoff;
 }
 
+async function recordHandoff(file, handoff, actor) {
+  const now = new Date();
+  await appendJsonLine(file, {
+    at: now.toISOString(),
+    actor,
+    type: "agent-handoff",
+    summary: `handoff ${handoff.status}`,
+    status: handoff.status,
+    warnings: handoff.warnings.map((warning) => warning.code),
+    trust: changedTrust(now, handoff.status !== "clear")
+  });
+}
+
 export function buildHandoff(manifest, timeline = [], warnings = [], intents = [], policy = {}) {
   const reviewRequired = warnings.length > 0 || intents.length > 0;
   return {

package/src/doctor.js

@@ -43,6 +43,8 @@ export function diagnose(manifest, context = {}) {
     });
   }
   warnings.push(...coordinationWarnings(context.intents || []));
+  warnings.push(...staleIntentWarnings(context.intents || []));
+  warnings.push(...handoffWarnings(context.timeline || []));
   return warnings;
 }
 
@@ -69,6 +71,30 @@ export function coordinationWarnings(intents = []) {
   return warnings;
 }
 
+export function staleIntentWarnings(intents = [], now = new Date(), maxAgeHours = 4) {
+  const warnings = [];
+  for (const intent of intents) {
+    if (!isStaleTimestamp(intent.at, now, maxAgeHours)) continue;
+    warnings.push({
+      code: "stale-open-intent",
+      target: intent.target || inferTarget(intent.action) || "",
+      message: `Open intent ${intent.id || ""} from ${intent.actor || "unknown"} is older than ${maxAgeHours} hours. Resolve it or confirm it before environment changes.`.replace(/\s+/g, " ").trim()
+    });
+  }
+  return warnings;
+}
+
+export function handoffWarnings(timeline = []) {
+  const lastEnvChange = [...timeline].reverse().find(isEnvironmentChange);
+  if (!lastEnvChange) return [];
+  const lastHandoff = [...timeline].reverse().find((item) => item.type === "agent-handoff");
+  if (lastHandoff && new Date(lastHandoff.at).getTime() >= new Date(lastEnvChange.at).getTime()) return [];
+  return [{
+    code: "handoff-stale",
+    message: "Environment changes were recorded after the last AI handoff. Run `aienvmp handoff --record --actor agent:id` before the next agent continues."
+  }];
+}
+
 function inferTarget(action = "") {
   const normalized = String(action).toLowerCase();
   for (const target of ["node", "python", "docker", "npm", "pnpm", "yarn", "uv", "pip", "pipx"]) {
@@ -76,3 +102,24 @@ function inferTarget(action = "") {
   }
   return "";
 }
+
+function isEnvironmentChange(item = {}) {
+  if (["runtime", "package-manager", "container"].includes(item.change?.scope)) return true;
+  if (item.type === "detected-change") return false;
+  const text = `${item.type || ""} ${item.target || ""} ${item.summary || ""} ${item.action || ""} ${item.change?.scope || ""} ${item.change?.key || ""}`.toLowerCase();
+  return [
+    "runtime",
+    "node",
+    "python",
+    "docker",
+    "package manager",
+    "package-manager",
+    "npm",
+    "pnpm",
+    "yarn",
+    "uv",
+    "pip",
+    "pipx",
+    "global"
+  ].some((token) => text.includes(token));
+}

package/src/manifest.js

@@ -32,8 +32,8 @@ export async function buildManifest(dir, options = {}) {
       sourceOfTruth: "AIENV.md",
       preflightCommand: "aienvmp context",
       handoffCommand: "aienvmp handoff",
-      intentCommand: "aienvmp intent --actor <agent:id> --action <planned-change>",
-      recordCommand: "aienvmp record --actor <agent:id> --summary <what-changed>",
+      intentCommand: "aienvmp intent --actor agent:id --action planned-change",
+      recordCommand: "aienvmp record --actor agent:id --summary what-changed",
       afterEnvironmentChange: ["aienvmp sync"],
       trustModel: {
         agentWritable: ["observed", "planned", "changed", "review", "stale"],

package/src/render.js

@@ -12,9 +12,10 @@ export function renderAIEnv(manifest, timeline = [], warnings = [], intents = []
   lines.push("1. Run `aienvmp context`.");
   lines.push("2. Prefer project-local version files such as `.nvmrc`, `.python-version`, `mise.toml`, and `.tool-versions`.");
   lines.push("3. Ask the user before changing global environment state.");
-  lines.push("4. Record planned environment changes with `aienvmp intent --actor <agent:id> --action <planned-change>`.");
+  lines.push("4. Record planned environment changes with `aienvmp intent --actor agent:id --action planned-change`.");
   lines.push("5. After environment changes, run `aienvmp sync`.");
-  lines.push("6. Record what changed with `aienvmp record --actor <agent:id> --summary <what-changed>`.", "");
+  lines.push("6. Record what changed with `aienvmp record --actor agent:id --summary what-changed`.");
+  lines.push("7. At handoff, run `aienvmp handoff --record --actor agent:id`.", "");
   lines.push("## Current Policy", "");
   lines.push(...policyLines(policy));
   lines.push("- Enforcement: non-blocking by default; warnings require review but do not lock the machine.");
@@ -76,6 +77,7 @@ Before changing runtimes, package managers, Docker settings, global packages, or
 4. Record planned environment changes with \`aienvmp intent\`.
 5. After environment changes, run \`aienvmp sync\`.
 6. Record what changed with \`aienvmp record\`.
+7. At handoff, run \`aienvmp handoff --record --actor agent:id\`.
 
 \`aienvmp\` does not replace this instruction file. It provides the live env map, lightweight runtime SBOM, intent log, timeline, and dashboard.`;
 }
@@ -102,9 +104,10 @@ export function renderContext(manifest, timeline = [], warnings = [], intents =
     "- Ask the user before global runtime, package manager, Docker, or global package changes.",
     "- Treat policy mismatches as review-required, not as permission to break ongoing operations.",
     "- Prefer project-local version files and local environments.",
-    "- Before planned env changes, run `aienvmp intent --actor <agent:id> --action <planned-change>`.",
+    "- Before planned env changes, run `aienvmp intent --actor agent:id --action planned-change`.",
     "- After env changes, run `aienvmp sync`.",
-    "- Then run `aienvmp record --actor <agent:id> --summary <what-changed>`.",
+    "- Then run `aienvmp record --actor agent:id --summary what-changed`.",
+    "- Before handing work to another AI, run `aienvmp handoff --record --actor agent:id`.",
     "",
     "Warnings:",
     ...(warnings.length ? warnings.map((w) => `- ${w.message}`) : ["- none"]),