build(pi-coding-agent): bump to 0.74.0 with enriched lockfile workflow

Upstream v0.74.0 lockfile omits resolved/integrity metadata needed by
buildNpmPackage's offline NPM cache. Add a package-local enriched lockfile,
a script to regenerate it from the npm registry, and a prePatch step to
copy it into the build sandbox.

modules/home/programs/terminal/pi/config/AGENTS.md

@@ -33,7 +33,7 @@ Full-file reads are fine when genuinely needed, but avoid them as the default re
 
 2. **Maintain AGENTS.md**: Keep project guidance up to date, but BLUF: concise, actionable, and context-size conscious.
 
-3. **Knowledge Capture**: At task end, if you discovered non-obvious conventions, pitfalls, or repeatable workflows that would have saved time, briefly recommend adding them to AGENTS.md or a skill. Say whether each belongs in project-level context, global agent context, or a task-specific skill. Skip this when there is nothing meaningful.
+3. **Knowledge Capture Check**: Before the final response, ask whether the task revealed a non-obvious convention, pitfall, repeatable workflow, or missing helper. If yes, briefly recommend exactly where to capture it: package/project AGENTS.md, global AGENTS.md, a skill, or a helper script. Skip this note when there is nothing meaningful.
 
 ## Style
 

packages/pi-coding-agent/AGENTS.md

@@ -0,0 +1,23 @@
+# pi-coding-agent Packaging Notes
+
+`pi-coding-agent` is built from the `earendil-works/pi-mono` monorepo with `buildNpmPackage`.
+
+## Lockfile Metadata
+
+Upstream `package-lock.json` may omit `resolved` / `integrity` metadata that npm can recover online, but Nix needs for its offline npm cache. Keep a package-local enriched lockfile at `packages/pi-coding-agent/package-lock.json` and copy it in during `prePatch` before `npmConfigHook` validates/generates `npmDeps`.
+
+After bumping `version` in `default.nix`, regenerate it with:
+
+```bash
+node packages/pi-coding-agent/update-lockfile.mjs
+# or explicitly:
+node packages/pi-coding-agent/update-lockfile.mjs 0.74.0
+```
+
+Then refresh `npmDepsHash` from the FOD mismatch:
+
+```bash
+nix build .#packages.aarch64-linux.pi-coding-agent.npmDeps --no-link
+```
+
+Remember: new files must be `git add`ed before the flake can see them.

packages/pi-coding-agent/default.nix

@@ -16,19 +16,24 @@
 
 buildNpmPackage rec {
   pname = "pi-coding-agent";
-  version = "0.73.1";
+  version = "0.74.0";
 
   src = fetchFromGitHub {
     owner = "earendil-works";
     repo = "pi-mono";
     rev = "v${version}";
-    hash = "sha256-ZcqMWghMACzEUswLujwClPF1pbwjTKzTbcYW86ZvjL4=";
+    hash = "sha256-wEiqOezD8w08vyuenh3Kk+YCYBbQoEq67wATDEKy5XM=";
   };
 
-  npmDepsHash = "sha256-tneAcwtTIfkcqQ8/Ch1Xa6OiOkTjJNYbH8wfhNneT/g=";
+  npmDepsHash = "sha256-ZcJ6k3gOpO6vOgukn2L0AcQsj5M+behltEx12u2Zu7Y=";
 
   nativeBuildInputs = [ pkg-config makeWrapper ];
 
+  # Restore NPM Metadata - v0.74.0 lockfile omits resolved/integrity entries needed by buildNpmPackage.
+  prePatch = ''
+    cp ${./package-lock.json} package-lock.json
+  '';
+
   buildInputs = [
     pixman
     cairo

packages/pi-coding-agent/update-lockfile.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+
+const repoRoot = new URL('../..', import.meta.url);
+const packageDir = new URL('.', import.meta.url);
+const defaultNixPath = new URL('default.nix', packageDir);
+const lockfilePath = new URL('package-lock.json', packageDir);
+const registryCache = new Map();
+
+// Version Selection
+async function getVersion() {
+  const argVersion = process.argv[2];
+  if (argVersion) return argVersion.replace(/^v/, '');
+
+  const defaultNix = await fs.readFile(defaultNixPath, 'utf8');
+  const match = defaultNix.match(/version\s*=\s*"([^"]+)";/);
+  if (!match) throw new Error(`Unable to find version in ${defaultNixPath.pathname}`);
+  return match[1];
+}
+
+// Package Name Extraction
+function packageNameFromLockPath(lockPath) {
+  const parts = lockPath.split('/');
+  const idx = parts.lastIndexOf('node_modules');
+  if (idx < 0 || idx + 1 >= parts.length) return null;
+
+  const first = parts[idx + 1];
+  if (first.startsWith('@')) return `${first}/${parts[idx + 2]}`;
+  return first;
+}
+
+// Registry Fetching
+function registryUrl(name, version) {
+  const encodedName = name.startsWith('@') ? name.replace('/', '%2f') : name;
+  return `https://registry.npmjs.org/${encodedName}/${version}`;
+}
+
+async function fetchPackageMetadata(name, version) {
+  const key = `${name}@${version}`;
+  if (registryCache.has(key)) return registryCache.get(key);
+
+  const response = await fetch(registryUrl(name, version), {
+    headers: { accept: 'application/json' },
+  });
+  if (!response.ok) {
+    throw new Error(`Failed to fetch ${key}: HTTP ${response.status}`);
+  }
+
+  const metadata = await response.json();
+  const dist = metadata.dist;
+  if (!dist?.tarball || !dist?.integrity) {
+    throw new Error(`Missing dist.tarball/dist.integrity for ${key}`);
+  }
+
+  registryCache.set(key, dist);
+  return dist;
+}
+
+// Lockfile Enrichment
+async function enrichLockfile(lock) {
+  let updated = 0;
+
+  for (const [lockPath, entry] of Object.entries(lock.packages ?? {})) {
+    if (!lockPath || entry.link || !entry.version || entry.resolved) continue;
+    if (!lockPath.includes('node_modules')) continue;
+
+    const name = packageNameFromLockPath(lockPath);
+    if (!name) continue;
+
+    const dist = await fetchPackageMetadata(name, entry.version);
+    entry.resolved = dist.tarball;
+    entry.integrity = dist.integrity;
+    updated += 1;
+  }
+
+  return updated;
+}
+
+// Main
+const version = await getVersion();
+const lockUrl = `https://raw.githubusercontent.com/earendil-works/pi-mono/v${version}/package-lock.json`;
+const response = await fetch(lockUrl, { headers: { accept: 'application/json' } });
+if (!response.ok) throw new Error(`Failed to fetch ${lockUrl}: HTTP ${response.status}`);
+
+const lock = await response.json();
+const updated = await enrichLockfile(lock);
+await fs.writeFile(lockfilePath, JSON.stringify(lock, null, 2) + '\n');
+
+const displayPath = path.relative(repoRoot.pathname, lockfilePath.pathname);
+console.error(`Wrote ${displayPath} for v${version}; restored metadata for ${updated} entries.`);