gsd-pi 2.67.0-dev.43b0159 → 2.67.0-dev.a5b1d8f

package/dist/web/standalone/package.json

@@ -55,7 +55,7 @@
     "input-otp": "1.4.2",
     "lucide-react": "^0.564.0",
     "motion": "^12.36.0",
-    "next": "16.1.6",
+    "next": "16.2.3",
     "next-themes": "^0.4.6",
     "node-pty": "^1.1.0",
     "react": "19.2.4",
@@ -80,7 +80,7 @@
     "@types/react-dom": "19.2.3",
     "esbuild": "^0.27.4",
     "eslint": "^9.38.0",
-    "eslint-config-next": "16.1.6",
+    "eslint-config-next": "16.2.3",
     "postcss": "^8.5",
     "tailwindcss": "^4.2.0",
     "tw-animate-css": "1.3.3",

package/dist/web/standalone/server.js

@@ -15,7 +15,7 @@ const currentPort = parseInt(process.env.PORT, 10) || 3000
 const hostname = process.env.HOSTNAME || '0.0.0.0'
 
 let keepAliveTimeout = parseInt(process.env.KEEP_ALIVE_TIMEOUT, 10)
-const nextConfig = {"env":{},"typescript":{"ignoreBuildErrors":true},"typedRoutes":false,"distDir":"./.next","cleanDistDir":true,"assetPrefix":"","cacheMaxMemorySize":52428800,"configOrigin":"next.config.mjs","useFileSystemPublicRoutes":true,"generateEtags":true,"pageExtensions":["tsx","ts","jsx","js"],"poweredByHeader":true,"compress":true,"images":{"deviceSizes":[640,750,828,1080,1200,1920,2048,3840],"imageSizes":[32,48,64,96,128,256,384],"path":"/_next/image","loader":"default","loaderFile":"","domains":[],"disableStaticImages":false,"minimumCacheTTL":14400,"formats":["image/webp"],"maximumRedirects":3,"maximumResponseBody":50000000,"dangerouslyAllowLocalIP":false,"dangerouslyAllowSVG":false,"contentSecurityPolicy":"script-src 'none'; frame-src 'none'; sandbox;","contentDispositionType":"attachment","localPatterns":[{"pathname":"**","search":""}],"remotePatterns":[],"qualities":[75],"unoptimized":true},"devIndicators":{"position":"bottom-left"},"onDemandEntries":{"maxInactiveAge":60000,"pagesBufferLength":5},"basePath":"","sassOptions":{},"trailingSlash":false,"i18n":null,"productionBrowserSourceMaps":false,"excludeDefaultMomentLocales":true,"reactProductionProfiling":false,"reactStrictMode":null,"reactMaxHeadersLength":6000,"httpAgentOptions":{"keepAlive":true},"logging":{},"compiler":{},"expireTime":31536000,"staticPageGenerationTimeout":60,"output":"standalone","modularizeImports":{"@mui/icons-material":{"transform":"@mui/icons-material/{{member}}"},"lodash":{"transform":"lodash/{{member}}"}},"outputFileTracingRoot":"/__w/gsd-2/gsd-2","cacheComponents":false,"cacheLife":{"default":{"stale":300,"revalidate":900,"expire":4294967294},"seconds":{"stale":30,"revalidate":1,"expire":60},"minutes":{"stale":300,"revalidate":60,"expire":3600},"hours":{"stale":300,"revalidate":3600,"expire":86400},"days":{"stale":300,"revalidate":86400,"expire":604800},"weeks":{"stale":300,"revalidate":604800,"expire":2592000},"max":{"stale":300,"revalidate":2592000,"expire":31536000}},"cacheHandlers":{},"experimental":{"useSkewCookie":false,"cssChunking":true,"multiZoneDraftMode":false,"appNavFailHandling":false,"prerenderEarlyExit":true,"serverMinification":true,"linkNoTouchStart":false,"caseSensitiveRoutes":false,"dynamicOnHover":false,"preloadEntriesOnStart":true,"clientRouterFilter":true,"clientRouterFilterRedirects":false,"fetchCacheKeyPrefix":"","proxyPrefetch":"flexible","optimisticClientCache":true,"manualClientBasePath":false,"cpus":5,"memoryBasedWorkersCount":false,"imgOptConcurrency":null,"imgOptTimeoutInSeconds":7,"imgOptMaxInputPixels":268402689,"imgOptSequentialRead":null,"imgOptSkipMetadata":null,"isrFlushToDisk":true,"workerThreads":false,"optimizeCss":false,"nextScriptWorkers":false,"scrollRestoration":false,"externalDir":false,"disableOptimizedLoading":false,"gzipSize":true,"craCompat":false,"esmExternals":true,"fullySpecified":false,"swcTraceProfiling":false,"forceSwcTransforms":false,"largePageDataBytes":128000,"typedEnv":false,"parallelServerCompiles":false,"parallelServerBuildTraces":false,"ppr":false,"authInterrupts":false,"webpackMemoryOptimizations":false,"optimizeServerReact":true,"viewTransition":false,"removeUncaughtErrorAndRejectionListeners":false,"validateRSCRequestHeaders":false,"staleTimes":{"dynamic":0,"static":300},"reactDebugChannel":false,"serverComponentsHmrCache":true,"staticGenerationMaxConcurrency":8,"staticGenerationMinPagesPerWorker":25,"transitionIndicator":false,"inlineCss":false,"useCache":false,"globalNotFound":false,"browserDebugInfoInTerminal":false,"lockDistDir":true,"isolatedDevBuild":true,"proxyClientMaxBodySize":10485760,"hideLogsAfterAbort":false,"mcpServer":true,"turbopackFileSystemCacheForDev":true,"turbopackFileSystemCacheForBuild":false,"turbopackInferModuleSideEffects":false,"optimizePackageImports":["lucide-react","date-fns","lodash-es","ramda","antd","react-bootstrap","ahooks","@ant-design/icons","@headlessui/react","@headlessui-float/react","@heroicons/react/20/solid","@heroicons/react/24/solid","@heroicons/react/24/outline","@visx/visx","@tremor/react","rxjs","@mui/material","@mui/icons-material","recharts","react-use","effect","@effect/schema","@effect/platform","@effect/platform-node","@effect/platform-browser","@effect/platform-bun","@effect/sql","@effect/sql-mssql","@effect/sql-mysql2","@effect/sql-pg","@effect/sql-sqlite-node","@effect/sql-sqlite-bun","@effect/sql-sqlite-wasm","@effect/sql-sqlite-react-native","@effect/rpc","@effect/rpc-http","@effect/typeclass","@effect/experimental","@effect/opentelemetry","@material-ui/core","@material-ui/icons","@tabler/icons-react","mui-core","react-icons/ai","react-icons/bi","react-icons/bs","react-icons/cg","react-icons/ci","react-icons/di","react-icons/fa","react-icons/fa6","react-icons/fc","react-icons/fi","react-icons/gi","react-icons/go","react-icons/gr","react-icons/hi","react-icons/hi2","react-icons/im","react-icons/io","react-icons/io5","react-icons/lia","react-icons/lib","react-icons/lu","react-icons/md","react-icons/pi","react-icons/ri","react-icons/rx","react-icons/si","react-icons/sl","react-icons/tb","react-icons/tfi","react-icons/ti","react-icons/vsc","react-icons/wi"],"trustHostHeader":false,"isExperimentalCompile":false},"htmlLimitedBots":"[\\w-]+-Google|Google-[\\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight","bundlePagesRouterDependencies":false,"configFileName":"next.config.mjs","serverExternalPackages":["@gsd/native","node-pty"],"turbopack":{"root":"/__w/gsd-2/gsd-2"},"distDirRoot":".next"}
+const nextConfig = {"env":{},"typescript":{"ignoreBuildErrors":true},"typedRoutes":false,"distDir":"./.next","cleanDistDir":true,"assetPrefix":"","cacheMaxMemorySize":52428800,"configOrigin":"next.config.mjs","useFileSystemPublicRoutes":true,"generateEtags":true,"pageExtensions":["tsx","ts","jsx","js"],"poweredByHeader":true,"compress":true,"images":{"deviceSizes":[640,750,828,1080,1200,1920,2048,3840],"imageSizes":[32,48,64,96,128,256,384],"path":"/_next/image","loader":"default","loaderFile":"","domains":[],"disableStaticImages":false,"minimumCacheTTL":14400,"formats":["image/webp"],"maximumRedirects":3,"maximumResponseBody":50000000,"dangerouslyAllowLocalIP":false,"dangerouslyAllowSVG":false,"contentSecurityPolicy":"script-src 'none'; frame-src 'none'; sandbox;","contentDispositionType":"attachment","localPatterns":[{"pathname":"**","search":""}],"remotePatterns":[],"qualities":[75],"unoptimized":true,"customCacheHandler":false},"devIndicators":{"position":"bottom-left"},"onDemandEntries":{"maxInactiveAge":60000,"pagesBufferLength":5},"basePath":"","sassOptions":{},"trailingSlash":false,"i18n":null,"productionBrowserSourceMaps":false,"excludeDefaultMomentLocales":true,"reactProductionProfiling":false,"reactStrictMode":null,"reactMaxHeadersLength":6000,"httpAgentOptions":{"keepAlive":true},"logging":{"serverFunctions":true,"browserToTerminal":"warn"},"compiler":{},"expireTime":31536000,"staticPageGenerationTimeout":60,"output":"standalone","modularizeImports":{"@mui/icons-material":{"transform":"@mui/icons-material/{{member}}"},"lodash":{"transform":"lodash/{{member}}"}},"outputFileTracingRoot":"/__w/gsd-2/gsd-2","cacheComponents":false,"cacheLife":{"default":{"stale":300,"revalidate":900,"expire":4294967294},"seconds":{"stale":30,"revalidate":1,"expire":60},"minutes":{"stale":300,"revalidate":60,"expire":3600},"hours":{"stale":300,"revalidate":3600,"expire":86400},"days":{"stale":300,"revalidate":86400,"expire":604800},"weeks":{"stale":300,"revalidate":604800,"expire":2592000},"max":{"stale":300,"revalidate":2592000,"expire":31536000}},"cacheHandlers":{},"experimental":{"appNewScrollHandler":false,"useSkewCookie":false,"cssChunking":true,"multiZoneDraftMode":false,"appNavFailHandling":false,"prerenderEarlyExit":true,"serverMinification":true,"linkNoTouchStart":false,"caseSensitiveRoutes":false,"cachedNavigations":false,"partialFallbacks":false,"dynamicOnHover":false,"varyParams":false,"prefetchInlining":false,"preloadEntriesOnStart":true,"clientRouterFilter":true,"clientRouterFilterRedirects":false,"fetchCacheKeyPrefix":"","proxyPrefetch":"flexible","optimisticClientCache":true,"manualClientBasePath":false,"cpus":5,"memoryBasedWorkersCount":false,"imgOptConcurrency":null,"imgOptTimeoutInSeconds":7,"imgOptMaxInputPixels":268402689,"imgOptSequentialRead":null,"imgOptSkipMetadata":null,"isrFlushToDisk":true,"workerThreads":false,"optimizeCss":false,"nextScriptWorkers":false,"scrollRestoration":false,"externalDir":false,"disableOptimizedLoading":false,"gzipSize":true,"craCompat":false,"esmExternals":true,"fullySpecified":false,"swcTraceProfiling":false,"forceSwcTransforms":false,"largePageDataBytes":128000,"typedEnv":false,"parallelServerCompiles":false,"parallelServerBuildTraces":false,"ppr":false,"authInterrupts":false,"webpackMemoryOptimizations":false,"optimizeServerReact":true,"strictRouteTypes":false,"viewTransition":false,"removeUncaughtErrorAndRejectionListeners":false,"validateRSCRequestHeaders":false,"staleTimes":{"dynamic":0,"static":300},"reactDebugChannel":true,"serverComponentsHmrCache":true,"staticGenerationMaxConcurrency":8,"staticGenerationMinPagesPerWorker":25,"transitionIndicator":false,"gestureTransition":false,"inlineCss":false,"useCache":false,"globalNotFound":false,"browserDebugInfoInTerminal":"warn","lockDistDir":true,"proxyClientMaxBodySize":10485760,"hideLogsAfterAbort":false,"mcpServer":true,"turbopackFileSystemCacheForDev":true,"turbopackFileSystemCacheForBuild":false,"turbopackInferModuleSideEffects":true,"turbopackPluginRuntimeStrategy":"childProcesses","optimizePackageImports":["lucide-react","date-fns","lodash-es","ramda","antd","react-bootstrap","ahooks","@ant-design/icons","@headlessui/react","@headlessui-float/react","@heroicons/react/20/solid","@heroicons/react/24/solid","@heroicons/react/24/outline","@visx/visx","@tremor/react","rxjs","@mui/material","@mui/icons-material","recharts","react-use","effect","@effect/schema","@effect/platform","@effect/platform-node","@effect/platform-browser","@effect/platform-bun","@effect/sql","@effect/sql-mssql","@effect/sql-mysql2","@effect/sql-pg","@effect/sql-sqlite-node","@effect/sql-sqlite-bun","@effect/sql-sqlite-wasm","@effect/sql-sqlite-react-native","@effect/rpc","@effect/rpc-http","@effect/typeclass","@effect/experimental","@effect/opentelemetry","@material-ui/core","@material-ui/icons","@tabler/icons-react","mui-core","react-icons/ai","react-icons/bi","react-icons/bs","react-icons/cg","react-icons/ci","react-icons/di","react-icons/fa","react-icons/fa6","react-icons/fc","react-icons/fi","react-icons/gi","react-icons/go","react-icons/gr","react-icons/hi","react-icons/hi2","react-icons/im","react-icons/io","react-icons/io5","react-icons/lia","react-icons/lib","react-icons/lu","react-icons/md","react-icons/pi","react-icons/ri","react-icons/rx","react-icons/si","react-icons/sl","react-icons/tb","react-icons/tfi","react-icons/ti","react-icons/vsc","react-icons/wi"],"trustHostHeader":false,"isExperimentalCompile":false},"htmlLimitedBots":"[\\w-]+-Google|Google-[\\w-]+|Chrome-Lighthouse|Slurp|DuckDuckBot|baiduspider|yandex|sogou|bitlybot|tumblr|vkShare|quora link preview|redditbot|ia_archiver|Bingbot|BingPreview|applebot|facebookexternalhit|facebookcatalog|Twitterbot|LinkedInBot|Slackbot|Discordbot|WhatsApp|SkypeUriPreview|Yeti|googleweblight","bundlePagesRouterDependencies":false,"configFileName":"next.config.mjs","serverExternalPackages":["@gsd/native","node-pty"],"turbopack":{"root":"/__w/gsd-2/gsd-2"},"distDirRoot":".next"}
 
 process.env.__NEXT_PRIVATE_STANDALONE_CONFIG = JSON.stringify(nextConfig)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-pi",
-  "version": "2.67.0-dev.43b0159",
+  "version": "2.67.0-dev.a5b1d8f",
   "description": "GSD — Get Shit Done coding agent",
   "license": "MIT",
   "repository": {

package/packages/pi-ai/dist/utils/event-stream.d.ts

@@ -16,4 +16,6 @@ export declare class EventStream<T, R = T> implements AsyncIterable<T> {
 export declare class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {
     constructor();
 }
+/** Factory function for AssistantMessageEventStream (for use by package consumers). */
+export declare function createAssistantMessageEventStream(): AssistantMessageEventStream;
 //# sourceMappingURL=event-stream.d.ts.map

package/packages/pi-ai/dist/utils/event-stream.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-stream.d.ts","sourceRoot":"","sources":["../../src/utils/event-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAG3E,qBAAa,WAAW,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAQ5D,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,aAAa;IARtB,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,kBAAkB,CAAa;IACvC,OAAO,CAAC,kBAAkB,CAAuB;gBAGxC,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,EACjC,aAAa,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC;IAOvC,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAiBpB,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,IAAI;IAYd,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;IAcjD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC;CAGpB;AAED,qBAAa,2BAA4B,SAAQ,WAAW,CAAC,qBAAqB,EAAE,gBAAgB,CAAC;;CAcpG"}
+{"version":3,"file":"event-stream.d.ts","sourceRoot":"","sources":["../../src/utils/event-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAG3E,qBAAa,WAAW,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAE,YAAW,aAAa,CAAC,CAAC,CAAC;IAQ5D,OAAO,CAAC,UAAU;IAClB,OAAO,CAAC,aAAa;IARtB,OAAO,CAAC,KAAK,CAAW;IACxB,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,kBAAkB,CAAa;IACvC,OAAO,CAAC,kBAAkB,CAAuB;gBAGxC,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,EACjC,aAAa,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC;IAOvC,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAiBpB,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC,GAAG,IAAI;IAYd,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC;IAcjD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC;CAGpB;AAED,qBAAa,2BAA4B,SAAQ,WAAW,CAAC,qBAAqB,EAAE,gBAAgB,CAAC;;CAcpG;AAED,uFAAuF;AACvF,wBAAgB,iCAAiC,IAAI,2BAA2B,CAE/E"}

package/packages/pi-ai/dist/utils/event-stream.js

@@ -70,4 +70,8 @@ export class AssistantMessageEventStream extends EventStream {
         });
     }
 }
+/** Factory function for AssistantMessageEventStream (for use by package consumers). */
+export function createAssistantMessageEventStream() {
+    return new AssistantMessageEventStream();
+}
 //# sourceMappingURL=event-stream.js.map

package/packages/pi-ai/dist/utils/event-stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-stream.js","sourceRoot":"","sources":["../../src/utils/event-stream.ts"],"names":[],"mappings":"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","sourcesContent":["import type { AssistantMessage, AssistantMessageEvent } from \"../types.js\";\n\n// Generic event stream class for async iteration\nexport class EventStream<T, R = T> implements AsyncIterable<T> {\n\tprivate queue: T[] = [];\n\tprivate waiting: ((value: IteratorResult<T>) => void)[] = [];\n\tprivate done = false;\n\tprivate finalResultPromise: Promise<R>;\n\tprivate resolveFinalResult!: (result: R) => void;\n\n\tconstructor(\n\t\tprivate isComplete: (event: T) => boolean,\n\t\tprivate extractResult: (event: T) => R,\n\t) {\n\t\tthis.finalResultPromise = new Promise((resolve) => {\n\t\t\tthis.resolveFinalResult = resolve;\n\t\t});\n\t}\n\n\tpush(event: T): void {\n\t\tif (this.done) return;\n\n\t\tif (this.isComplete(event)) {\n\t\t\tthis.done = true;\n\t\t\tthis.resolveFinalResult(this.extractResult(event));\n\t\t}\n\n\t\t// Deliver to waiting consumer or queue it\n\t\tconst waiter = this.waiting.shift();\n\t\tif (waiter) {\n\t\t\twaiter({ value: event, done: false });\n\t\t} else {\n\t\t\tthis.queue.push(event);\n\t\t}\n\t}\n\n\tend(result?: R): void {\n\t\tthis.done = true;\n\t\tif (result !== undefined) {\n\t\t\tthis.resolveFinalResult(result);\n\t\t}\n\t\t// Notify all waiting consumers that we're done\n\t\twhile (this.waiting.length > 0) {\n\t\t\tconst waiter = this.waiting.shift()!;\n\t\t\twaiter({ value: undefined as any, done: true });\n\t\t}\n\t}\n\n\tasync *[Symbol.asyncIterator](): AsyncIterator<T> {\n\t\twhile (true) {\n\t\t\tif (this.queue.length > 0) {\n\t\t\t\tyield this.queue.shift()!;\n\t\t\t} else if (this.done) {\n\t\t\t\treturn;\n\t\t\t} else {\n\t\t\t\tconst result = await new Promise<IteratorResult<T>>((resolve) => this.waiting.push(resolve));\n\t\t\t\tif (result.done) return;\n\t\t\t\tyield result.value;\n\t\t\t}\n\t\t}\n\t}\n\n\tresult(): Promise<R> {\n\t\treturn this.finalResultPromise;\n\t}\n}\n\nexport class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {\n\tconstructor() {\n\t\tsuper(\n\t\t\t(event) => event.type === \"done\" || event.type === \"error\",\n\t\t\t(event) => {\n\t\t\t\tif (event.type === \"done\") {\n\t\t\t\t\treturn event.message;\n\t\t\t\t} else if (event.type === \"error\") {\n\t\t\t\t\treturn event.error;\n\t\t\t\t}\n\t\t\t\tthrow new Error(\"Unexpected event type for final result\");\n\t\t\t},\n\t\t);\n\t}\n}\n"]}
+{"version":3,"file":"event-stream.js","sourceRoot":"","sources":["../../src/utils/event-stream.ts"],"names":[],"mappings":"AAEA,iDAAiD;AACjD,MAAM,OAAO,WAAW;IAOvB,YACS,UAAiC,EACjC,aAA8B;QAD9B,eAAU,GAAV,UAAU,CAAuB;QACjC,kBAAa,GAAb,aAAa,CAAiB;QAR/B,UAAK,GAAQ,EAAE,CAAC;QAChB,YAAO,GAA2C,EAAE,CAAC;QACrD,SAAI,GAAG,KAAK,CAAC;QAQpB,IAAI,CAAC,kBAAkB,GAAG,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YACjD,IAAI,CAAC,kBAAkB,GAAG,OAAO,CAAC;QACnC,CAAC,CAAC,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,KAAQ;QACZ,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO;QAEtB,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;YACjB,IAAI,CAAC,kBAAkB,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;QACpD,CAAC;QAED,0CAA0C;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACpC,IAAI,MAAM,EAAE,CAAC;YACZ,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACvC,CAAC;aAAM,CAAC;YACP,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACxB,CAAC;IACF,CAAC;IAED,GAAG,CAAC,MAAU;QACb,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YAC1B,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC;QACD,+CAA+C;QAC/C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAG,CAAC;YACrC,MAAM,CAAC,EAAE,KAAK,EAAE,SAAgB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC;IACF,CAAC;IAED,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,aAAa,CAAC;QAC5B,OAAO,IAAI,EAAE,CAAC;YACb,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC3B,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,EAAG,CAAC;YAC3B,CAAC;iBAAM,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACtB,OAAO;YACR,CAAC;iBAAM,CAAC;gBACP,MAAM,MAAM,GAAG,MAAM,IAAI,OAAO,CAAoB,CAAC,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;gBAC7F,IAAI,MAAM,CAAC,IAAI;oBAAE,OAAO;gBACxB,MAAM,MAAM,CAAC,KAAK,CAAC;YACpB,CAAC;QACF,CAAC;IACF,CAAC;IAED,MAAM;QACL,OAAO,IAAI,CAAC,kBAAkB,CAAC;IAChC,CAAC;CACD;AAED,MAAM,OAAO,2BAA4B,SAAQ,WAAoD;IACpG;QACC,KAAK,CACJ,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAC1D,CAAC,KAAK,EAAE,EAAE;YACT,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;gBAC3B,OAAO,KAAK,CAAC,OAAO,CAAC;YACtB,CAAC;iBAAM,IAAI,KAAK,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;gBACnC,OAAO,KAAK,CAAC,KAAK,CAAC;YACpB,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC3D,CAAC,CACD,CAAC;IACH,CAAC;CACD;AAED,uFAAuF;AACvF,MAAM,UAAU,iCAAiC;IAChD,OAAO,IAAI,2BAA2B,EAAE,CAAC;AAC1C,CAAC","sourcesContent":["import type { AssistantMessage, AssistantMessageEvent } from \"../types.js\";\n\n// Generic event stream class for async iteration\nexport class EventStream<T, R = T> implements AsyncIterable<T> {\n\tprivate queue: T[] = [];\n\tprivate waiting: ((value: IteratorResult<T>) => void)[] = [];\n\tprivate done = false;\n\tprivate finalResultPromise: Promise<R>;\n\tprivate resolveFinalResult!: (result: R) => void;\n\n\tconstructor(\n\t\tprivate isComplete: (event: T) => boolean,\n\t\tprivate extractResult: (event: T) => R,\n\t) {\n\t\tthis.finalResultPromise = new Promise((resolve) => {\n\t\t\tthis.resolveFinalResult = resolve;\n\t\t});\n\t}\n\n\tpush(event: T): void {\n\t\tif (this.done) return;\n\n\t\tif (this.isComplete(event)) {\n\t\t\tthis.done = true;\n\t\t\tthis.resolveFinalResult(this.extractResult(event));\n\t\t}\n\n\t\t// Deliver to waiting consumer or queue it\n\t\tconst waiter = this.waiting.shift();\n\t\tif (waiter) {\n\t\t\twaiter({ value: event, done: false });\n\t\t} else {\n\t\t\tthis.queue.push(event);\n\t\t}\n\t}\n\n\tend(result?: R): void {\n\t\tthis.done = true;\n\t\tif (result !== undefined) {\n\t\t\tthis.resolveFinalResult(result);\n\t\t}\n\t\t// Notify all waiting consumers that we're done\n\t\twhile (this.waiting.length > 0) {\n\t\t\tconst waiter = this.waiting.shift()!;\n\t\t\twaiter({ value: undefined as any, done: true });\n\t\t}\n\t}\n\n\tasync *[Symbol.asyncIterator](): AsyncIterator<T> {\n\t\twhile (true) {\n\t\t\tif (this.queue.length > 0) {\n\t\t\t\tyield this.queue.shift()!;\n\t\t\t} else if (this.done) {\n\t\t\t\treturn;\n\t\t\t} else {\n\t\t\t\tconst result = await new Promise<IteratorResult<T>>((resolve) => this.waiting.push(resolve));\n\t\t\t\tif (result.done) return;\n\t\t\t\tyield result.value;\n\t\t\t}\n\t\t}\n\t}\n\n\tresult(): Promise<R> {\n\t\treturn this.finalResultPromise;\n\t}\n}\n\nexport class AssistantMessageEventStream extends EventStream<AssistantMessageEvent, AssistantMessage> {\n\tconstructor() {\n\t\tsuper(\n\t\t\t(event) => event.type === \"done\" || event.type === \"error\",\n\t\t\t(event) => {\n\t\t\t\tif (event.type === \"done\") {\n\t\t\t\t\treturn event.message;\n\t\t\t\t} else if (event.type === \"error\") {\n\t\t\t\t\treturn event.error;\n\t\t\t\t}\n\t\t\t\tthrow new Error(\"Unexpected event type for final result\");\n\t\t\t},\n\t\t);\n\t}\n}\n\n/** Factory function for AssistantMessageEventStream (for use by package consumers). */\nexport function createAssistantMessageEventStream(): AssistantMessageEventStream {\n\treturn new AssistantMessageEventStream();\n}\n"]}

package/packages/pi-ai/src/utils/event-stream.ts

@@ -80,3 +80,8 @@ export class AssistantMessageEventStream extends EventStream<AssistantMessageEve
 		);
 	}
 }
+
+/** Factory function for AssistantMessageEventStream (for use by package consumers). */
+export function createAssistantMessageEventStream(): AssistantMessageEventStream {
+	return new AssistantMessageEventStream();
+}

package/src/resources/GSD-WORKFLOW.md

@@ -18,7 +18,8 @@ Read these files in order and act on what they say:
 3. **`.gsd/milestones/<active>/M###-CONTEXT.md`** — Milestone-level project decisions, reference paths, constraints. Read this before doing implementation work.
 4. If a slice is active and has one, read **`S##-CONTEXT.md`** — Slice-specific decisions and constraints.
 5. If a slice is active, read its **`S##-PLAN.md`** — Which tasks exist? Which are done?
-6. If a task was interrupted, check for **`continue.md`** in the active slice directory — Resume from there.
+6. If `.gsd/CODEBASE.md` exists, skim it for fast structural orientation before broad code exploration.
+7. If a task was interrupted, check for **`continue.md`** in the active slice directory — Resume from there.
 
 Then do the thing `STATE.md` says to do next.
 
@@ -44,6 +45,7 @@ All artifacts live in `.gsd/` at the project root:
 .gsd/
   STATE.md                                  # Dashboard — always read first (derived cache; runtime, gitignored)
   DECISIONS.md                              # Append-only decisions register
+  CODEBASE.md                               # Generated codebase map cache (auto-refreshed by GSD)
   milestones/
     M001/
       M001-ROADMAP.md                       # Milestone plan (checkboxes = state)

package/src/resources/extensions/get-secrets-from-user.ts

@@ -47,6 +47,14 @@ function shellEscapeSingle(value: string): string {
 	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
+function isSafeEnvVarKey(key: string): boolean {
+	return /^[A-Za-z_][A-Za-z0-9_]*$/.test(key);
+}
+
+function isSupportedDeploymentEnvironment(env: string): boolean {
+	return env === "development" || env === "preview" || env === "production";
+}
+
 function hydrateProcessEnv(key: string, value: string): void {
 	// Make newly collected secrets immediately visible to the current session.
 	// Some extensions read process.env directly and do not reload .env on every call.
@@ -330,12 +338,22 @@ async function applySecrets(
 
 	if ((destination === "vercel" || destination === "convex") && opts.exec) {
 		const env = opts.environment ?? "development";
+		if (!isSupportedDeploymentEnvironment(env)) {
+			errors.push(`environment: unsupported target environment "${env}"`);
+			return { applied, errors };
+		}
 		for (const { key, value } of provided) {
+			if (!isSafeEnvVarKey(key)) {
+				errors.push(`${key}: invalid environment variable name`);
+				continue;
+			}
 			const cmd = destination === "vercel"
 				? `printf %s ${shellEscapeSingle(value)} | vercel env add ${key} ${env}`
-				: `npx convex env set ${key} ${shellEscapeSingle(value)}`;
+				: "";
 			try {
-				const result = await opts.exec("sh", ["-c", cmd]);
+				const result = destination === "vercel"
+					? await opts.exec("sh", ["-c", cmd])
+					: await opts.exec("npx", ["convex", "env", "set", key, value]);
 				if (result.code !== 0) {
 					errors.push(`${key}: ${result.stderr.slice(0, 200)}`);
 				} else {

package/src/resources/extensions/gsd/auto-post-unit.ts

@@ -64,6 +64,7 @@ import { loadEffectiveGSDPreferences } from "./preferences.js";
 import { getSliceTasks } from "./gsd-db.js";
 import { runPreExecutionChecks, type PreExecutionResult } from "./pre-execution-checks.js";
 import { writePreExecutionEvidence } from "./verification-evidence.js";
+import { ensureCodebaseMapFresh } from "./codebase-generator.js";
 
 /** Maximum verification retry attempts before escalating to blocker placeholder (#2653). */
 const MAX_VERIFICATION_RETRIES = 3;
@@ -669,6 +670,35 @@ export async function postUnitPreVerification(pctx: PostUnitContext, opts?: PreV
 export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"continue" | "step-wizard" | "stopped"> {
   const { s, ctx, pi, buildSnapshotOpts, lockBase, stopAuto, pauseAuto, updateProgressWidget } = pctx;
 
+  if (s.currentUnit) {
+    try {
+      const codebasePrefs = loadEffectiveGSDPreferences()?.preferences?.codebase;
+      const refresh = ensureCodebaseMapFresh(
+        s.basePath,
+        codebasePrefs
+          ? {
+              excludePatterns: codebasePrefs.exclude_patterns,
+              maxFiles: codebasePrefs.max_files,
+              collapseThreshold: codebasePrefs.collapse_threshold,
+            }
+          : undefined,
+        { force: true, ttlMs: 0 },
+      );
+      if (refresh.status === "generated" || refresh.status === "updated") {
+        debugLog("postUnit", {
+          phase: "codebase-refresh",
+          unitType: s.currentUnit.type,
+          unitId: s.currentUnit.id,
+          status: refresh.status,
+          fileCount: refresh.fileCount,
+          reason: refresh.reason,
+        });
+      }
+    } catch (e) {
+      logWarning("engine", `CODEBASE refresh failed: ${(e as Error).message}`);
+    }
+  }
+
   // ── Post-unit hooks ──
   if (s.currentUnit && !s.stepMode) {
     const hookUnit = checkPostUnitHooks(s.currentUnit.type, s.currentUnit.id, s.basePath);
@@ -995,4 +1025,3 @@ export async function postUnitPostVerification(pctx: PostUnitContext): Promise<"
 
   return "continue";
 }
-

package/src/resources/extensions/gsd/bootstrap/system-context.ts

@@ -11,6 +11,7 @@ import { readForensicsMarker } from "../forensics.js";
 import { resolveAllSkillReferences, renderPreferencesForSystemPrompt, loadEffectiveGSDPreferences } from "../preferences.js";
 import { resolveSkillReference } from "../preferences-skills.js";
 import { resolveGsdRootFile, resolveSliceFile, resolveSlicePath, resolveTaskFile, resolveTaskFiles, resolveTasksDir, relSliceFile, relSlicePath, relTaskFile } from "../paths.js";
+import { ensureCodebaseMapFresh, readCodebaseMap } from "../codebase-generator.js";
 import { hasSkillSnapshot, detectNewSkills, formatSkillsXml } from "../skill-discovery.js";
 import { getActiveAutoWorktreeContext } from "../auto-worktree.js";
 import { getActiveWorktreeName, getWorktreeOriginalCwd } from "../worktree-command.js";
@@ -128,10 +129,24 @@ export async function buildBeforeAgentStartResult(
   }
 
   let codebaseBlock = "";
+  try {
+    const codebaseOptions = loadedPreferences?.preferences?.codebase
+      ? {
+          excludePatterns: loadedPreferences.preferences.codebase.exclude_patterns,
+          maxFiles: loadedPreferences.preferences.codebase.max_files,
+          collapseThreshold: loadedPreferences.preferences.codebase.collapse_threshold,
+        }
+      : undefined;
+    ensureCodebaseMapFresh(process.cwd(), codebaseOptions);
+  } catch (e) {
+    logWarning("bootstrap", `CODEBASE refresh failed: ${(e as Error).message}`);
+  }
+
   const codebasePath = resolveGsdRootFile(process.cwd(), "CODEBASE");
-  if (existsSync(codebasePath)) {
+  const rawCodebase = readCodebaseMap(process.cwd());
+  if (existsSync(codebasePath) && rawCodebase) {
     try {
-      const rawContent = readFileSync(codebasePath, "utf-8").trim();
+      const rawContent = rawCodebase.trim();
       if (rawContent) {
         // Cap injection size to ~2 000 tokens to avoid bloating every request.
         // Full map is always available at .gsd/CODEBASE.md.
@@ -141,7 +156,7 @@ export async function buildBeforeAgentStartResult(
         const content = rawContent.length > MAX_CODEBASE_CHARS
           ? rawContent.slice(0, MAX_CODEBASE_CHARS) + "\n\n*(truncated — see .gsd/CODEBASE.md for full map)*"
           : rawContent;
-        codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, may be stale — run /gsd codebase update to refresh)]\n\n${content}`;
+        codebaseBlock = `\n\n[PROJECT CODEBASE — File structure and descriptions (generated ${generatedAt}, auto-refreshed when GSD detects tracked file changes; use /gsd codebase stats for status)]\n\n${content}`;
       }
     } catch (e) {
       logWarning("bootstrap", `CODEBASE file read failed: ${(e as Error).message}`);
@@ -494,4 +509,3 @@ export function clearForensicsMarker(basePath: string): void {
     }
   }
 }
-

package/src/resources/extensions/gsd/codebase-generator.ts

@@ -8,6 +8,7 @@
  * Maintenance: agent updates descriptions as it works; incremental update preserves them.
  */
 
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, dirname, extname } from "node:path";
 
@@ -22,6 +23,28 @@ export interface CodebaseMapOptions {
   collapseThreshold?: number;
 }
 
+export interface CodebaseMapMetadata {
+  generatedAt: string;
+  fingerprint: string;
+  fileCount: number;
+  truncated: boolean;
+}
+
+export interface EnsureCodebaseMapOptions {
+  ttlMs?: number;
+  maxAgeMs?: number;
+  force?: boolean;
+}
+
+export interface EnsureCodebaseMapResult {
+  status: "generated" | "updated" | "fresh" | "empty";
+  fileCount: number;
+  truncated: boolean;
+  generatedAt: string | null;
+  fingerprint: string | null;
+  reason?: string;
+}
+
 interface FileEntry {
   path: string;
   description: string;
@@ -33,6 +56,18 @@ interface DirectoryGroup {
   collapsed: boolean;
 }
 
+interface ResolvedCodebaseMapOptions {
+  excludes: string[];
+  maxFiles: number;
+  collapseThreshold: number;
+  optionSignature: string;
+}
+
+interface EnumeratedFiles {
+  files: string[];
+  truncated: boolean;
+}
+
 // ─── Defaults ────────────────────────────────────────────────────────────────
 
 const DEFAULT_EXCLUDES = [
@@ -55,6 +90,11 @@ const DEFAULT_EXCLUDES = [
 
 const DEFAULT_MAX_FILES = 500;
 const DEFAULT_COLLAPSE_THRESHOLD = 20;
+const DEFAULT_REFRESH_TTL_MS = 30_000;
+const DEFAULT_MAX_AGE_MS = 15 * 60_000;
+const CODEBASE_METADATA_PREFIX = "<!-- gsd:codebase-meta ";
+
+const freshnessCache = new Map<string, { checkedAt: number; result: EnsureCodebaseMapResult }>();
 
 // ─── Parsing ─────────────────────────────────────────────────────────────────
 
@@ -96,6 +136,33 @@ export function parseCodebaseMap(content: string): Map<string, string> {
   return descriptions;
 }
 
+export function parseCodebaseMapMetadata(content: string): CodebaseMapMetadata | null {
+  const metaLine = content
+    .split("\n")
+    .find((line) => line.trimStart().startsWith(CODEBASE_METADATA_PREFIX));
+  if (!metaLine) return null;
+
+  const trimmed = metaLine.trim();
+  const jsonStart = CODEBASE_METADATA_PREFIX.length;
+  const jsonEnd = trimmed.lastIndexOf(" -->");
+  if (jsonEnd <= jsonStart) return null;
+
+  try {
+    const parsed = JSON.parse(trimmed.slice(jsonStart, jsonEnd));
+    if (
+      typeof parsed?.generatedAt === "string"
+      && typeof parsed?.fingerprint === "string"
+      && typeof parsed?.fileCount === "number"
+      && typeof parsed?.truncated === "boolean"
+    ) {
+      return parsed as CodebaseMapMetadata;
+    }
+  } catch {
+    // Ignore malformed metadata and treat the map as stale.
+  }
+  return null;
+}
+
 // ─── File Enumeration ────────────────────────────────────────────────────────
 
 function shouldExclude(filePath: string, excludes: string[]): boolean {
@@ -134,6 +201,36 @@ function enumerateFiles(basePath: string, excludes: string[], maxFiles: number):
   return { files: truncated ? filtered.slice(0, maxFiles) : filtered, truncated };
 }
 
+function resolveGeneratorOptions(options?: CodebaseMapOptions): ResolvedCodebaseMapOptions {
+  const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
+  const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
+  const collapseThreshold = options?.collapseThreshold ?? DEFAULT_COLLAPSE_THRESHOLD;
+  return {
+    excludes,
+    maxFiles,
+    collapseThreshold,
+    optionSignature: JSON.stringify({
+      excludes,
+      maxFiles,
+      collapseThreshold,
+    }),
+  };
+}
+
+function computeCodebaseFingerprint(
+  files: string[],
+  resolved: ResolvedCodebaseMapOptions,
+  truncated: boolean,
+): string {
+  return createHash("sha1")
+    .update(JSON.stringify({
+      files,
+      truncated,
+      optionSignature: resolved.optionSignature,
+    }))
+    .digest("hex");
+}
+
 // ─── Grouping ────────────────────────────────────────────────────────────────
 
 function groupByDirectory(
@@ -174,14 +271,19 @@ function groupByDirectory(
 
 // ─── Rendering ───────────────────────────────────────────────────────────────
 
-function renderCodebaseMap(groups: DirectoryGroup[], totalFiles: number, truncated: boolean): string {
+function renderCodebaseMap(
+  groups: DirectoryGroup[],
+  totalFiles: number,
+  truncated: boolean,
+  metadata: CodebaseMapMetadata,
+): string {
   const lines: string[] = [];
-  const now = new Date().toISOString().split(".")[0] + "Z";
   const described = groups.reduce((sum, g) => sum + g.files.filter((f) => f.description).length, 0);
 
   lines.push("# Codebase Map");
   lines.push("");
-  lines.push(`Generated: ${now} | Files: ${totalFiles} | Described: ${described}/${totalFiles}`);
+  lines.push(`Generated: ${metadata.generatedAt} | Files: ${totalFiles} | Described: ${described}/${totalFiles}`);
+  lines.push(`${CODEBASE_METADATA_PREFIX}${JSON.stringify(metadata)} -->`);
   if (truncated) {
     lines.push(`Note: Truncated to first ${totalFiles} files. Run with higher --max-files to include all.`);
   }
@@ -229,6 +331,41 @@ function renderCodebaseMap(groups: DirectoryGroup[], totalFiles: number, truncat
   return lines.join("\n");
 }
 
+function buildCodebaseMap(
+  basePath: string,
+  resolved: ResolvedCodebaseMapOptions,
+  existingDescriptions?: Map<string, string>,
+  enumerated?: EnumeratedFiles,
+): {
+  content: string;
+  fileCount: number;
+  truncated: boolean;
+  files: string[];
+  fingerprint: string;
+  generatedAt: string;
+} {
+  const listed = enumerated ?? enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+  const descriptions = existingDescriptions ?? new Map<string, string>();
+  const groups = groupByDirectory(listed.files, descriptions, resolved.collapseThreshold);
+  const generatedAt = new Date().toISOString().split(".")[0] + "Z";
+  const metadata: CodebaseMapMetadata = {
+    generatedAt,
+    fingerprint: computeCodebaseFingerprint(listed.files, resolved, listed.truncated),
+    fileCount: listed.files.length,
+    truncated: listed.truncated,
+  };
+  const content = renderCodebaseMap(groups, listed.files.length, listed.truncated, metadata);
+
+  return {
+    content,
+    fileCount: listed.files.length,
+    truncated: listed.truncated,
+    files: listed.files,
+    fingerprint: metadata.fingerprint,
+    generatedAt,
+  };
+}
+
 // ─── Public API ──────────────────────────────────────────────────────────────
 
 /**
@@ -239,17 +376,9 @@ export function generateCodebaseMap(
   basePath: string,
   options?: CodebaseMapOptions,
   existingDescriptions?: Map<string, string>,
-): { content: string; fileCount: number; truncated: boolean; files: string[] } {
-  const excludes = [...DEFAULT_EXCLUDES, ...(options?.excludePatterns ?? [])];
-  const maxFiles = options?.maxFiles ?? DEFAULT_MAX_FILES;
-  const collapseThreshold = options?.collapseThreshold ?? DEFAULT_COLLAPSE_THRESHOLD;
-
-  const { files, truncated } = enumerateFiles(basePath, excludes, maxFiles);
-  const descriptions = existingDescriptions ?? new Map<string, string>();
-  const groups = groupByDirectory(files, descriptions, collapseThreshold);
-  const content = renderCodebaseMap(groups, files.length, truncated);
-
-  return { content, fileCount: files.length, truncated, files };
+): { content: string; fileCount: number; truncated: boolean; files: string[]; fingerprint: string; generatedAt: string } {
+  const resolved = resolveGeneratorOptions(options);
+  return buildCodebaseMap(basePath, resolved, existingDescriptions);
 }
 
 /**
@@ -259,8 +388,18 @@ export function generateCodebaseMap(
 export function updateCodebaseMap(
   basePath: string,
   options?: CodebaseMapOptions,
-): { content: string; added: number; removed: number; unchanged: number; fileCount: number; truncated: boolean } {
+): {
+  content: string;
+  added: number;
+  removed: number;
+  unchanged: number;
+  fileCount: number;
+  truncated: boolean;
+  fingerprint: string;
+  generatedAt: string;
+} {
   const codebasePath = join(gsdRoot(basePath), "CODEBASE.md");
+  const resolved = resolveGeneratorOptions(options);
 
   // Load existing descriptions
   let existingDescriptions = new Map<string, string>();
@@ -273,7 +412,7 @@ export function updateCodebaseMap(
 
   // Generate new map preserving descriptions — reuse the returned file list
   // to avoid a second enumeration (prevents race between content and stats).
-  const result = generateCodebaseMap(basePath, options, existingDescriptions);
+  const result = buildCodebaseMap(basePath, resolved, existingDescriptions);
   const currentSet = new Set(result.files);
 
   // Count changes
@@ -294,9 +433,114 @@ export function updateCodebaseMap(
     unchanged: result.files.length - added,
     fileCount: result.fileCount,
     truncated: result.truncated,
+    fingerprint: result.fingerprint,
+    generatedAt: result.generatedAt,
   };
 }
 
+function clearFreshnessCache(basePath: string): void {
+  for (const key of freshnessCache.keys()) {
+    if (key === basePath || key.startsWith(`${basePath}::`)) {
+      freshnessCache.delete(key);
+    }
+  }
+}
+
+export function ensureCodebaseMapFresh(
+  basePath: string,
+  options?: CodebaseMapOptions,
+  ensureOptions?: EnsureCodebaseMapOptions,
+): EnsureCodebaseMapResult {
+  const resolved = resolveGeneratorOptions(options);
+  const cacheKey = `${basePath}::${resolved.optionSignature}`;
+  const ttlMs = ensureOptions?.ttlMs ?? DEFAULT_REFRESH_TTL_MS;
+  const maxAgeMs = ensureOptions?.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+  const force = ensureOptions?.force === true;
+  const now = Date.now();
+
+  if (!force && ttlMs > 0) {
+    const cached = freshnessCache.get(cacheKey);
+    if (cached && now - cached.checkedAt < ttlMs) {
+      return cached.result;
+    }
+  }
+
+  const existing = readCodebaseMap(basePath);
+  const listed = enumerateFiles(basePath, resolved.excludes, resolved.maxFiles);
+  const fingerprint = computeCodebaseFingerprint(listed.files, resolved, listed.truncated);
+
+  const cacheAndReturn = (result: EnsureCodebaseMapResult): EnsureCodebaseMapResult => {
+    freshnessCache.set(cacheKey, { checkedAt: now, result });
+    return result;
+  };
+
+  if (!existing) {
+    const generated = buildCodebaseMap(basePath, resolved, undefined, listed);
+    if (generated.fileCount > 0) {
+      writeCodebaseMap(basePath, generated.content);
+      return cacheAndReturn({
+        status: "generated",
+        fileCount: generated.fileCount,
+        truncated: generated.truncated,
+        generatedAt: generated.generatedAt,
+        fingerprint: generated.fingerprint,
+        reason: "missing",
+      });
+    }
+    return cacheAndReturn({
+      status: "empty",
+      fileCount: 0,
+      truncated: false,
+      generatedAt: null,
+      fingerprint,
+      reason: "no-tracked-files",
+    });
+  }
+
+  const metadata = parseCodebaseMapMetadata(existing);
+  const existingDescriptions = parseCodebaseMap(existing);
+  const ageMs = metadata ? now - Date.parse(metadata.generatedAt) : Number.POSITIVE_INFINITY;
+  const staleReason =
+    !metadata ? "missing-metadata"
+    : metadata.fingerprint !== fingerprint ? "files-changed"
+    : metadata.fileCount !== listed.files.length ? "file-count-changed"
+    : metadata.truncated !== listed.truncated ? "truncation-changed"
+    : maxAgeMs > 0 && Number.isFinite(ageMs) && ageMs > maxAgeMs ? "expired"
+    : undefined;
+
+  if (!staleReason) {
+    return cacheAndReturn({
+      status: "fresh",
+      fileCount: metadata?.fileCount ?? listed.files.length,
+      truncated: metadata?.truncated ?? listed.truncated,
+      generatedAt: metadata?.generatedAt ?? null,
+      fingerprint: metadata?.fingerprint ?? fingerprint,
+    });
+  }
+
+  const updated = buildCodebaseMap(basePath, resolved, existingDescriptions, listed);
+  if (updated.fileCount > 0) {
+    writeCodebaseMap(basePath, updated.content);
+    return cacheAndReturn({
+      status: "updated",
+      fileCount: updated.fileCount,
+      truncated: updated.truncated,
+      generatedAt: updated.generatedAt,
+      fingerprint: updated.fingerprint,
+      reason: staleReason,
+    });
+  }
+
+  return cacheAndReturn({
+    status: "empty",
+    fileCount: 0,
+    truncated: false,
+    generatedAt: null,
+    fingerprint,
+    reason: staleReason,
+  });
+}
+
 /**
  * Write CODEBASE.md to .gsd/ directory.
  */
@@ -305,6 +549,7 @@ export function writeCodebaseMap(basePath: string, content: string): string {
   mkdirSync(root, { recursive: true });
   const outPath = join(root, "CODEBASE.md");
   writeFileSync(outPath, content, "utf-8");
+  clearFreshnessCache(basePath);
   return outPath;
 }