@automaton-labs/aib 0.0.7 → 0.0.8

package/dist/commands/session-workspace.js

@@ -1,31 +1,1836 @@
-"use strict";var De=exports&&exports.__createBinding||(Object.create?(function(e,t,n,s){s===void 0&&(s=n);var i=Object.getOwnPropertyDescriptor(t,n);(!i||("get"in i?!t.__esModule:i.writable||i.configurable))&&(i={enumerable:!0,get:function(){return t[n]}}),Object.defineProperty(e,s,i)}):(function(e,t,n,s){s===void 0&&(s=n),e[s]=t[n]})),$e=exports&&exports.__setModuleDefault||(Object.create?(function(e,t){Object.defineProperty(e,"default",{enumerable:!0,value:t})}):function(e,t){e.default=t}),ie=exports&&exports.__importStar||(function(){var e=function(t){return e=Object.getOwnPropertyNames||function(n){var s=[];for(var i in n)Object.prototype.hasOwnProperty.call(n,i)&&(s[s.length]=i);return s},e(t)};return function(t){if(t&&t.__esModule)return t;var n={};if(t!=null)for(var s=e(t),i=0;i<s.length;i++)s[i]!=="default"&&De(n,t,s[i]);return $e(n,t),n}})();Object.defineProperty(exports,"__esModule",{value:!0}),exports.isSessionHandle=M,exports.runWithSessionOverride=Ue,exports.runSessionWorkspaceCommand=Fe,exports.resolveSessionFileArgument=B,exports.saveSessionOutputJson=qe,exports.saveSessionOutputText=et,exports.saveSessionResultJson=tt,exports.saveSessionResultViewJson=nt,exports.readSessionResultViewJson=st,exports.readSessionResultJson=it,exports.captureSessionInputJson=rt,exports.captureSessionInput=ae,exports.sessionWorkspaceExists=ot,exports.useSessionGuidance=ue,exports.readSessionBooleanPref=at,exports.readSessionNumberPref=ut,exports.readSessionStringPref=ct,exports.readEffectiveSessionPathAliases=lt,exports.readSessionPathAliasOverrides=ft,exports.tryResolveCurrentSessionId=Ut;const l=ie(require("node:fs")),c=ie(require("node:path")),xe=require("node:async_hooks"),E=require("../config/env-vars"),_=require("../config/workspace-root"),b=require("../config/path-aliases"),m=require("../shared/agent-text"),u=require("../shared/errors"),je=c.join(".tmp","aib"),U="sessionDir",Ce="session.json",we="active.json",Re="aib:",Le="s_",Pe="last",Te="_last.json",F=new xe.AsyncLocalStorage,ke=["graph","inspect","code","slice","members","exports","deps","usages","duplicates","execution","rename","move","refactor","modulePlan","imports"],We=["inspect","graph","rename","move","refactor","modulePlan","imports","generic"],O={"guidance.nextLimit":{type:"number",default:2,min:0,max:100,hidden:!0},"diagnostics.hintLimit":{type:"number",default:2,min:0,max:100,hidden:!0},"inspect.code.show":{type:"boolean",default:!0,hidden:!0},"inspect.code.maxNonEmptyLines":{type:"number",default:120,min:1,max:1e4},"inspect.code.meta":{type:"boolean",default:!0,hidden:!0},"inspect.members.maxItems":{type:"number",default:20,min:1,max:1e3},"inspect.members.all":{type:"boolean",default:!1,hidden:!0},"inspect.exports.ranges":{type:"boolean",default:!1,hidden:!0},"inspect.exports.resolveStar":{type:"boolean",default:!1,hidden:!0},"inspect.graph.hubs":{type:"boolean",default:!0},"inspect.graph.entrypoints":{type:"boolean",default:!0},"inspect.graph.leaves":{type:"boolean",default:!0},"inspect.graph.edges":{type:"boolean",default:!0},"inspect.graph.symbols":{type:"boolean",default:!1,hidden:!0},"inspect.graph.symbolUsage":{type:"boolean",default:!1},"inspect.usages.detail":{type:"string",default:"locations",values:["summary","locations","code"],hidden:!0},"inspect.usages.maxLocations":{type:"number",default:12,min:1,max:1e4},"inspect.usages.maxCodeBlocks":{type:"number",default:8,min:1,max:1e4},"inspect.usages.excludeTarget":{type:"boolean",default:!1,hidden:!0}};function M(e){return e.startsWith(Re)}function Ue(e,t){return e?F.run(e,t):t()}function Fe(e,t,n){const s=t[0]??"status",i=(0,_.resolveWorkspaceRoot)(e);if(!i){if(s==="status")return(0,m.attachAgentText)({initialized:!1,active:null,source:"none",available:[],next:"Run aib help first-setup"},["session not ready","","No aib.json was found.","","If you are a user:","ask your agent to set up AIB for this repo:","aib help first-setup","","If you are an agent:","run:","aib help first-setup","","Then follow the setup from the intended repository root."].join(`
-`));(0,_.resolveRequiredWorkspaceRoot)(e)}const r=i?.root??e;if(Rt(r),s==="init")return dt(r,t.slice(1));if(s==="status")return Dt(r);if(s==="list")return St(r);if(s==="use")return ht(r,t.slice(1));if(s==="where")return mt(r,t.slice(1));if(s==="read")return It(r,t.slice(1),n);if(s==="write")return Je(r,t.slice(1),n);if(s==="prefs")return Be(r,t.slice(1),n);if(s==="aliases")return Me(r,t.slice(1),n);if(s==="clear")return Ct(r);throw new u.CliError("UNKNOWN_SESSION_WORKSPACE_COMMAND",`Unknown session workspace command: ${s}`)}function Me(e,t,n){const s=t[0]??"get";if(s==="get"){const i=A(e),r=(0,b.readConfigPathAliases)(e),o=(0,b.normalizePathAliasMap)(i.pathAliases??{},"session path aliases"),a={aliases:(0,b.effectivePathAliases)(e,o),config:r,session:o};return(0,m.attachAgentText)(a,V(a))}if(s==="set"){const i=A(e),r=t.includes("--stdin")?Ve(n):ze(t.slice(1)),o=(0,b.normalizePathAliasMap)(i.pathAliases??{},"session path aliases"),a={};for(const[d,p]of Object.entries(r)){const S=(0,b.normalizePathAliasName)(d,"session path aliases");if(typeof p!="string"||p.trim()==="")throw new u.CliError("INVALID_PATH_ALIAS_TARGET",`session path alias ${d} must be a non-empty path string.`);o[S]=p.trim().replace(/\\/g,"/"),a[S]=o[S]}i.pathAliases=o,g(e,i);const f={updated:a,aliases:(0,b.effectivePathAliases)(e,o)};return(0,m.attachAgentText)(f,V(f))}if(s==="clear"){const i=A(e),r=t.slice(1).filter(d=>!d.startsWith("--")),o=(0,b.normalizePathAliasMap)(i.pathAliases??{},"session path aliases"),a=[];if(r.length===0)a.push(...Object.keys(o).sort()),delete i.pathAliases;else{for(const d of r){const p=(0,b.normalizePathAliasName)(d,"session path aliases");Object.prototype.hasOwnProperty.call(o,p)&&(a.push(p),delete o[p])}Object.keys(o).length>0?i.pathAliases=o:delete i.pathAliases}g(e,i);const f={cleared:a,aliases:(0,b.effectivePathAliases)(e,i.pathAliases??{})};return(0,m.attachAgentText)(f,V(f))}throw new u.CliError("UNKNOWN_SESSION_ALIASES_COMMAND",`Unknown session aliases command: ${s}`,{expected:"aib session aliases get | set | clear"})}function Ve(e){if(!y(e))throw new u.CliError("INVALID_SESSION_ALIASES_STDIN","session aliases set --stdin expects a JSON object.");const t=y(e.aliases)?e.aliases:e,n={};for(const[s,i]of Object.entries(t))typeof i=="string"&&(n[s]=i);return n}function ze(e){if(e.length===0||e.length%2!==0)throw new u.CliError("SESSION_ALIASES_SET_USAGE","Usage: aib session aliases set <name> <path> [<name> <path>...] or session aliases set --stdin");const t={};for(let n=0;n<e.length;n+=2)t[e[n]??""]=e[n+1]??"";return t}function V(e){if(y(e.updated))return re("aliases.updated",e.updated);if(Array.isArray(e.cleared)){const t=e.cleared.filter(n=>typeof n=="string");return t.length>0?["aliases.cleared",...t].join(`
-`):"aliases.cleared none"}if(y(e.aliases)){const t=re("aliases",e.aliases).split(`
-`);return t.length===1&&t.push("none"),t.join(`
-`)}return null}function re(e,t){const n=[e];for(const[s,i]of Object.entries(t).sort(([r],[o])=>r.localeCompare(o)))n.push(`@${s}/=${String(i)}`);return n.join(`
-`)}function Je(e,t,n){const s=t[0]??"",i=t[1]??"";if(!s||!i)throw new u.CliError("SESSION_WRITE_USAGE","Usage: aib session write <kind> <name> --stdin");if(n===void 0)throw new u.CliError("STDIN_REQUIRED","session write expects JSON on stdin and the --stdin flag.");const r=A(e),o=Z(r,s,i);x(o,n);const a=C(r,"inputs",s,i,o);Ne(r,s,n),g(e,r);const f={written:a.handle,file:h(e,o)},d=ue(e,"session.write.from",`Use with --from ${a.handle}`);return d&&(f.next=d),f}function Be(e,t,n){const s=t[0]??"get";if(s==="get"){const i=A(e),r=t.includes("--all"),o=t.slice(1).find(p=>!p.startsWith("--")),a=r?Ye(i):Ze(i.prefs??{}),f=Ke(a,o),d=r?{prefs:f}:{overrides:f,defaults:"omitted; use session prefs get --all"};return(0,m.attachAgentText)(d,z(d))}if(s==="set"){const i=A(e),r=t.includes("--stdin")?He(n):Ge(t.slice(1)),o=i.prefs??{},a={};for(const[d,p]of Object.entries(r)){const S=oe(d),N=Qe(S,p);o[S]=N,a[S]=N}i.prefs=o,g(e,i);const f={updated:a};return(0,m.attachAgentText)(f,z(f))}if(s==="clear"){const i=A(e),r=t.slice(1).filter(d=>!d.startsWith("--")),o=i.prefs??{},a=[];if(r.length===0)a.push(...Object.keys(o).sort()),delete i.prefs;else{for(const d of r){const p=oe(d);Object.prototype.hasOwnProperty.call(o,p)&&(a.push(p),delete o[p])}Object.keys(o).length>0?i.prefs=o:delete i.prefs}g(e,i);const f={cleared:a};return(0,m.attachAgentText)(f,z(f))}throw new u.CliError("UNKNOWN_SESSION_PREFS_COMMAND",`Unknown session prefs command: ${s}`,{expected:"aib session prefs get | set | clear"})}function Ke(e,t){if(!t)return e;const n={};for(const[s,i]of Object.entries(e))(s===t||s.startsWith(`${t}.`))&&(n[s]=i);return n}function z(e){if(y(e.updated))return J("prefs.updated",e.updated);if(Array.isArray(e.cleared)){const t=e.cleared.filter(n=>typeof n=="string");return t.length>0?["prefs.cleared",...t].join(`
-`):"prefs.cleared none"}if(y(e.overrides)){const t=J("prefs",e.overrides).split(`
-`);return t.length===1&&t.push("no overrides"),typeof e.defaults=="string"&&t.push(e.defaults),t.join(`
-`)}return y(e.prefs)?J("prefs",e.prefs):null}function J(e,t){const n=[e];for(const[s,i]of Object.entries(t).sort(([r],[o])=>r.localeCompare(o)))n.push(`${s}=${String(i)}`);return n.join(`
-`)}function He(e){if(!y(e))throw new u.CliError("INVALID_SESSION_PREFS_STDIN","session prefs set --stdin expects a JSON object.");const t=y(e.prefs)?e.prefs:e,n={};for(const[s,i]of Object.entries(t))n[s]=i;return n}function Ge(e){if(e.length===0||e.length%2!==0)throw new u.CliError("SESSION_PREFS_SET_USAGE","Usage: aib session prefs set <key> <value> [<key> <value>...] or session prefs set --stdin");const t={};for(let n=0;n<e.length;n+=2){const s=e[n]??"",i=e[n+1]??"";t[s]=i}return t}function oe(e){if(Object.prototype.hasOwnProperty.call(O,e))return e;throw new u.CliError("UNKNOWN_SESSION_PREF",`Unknown session preference: ${e}`,{available:Object.keys(O)})}function Qe(e,t){const n=O[e];if(n.type==="boolean"){if(typeof t=="boolean")return t;if(typeof t=="string"){const i=t.trim().toLowerCase();if(i==="true")return!0;if(i==="false")return!1}throw new u.CliError("INVALID_SESSION_PREF_VALUE",`${e} expects true or false.`)}if(n.type==="string"){if(typeof t!="string")throw new u.CliError("INVALID_SESSION_PREF_VALUE",`${e} expects one of: ${n.values.join(", ")}.`);const i=t.trim();if(!n.values.includes(i))throw new u.CliError("INVALID_SESSION_PREF_VALUE",`${e} expects one of: ${n.values.join(", ")}.`);return i}const s=typeof t=="number"?t:typeof t=="string"?Number(t):NaN;if(!Number.isInteger(s)||s<n.min||s>n.max)throw new u.CliError("INVALID_SESSION_PREF_VALUE",`${e} expects an integer from ${n.min} to ${n.max}.`);return s}function Ye(e){const t={};for(const n of Object.keys(O)){const s=O[n];"hidden"in s&&s.hidden||(s.type==="boolean"?t[n]=ce(e,n,s.default):s.type==="number"?t[n]=K(e,n,s.default):t[n]=le(e,n,s.default))}return t}function Ze(e){const t={};for(const[n,s]of Object.entries(e))Xe(n)||(t[n]=s);return t}function Xe(e){if(!Object.prototype.hasOwnProperty.call(O,e))return!1;const t=O[e];return"hidden"in t&&t.hidden===!0}function B(e,t){if(!M(t))return t;const n=A(e),s=Oe(t),i=s.scope==="input"?n.inputs:n.outputs,r=s.scope==="input"?s.kind:s.scope,o=i[r],a=s.name==="last"?o?.last:s.name,f=a?o?.items[a]:void 0;if(!f)throw new u.CliError("SESSION_HANDLE_NOT_FOUND",`Session handle not found: ${t}`,{handle:t,sessionDir:h(e,n.rootDir)});return f.file}function qe(e,t,n,s){const i=A(e),r=Ae(i,t,n,".json");l.mkdirSync(c.dirname(r),{recursive:!0}),l.writeFileSync(r,`${JSON.stringify(s,null,2)}
-`);const o=C(i,"outputs",t,n,r);return g(e,i),{saved:o.handle,last:`aib:${t}:last`,file:h(e,r)}}function et(e,t,n,s,i=".txt"){const r=A(e),o=Ae(r,t,n,i);l.mkdirSync(c.dirname(o),{recursive:!0}),l.writeFileSync(o,s);const a=C(r,"outputs",t,n,o);return g(e,r),{saved:a.handle,last:`aib:${t}:last`,file:h(e,o)}}function tt(e,t,n,s){const i=v(e);if(!i)return null;const r=I(t),o=I(n),a=c.join(i.rootDir,"outputs","result",r,`${o}.json`);return x(a,s),{saved:`aib:result:${r}:${o}`,file:h(e,a)}}function nt(e,t,n){const s=v(e);if(!s)return null;const i=I(t),r=c.join(s.rootDir,"outputs","result",`${i}.json`);return x(r,n),{saved:`aib:${i}`,file:h(e,r)}}function st(e,t){const n=A(e),s=I(t),i=c.join(n.rootDir,"outputs","result",`${s}.json`);if(!l.existsSync(i))throw new u.CliError("SESSION_RESULT_NOT_FOUND",`Result handle not found: aib:${s}`,{handle:`aib:${s}`,sessionDir:h(e,n.rootDir)});const r=JSON.parse(l.readFileSync(i,"utf8"));if(!r||typeof r!="object"||Array.isArray(r))throw new u.CliError("INVALID_SESSION_RESULT",`Result artifact is not a JSON object: aib:${s}`);return r}function it(e,t,n){const s=A(e),i=I(t),r=I(n),o=c.join(s.rootDir,"outputs","result",i,`${r}.json`);if(!l.existsSync(o))throw new u.CliError("SESSION_RESULT_NOT_FOUND",`Result handle not found: aib:result:${i}:${r}`,{handle:`aib:result:${i}:${r}`,sessionDir:h(e,s.rootDir)});const a=JSON.parse(l.readFileSync(o,"utf8"));if(!a||typeof a!="object"||Array.isArray(a))throw new u.CliError("INVALID_SESSION_RESULT",`Result artifact is not a JSON object: aib:result:${i}:${r}`);return a}function rt(e,t,n,s){return ae(e,t,n,s,{format:"json",text:JSON.stringify(s,null,2)})}function ae(e,t,n,s,i){const r=v(e);if(!r)return null;const o=i??{format:"json",text:JSON.stringify(s,null,2)},a=o.format==="dsl"?Z(r,t,n,".dsl"):Z(r,t,n,".json");o.format==="dsl"?(_e(a,o.text),x(Ft(r,t,n),s)):x(a,s);const f=C(r,"inputs",t,n,a);return Ne(r,t,s,o),g(e,r),{handle:f.handle,file:h(e,a)}}function ot(e){return l.existsSync(L(e))}function ue(e,t,n,s=-1){const i=v(e);if(!i)return n;const r=s>=0?s:K(i,"guidance.nextLimit",2),o=i.guidance??{},a=o[t]??{shown:0,limit:r};if(a.limit=r,a.shown>=a.limit){o[t]=a,i.guidance=o,g(e,i);return}return a.shown+=1,o[t]=a,i.guidance=o,g(e,i),n}function at(e,t,n){const s=v(e),i=O[t],r=typeof n=="boolean"?n:i.type==="boolean"?i.default:!1;return s?ce(s,t,r):r}function ut(e,t,n){const s=v(e),i=O[t],r=typeof n=="number"?n:i.type==="number"?i.default:0,o=(0,_.readWorkspaceNumberConfig)(e,t,r);return s?K(s,t,o):o}function ct(e,t,n){const s=v(e),i=O[t],r=typeof n=="string"?n:i.type==="string"?i.default:"";return s?le(s,t,r):r}function lt(e){try{const t=v(e);return(0,b.effectivePathAliases)(e,t?.pathAliases??{})}catch(t){if(t instanceof u.CliError&&t.code==="MULTIPLE_AIB_SESSIONS")return(0,b.effectivePathAliases)(e,{});throw t}}function ft(e){try{const t=v(e);return(0,b.normalizePathAliasMap)(t?.pathAliases??{},"session path aliases")}catch(t){if(t instanceof u.CliError&&t.code==="MULTIPLE_AIB_SESSIONS")return{};throw t}}function ce(e,t,n){const s=e.prefs?.[t];return typeof s=="boolean"?s:n}function K(e,t,n){const s=e.prefs?.[t];return typeof s=="number"&&Number.isFinite(s)?s:n}function le(e,t,n){const s=e.prefs?.[t];return typeof s=="string"?s:n}function dt(e,t){const n=w(t,"--dir"),s=Q(e,n,!0),i=w(t,"--name"),r=$(i??Y()??Jt()),o=c.join(s.rootDir,r),a=new Date().toISOString(),d=R(e,r)??{version:1,sessionId:r,cwd:c.resolve(e),rootDir:o,createdAt:a,updatedAt:a,outputs:{},inputs:{},guidance:{}};d.sessionId=r,d.rootDir=o,d.updatedAt=a,me(d),g(e,d),be(e,d,!0);const p=D(e),S=p?Object.keys(p.sessions).length:1,N={session:r,dir:h(e,d.rootDir),sessionDir:h(e,s.rootDir),sessionDirSource:s.source,sessionCount:S,bind:`${E.CLI_ENV.session}=${r}`,next:S===1?"Run AIB commands without -s for now. AIB will tell you if multiple sessions exist.":`Use aib -s ${r} <command> or set ${E.CLI_ENV.session}=${r}.`};return s.ignoredRequestedDir&&(N.note=`${U} from aib.json is in effect; --dir was ignored.`,N.requestedDir=s.ignoredRequestedDir),(0,m.attachAgentText)(N,pt(N))}function pt(e){const t=String(e.session??""),n=typeof e.sessionCount=="number"?e.sessionCount:1,s=[`session ready: ${t}`,""];return typeof e.note=="string"&&e.note&&(s.push("aib.json sessionDir is in effect; --dir was ignored."),s.push("")),n===1?(s.push("Only one AIB session exists in this repo."),s.push("You can run AIB commands without -s for now."),s.push("AIB will tell you if multiple sessions exist and you need to choose one.")):(s.push("Multiple AIB sessions exist in this repo."),s.push("Use this session explicitly:"),s.push(`aib -s ${t} <command>`),s.push(""),s.push("Or bind it in this shell:"),s.push(`${E.CLI_ENV.session}=${t}`)),s.join(`
-`)}function St(e){const t=D(e),n=k(e);return{active:n.sessionId??t?.activeSessionId??null,source:n.source,sessions:t?Object.values(t.sessions).sort((s,i)=>s.sessionId.localeCompare(i.sessionId)).map(s=>`${s.sessionId} -> ${h(e,s.rootDir)}`):[]}}function ht(e,t){const n=t[0]??"";if(!n)throw new u.CliError("SESSION_USE_ID_REQUIRED","Usage: aib session use <sessionId>");const s=$(n),i=D(e),r=i?.sessions[s];if(!r)throw new u.CliError("SESSION_NOT_FOUND",`Session not found: ${s}`,{available:i?Object.keys(i.sessions).sort():[]});return T(e,{...i??ge(e),activeSessionId:s}),{session:s,dir:h(e,r.rootDir),bind:`${E.CLI_ENV.session}=${s}`,next:`Use aib -s ${s} <command> or set ${E.CLI_ENV.session}=${s}.`}}function mt(e,t){const n=t[0]??"";if(!n)throw new u.CliError("SESSION_WHERE_HANDLE_REQUIRED","Usage: aib session where <handle>");const s=B(e,n),i={handle:n,file:h(e,s)};return(0,m.attachAgentText)(i,[n,i.file].join(`
-`))}function It(e,t,n){if(t.includes("--stdin")){if(!y(n))throw new u.CliError("INVALID_SESSION_READ_STDIN","session read --stdin expects a JSON object payload.");const r=yt(n);if(r.length===1){const a=H(e,r[0]);return(0,m.attachAgentText)(a,G(a))}const o={reads:r.map(a=>gt(e,a))};return(0,m.attachAgentText)(o,G(o))}const s=t[0]??"";if(!s)throw new u.CliError("SESSION_READ_HANDLE_REQUIRED","Usage: aib session read <handle> [--head <n> | --offset <n> --limit <n>]");const i=H(e,{handle:s,...vt(t.slice(1))});return(0,m.attachAgentText)(i,G(i))}function yt(e){if(Array.isArray(e.reads))return e.reads.map((t,n)=>{if(typeof t=="string"){if(!M(t))throw new u.CliError("INVALID_SESSION_READ_ROW",`session read row at index ${n} must be an aib: handle string or an object.`);return{handle:t}}if(!y(t))throw new u.CliError("INVALID_SESSION_READ_ROW",`session read row at index ${n} must be an aib: handle string or an object.`);return fe(t,n)});if(typeof e.handle=="string"||typeof e.read=="string")return[fe(e,0)];throw new u.CliError("INVALID_SESSION_READ_STDIN","Expected { reads: [{ handle }] } or { handle }.")}function fe(e,t){const n=X(e.handle)??X(e.read);if(!n)throw new u.CliError("SESSION_READ_HANDLE_REQUIRED",`session read row at index ${t} requires handle.`);return{handle:n,...e.rawInput===!0?{rawInput:!0}:{},...pe(e,t)}}function gt(e,t){try{return H(e,t)}catch(n){if(n instanceof u.CliError){const s=y(n.details)?n.details:{};return{read:t.handle,error:n.code,...typeof s.next=="string"?{next:s.next}:{}}}return{read:t.handle,error:"UNEXPECTED_ERROR"}}}function H(e,t){Ot(t);const n=Oe(t.handle),s=B(e,t.handle);if(n.scope==="input"&&!t.rawInput){const r=Nt(n.kind,t.handle);return{read:t.handle,file:h(e,s),next:r?`Edit file, then rerun: ${r}`:"Edit file, then rerun the command with --from <handle>."}}if(n.scope==="graph"||n.scope==="usages"){const r=n.scope==="graph"?`aib inspect graph --from-file ${t.handle} --focus <file>`:`aib inspect usages --from-file ${t.handle} --focus <name>`;throw new u.CliError("SESSION_ARTIFACT_NOT_READABLE",`${n.scope} artifacts are reusable indexes, not agent-readable context.`,{handle:t.handle,kind:n.scope,next:r})}if(n.scope==="duplicates"){const r=l.readFileSync(s,"utf8");return{read:t.handle,content:bt(e,t.handle,s,r,t)}}const i=l.readFileSync(s,"utf8");return{read:t.handle,content:At(s,i,t)}}function bt(e,t,n,s,i){const r=Et(e,t,n,s);return i.head!==void 0||i.offset!==void 0||i.limit!==void 0?Se(r,i):r}function Et(e,t,n,s){let i;try{i=JSON.parse(s)}catch{return de(t,n,s)}if(!y(i))return de(t,n,s);const r=[],o=Array.isArray(i.targetPaths)?i.targetPaths.filter(S=>typeof S=="string"&&S!==""):[],a=o.length===1?h(e,o[0]):o.length>1?`${o.length} scopes`:"";r.push(a?`duplicates ${a}`:"duplicates");const f=typeof i.summary=="string"?i.summary:`${j(i.itemCount)} ${te(j(i.itemCount),"name")}`;r.push(f);const d=Array.isArray(i.items)?i.items.filter(y):[];for(const S of d){const N=typeof S.name=="string"?S.name:"",ve=j(S.declarationCount),ne=j(S.variantCount),se=j(S.exactCopyCount);N&&r.push(`${N} x${ve}, ${ne} ${te(ne,"variant")}${se>0?`, exact x${se}`:""}`)}const p=j(i.hiddenItemCount);return p>0&&r.push(`+ ${p} ${te(p,"name")}`),r.push(`raw: aib session where ${t}`),r.join(`
-`)}function de(e,t,n){return[`saved artifact ${e}`,`${n.length} bytes`,`raw: ${t}`].join(`
-`)}function At(e,t,n){if(n.head!==void 0||n.offset!==void 0||n.limit!==void 0)return Se(t,n);if(c.extname(e).toLowerCase()!==".json")return t;try{return JSON.parse(t)}catch{return t}}function G(e){const t=Array.isArray(e.reads)?e.reads.filter(y):[e];if(t.length===0)return null;const n=[],s=t.length>1;for(const i of t){const r=typeof i.read=="string"?i.read:"",o=i.content,a=_t(o);if(a!==null){s&&r&&n.push(`// ${r}`),n.push(a.trimEnd());continue}if(typeof i.file=="string"){s&&r?n.push(`// ${r}`):r&&n.push(`input ${r}`),n.push(`file: ${i.file}`),typeof i.next=="string"&&n.push(`next: ${i.next}`);continue}const f=typeof i.error=="string"?i.error:"";if(f){s&&r&&n.push(`// ${r}`),n.push(`error: ${f}`),typeof i.next=="string"&&n.push(`next: ${i.next}`);continue}return null}return n.join(`
-`)}function _t(e){return typeof e=="string"?e:e===void 0?null:JSON.stringify(e,null,2)}function Nt(e,t){return e==="inspect"?`aib inspect --from ${t}`:e==="graph"?`aib inspect graph --from ${t}`:e==="rename"?`aib rename preview --from ${t}`:e==="move"?`aib move toFile preview --from ${t}`:e==="refactor"?`aib refactor batch preview --from ${t}`:e==="modulePlan"?`aib modulePlan preview --from ${t}`:e==="imports"?`aib imports normalize preview --from ${t}`:null}function Ot(e){if(e.head!==void 0&&(e.offset!==void 0||e.limit!==void 0))throw new u.CliError("SESSION_READ_RANGE_CONFLICT","Use either head or offset/limit, not both.")}function vt(e){const t={},n=w(e,"--head"),s=w(e,"--offset"),i=w(e,"--limit");return n!==void 0&&(t.head=n),s!==void 0&&(t.offset=s),i!==void 0&&(t.limit=i),{...e.includes("--raw-input")?{rawInput:!0}:{},...pe(t,0)}}function pe(e,t){const n=q(e.head,`session read row at index ${t} has invalid head.`),s=q(e.offset,`session read row at index ${t} has invalid offset.`),i=zt(e.limit,`session read row at index ${t} has invalid limit.`);return{...n!==void 0?{head:n}:{},...s!==void 0?{offset:s}:{},...i!==void 0?{limit:i}:{}}}function Se(e,t){if(t.head===void 0&&t.offset===void 0&&t.limit===void 0)return e;const n=e.split(/\r?\n/),s=t.head!==void 0?0:t.offset??0,i=t.head!==void 0?t.head:t.limit!==void 0?s+t.limit:void 0;return n.slice(s,i).join(`
-`)}function Dt(e){const t=D(e),n=k(e),s=t?Object.keys(t.sessions).sort():[];if(n.source==="ambiguous")return(0,m.attachAgentText)({ok:!1,code:"MULTIPLE_AIB_SESSIONS",error:"Multiple AIB sessions exist. Select one explicitly.",available:s,next:`Use aib -s <session> <command> or set ${E.CLI_ENV.session}=<session>.`},jt(s));const i=n.sessionId?R(e,n.sessionId):null;if(!i){const o={initialized:!1,active:n.sessionId??null,source:n.source,available:s,next:n.sessionId?`Run aib session init --name ${n.sessionId}`:"Run aib session init --name <name>"};return(0,m.attachAgentText)(o,$t(o))}g(e,i);const r={initialized:!0,session:i.sessionId??n.sessionId,active:i.sessionId??n.sessionId,source:n.source,available:s,sessionDir:h(e,i.rootDir),aliases:(0,b.effectivePathAliases)(e,i.pathAliases??{}),latest:Mt(i),dirs:Vt(e,i)};return(0,m.attachAgentText)(r,xt(r))}function $t(e){const t=typeof e.active=="string"&&e.active?e.active:null;return t?["session not ready","",`Session ${t} was not found.`,"Create it:",`aib session init --name ${t}`].join(`
-`):["session not ready","","No AIB sessions exist in this repo.","Create one:","aib session init --name <name>"].join(`
-`)}function xt(e){const t=String(e.session??""),n=e.aliases&&typeof e.aliases=="object"&&!Array.isArray(e.aliases)?e.aliases:{},s=[`session: ${t}`],i=Object.entries(n).filter(([,r])=>typeof r=="string"&&r.trim()!=="").sort(([r],[o])=>r.localeCompare(o)).map(([r,o])=>`@${r} -> ${String(o)}`);return i.length>0&&s.push("","aliases:",...i),e.source==="single"&&s.push("","Only one AIB session exists in this repo.","You can run AIB commands without -s."),s.join(`
-`)}function jt(e){return["multiple AIB sessions","","available:",...e,"","Choose one:","aib -s <session> <command>","","Or bind it in this shell:",`${E.CLI_ENV.session}=<session>`,"","If none of these sessions is yours, create a new one:","aib session init --name <name>"].join(`
-`)}function Ct(e){const t=k(e),n=D(e),s=n?Object.keys(n.sessions).sort():[];if(t.source==="ambiguous")return(0,m.attachAgentText)({ok:!1,code:"MULTIPLE_AIB_SESSIONS",error:"Multiple AIB sessions exist. Select one explicitly.",available:s,next:"Use aib -s <session> session clear."},wt(s));const i=t.sessionId?R(e,t.sessionId):null;if(!i)return(0,m.attachAgentText)({cleared:!1,reason:"session-not-initialized"},["No AIB sessions exist in this repo.","","Create one:","aib session init --name <name>"].join(`
-`));he(i,{touch:!0}),g(e,i);const r=i.sessionId??t.sessionId??"";return(0,m.attachAgentText)({cleared:!0,session:r,dir:h(e,i.rootDir)},[`session cleared: ${r}`,"","Inputs and outputs were pruned.","You can keep using this session."].join(`
-`))}function he(e,t){l.rmSync(c.join(e.rootDir,"inputs"),{recursive:!0,force:!0}),l.rmSync(c.join(e.rootDir,"outputs"),{recursive:!0,force:!0}),e.inputs={},e.outputs={},e.guidance={},t.touch&&(e.updatedAt=new Date().toISOString()),me(e)}function wt(e){return["multiple AIB sessions","","available:",...e,"","Clear one explicitly only if it is yours:","aib -s <session> session clear","","If none of these sessions is yours, create a new one:","aib session init --name <name>"].join(`
-`)}function Rt(e){const t=Lt(e),n=D(e);if(!n)return;const s=Date.now();let i=!1;for(const[r,o]of Object.entries(n.sessions)){const a=P(o.rootDir);if(!l.existsSync(a)){delete n.sessions[r],i=!0,n.activeSessionId===r&&delete n.activeSessionId;continue}const f=Date.parse(o.updatedAt);if(!Number.isFinite(f))continue;const d=s-f;if(t.autoDelete&&t.ttlDeleteMs>0&&d>t.ttlDeleteMs){l.rmSync(o.rootDir,{recursive:!0,force:!0}),delete n.sessions[r],i=!0,n.activeSessionId===r&&delete n.activeSessionId;continue}if(t.autoClean&&t.ttlCleanMs>0&&d>t.ttlCleanMs){const p=Ie(e,o.rootDir,r);p&&(he(p,{touch:!1}),Pt(p))}}if(i){if(!n.activeSessionId){const r=Object.keys(n.sessions).sort()[0];r&&(n.activeSessionId=r)}T(e,n)}}function Lt(e){const t=(0,_.readWorkspaceNumberConfig)(e,"session.ttlMinutes",60),n=(0,_.readWorkspaceNumberConfig)(e,"session.ttlDeleteMinutes",t),s=(0,_.readWorkspaceNumberConfig)(e,"session.ttlCleanMinutes",t);return{autoDelete:(0,_.readWorkspaceBooleanConfig)(e,"session.autoDelete",!0),ttlDeleteMs:n>0?n*6e4:0,autoClean:(0,_.readWorkspaceBooleanConfig)(e,"session.autoClean",!0),ttlCleanMs:s>0?s*6e4:0}}function me(e){for(const t of ke)l.mkdirSync(c.join(e.rootDir,"outputs",t),{recursive:!0});for(const t of We)l.mkdirSync(c.join(e.rootDir,"inputs",t),{recursive:!0})}function R(e,t){const s=D(e)?.sessions[t];return s?Ie(e,s.rootDir,t):null}function v(e){const t=Ee(e);return t.sessionId?R(e,t.sessionId):null}function Ie(e,t,n){try{const s=JSON.parse(l.readFileSync(P(t),"utf8"));if(!s||typeof s!="object"||Array.isArray(s))return null;const i=s;return i.version!==1||typeof i.rootDir!="string"?null:(i.sessionId=i.sessionId??n,i)}catch{return null}}function A(e){const t=v(e);if(!t)throw new u.CliError("SESSION_WORKSPACE_NOT_INITIALIZED","Session workspace is not initialized.",{session:Y()??null,next:"Run aib session init --name <name>",help:"aib help session"});return g(e,t),t}function g(e,t){t.updatedAt=new Date().toISOString(),l.mkdirSync(t.rootDir,{recursive:!0}),l.writeFileSync(P(t.rootDir),`${JSON.stringify(t,null,2)}
-`),be(e,t,!1)}function Pt(e){l.mkdirSync(e.rootDir,{recursive:!0}),l.writeFileSync(P(e.rootDir),`${JSON.stringify(e,null,2)}
-`)}function Q(e,t,n=!1){const s=(0,_.resolveWorkspaceRoot)(e),i=s?.root??e,r=s?X(s.config[U]):void 0;if(r)return{rootDir:ye(i,r),source:"aib.json",...t?{ignoredRequestedDir:t}:{}};const a=ye(i,t??je);return n&&s&&(0,_.updateWorkspaceConfig)(i,{[U]:Tt(i,a)}),{rootDir:a,source:t?"request":"default"}}function ye(e,t){const n=c.resolve(e,t);return c.basename(n).toLowerCase()==="aib"?n:c.join(n,"aib")}function Tt(e,t){const n=c.relative(e,t);return n&&!n.startsWith("..")&&!c.isAbsolute(n)?n.replace(/\\/g,"/"):t.replace(/\\/g,"/")}function L(e){return c.join(Q(e).rootDir,Ce)}function kt(e){return c.join(Q(e).rootDir,we)}function P(e){return c.join(e,"session.json")}function D(e){try{const t=JSON.parse(l.readFileSync(L(e),"utf8"));if(!t||typeof t!="object"||Array.isArray(t))return null;const n=t;return n.version!==1||!n.sessions||typeof n.sessions!="object"?null:{version:1,cwd:typeof n.cwd=="string"?n.cwd:c.resolve(e),...typeof n.activeSessionId=="string"?{activeSessionId:n.activeSessionId}:{},sessions:n.sessions}}catch{return null}}function T(e,t){t.cwd=c.resolve((0,_.resolveWorkspaceRoot)(e)?.root??e),l.mkdirSync(c.dirname(L(e)),{recursive:!0}),l.writeFileSync(L(e),`${JSON.stringify(t,null,2)}
-`),Wt(e,t.activeSessionId)}function ge(e){return{version:1,cwd:c.resolve(e),sessions:{}}}function Wt(e,t){const n=kt(e);if(l.mkdirSync(c.dirname(n),{recursive:!0}),!t){l.rmSync(n,{force:!0});return}l.writeFileSync(n,`${JSON.stringify({sessionId:t,updatedAt:new Date().toISOString()},null,2)}
-`)}function be(e,t,n){const s=t.sessionId??Y()??"";if(!s)return;const i=D(e)??ge(e);i.sessions[s]={sessionId:s,rootDir:t.rootDir,createdAt:i.sessions[s]?.createdAt??t.createdAt,updatedAt:t.updatedAt},(n||!i.activeSessionId)&&(i.activeSessionId=s),T(e,i)}function Bt(e,t){const n=D(e);if(!(!n||!t)){if(delete n.sessions[t],n.activeSessionId===t){const s=Object.keys(n.sessions).sort()[0];s?n.activeSessionId=s:delete n.activeSessionId}T(e,n)}}function Ee(e){const t=F.getStore();if(t)return{sessionId:$(t),source:"override"};const n=process.env[E.CLI_ENV.session];if(n&&n.trim())return{sessionId:$(n),source:"env"};const s=process.env[E.CLI_ENV.legacySession];if(s&&s.trim())return{sessionId:$(s),source:"legacy-env"};const i=D(e),r=i?Object.keys(i.sessions).sort():[];if(r.length===1)return{sessionId:r[0],source:"single"};if(r.length>1)throw new u.CliError("MULTIPLE_AIB_SESSIONS","Multiple AIB sessions exist. Select one explicitly.",{available:r,next:`Use aib -s <session> <command> or set ${E.CLI_ENV.session}=<session>.`});return{sessionId:null,source:"none"}}function k(e){try{return Ee(e)}catch(t){if(t instanceof u.CliError&&t.code==="MULTIPLE_AIB_SESSIONS")return{sessionId:null,source:"ambiguous"};throw t}}function Ut(e){const t=k(e);return{sessionId:t.sessionId,sessionSource:t.source}}function Y(){const e=F.getStore();if(e)return $(e);const t=process.env[E.CLI_ENV.session];if(t&&t.trim())return $(t);const n=process.env[E.CLI_ENV.legacySession];return n&&n.trim()?$(n):null}function Ae(e,t,n,s){return c.join(e.rootDir,"outputs",I(t),`${I(n)}${ee(s)}`)}function Z(e,t,n,s=".json"){return c.join(e.rootDir,"inputs",I(t),`${I(n)}${ee(s)}`)}function Ft(e,t,n){return c.join(e.rootDir,"inputs",I(t),`${I(n)}.compiled.json`)}function W(e,t,n=".json"){return c.join(e.rootDir,"inputs",I(t),n===".json"?Te:`_last${ee(n)}`)}function x(e,t){l.mkdirSync(c.dirname(e),{recursive:!0}),l.writeFileSync(e,`${JSON.stringify(t,null,2)}
-`)}function _e(e,t){l.mkdirSync(c.dirname(e),{recursive:!0}),l.writeFileSync(e,t.endsWith(`
-`)?t:`${t}
-`,"utf8")}function Ne(e,t,n,s){const i=I(t),r=s??{format:"json",text:JSON.stringify(n,null,2)},o=r.format==="dsl"?W(e,i,".dsl"):W(e,i,".json");r.format==="dsl"?(_e(o,r.text),x(c.join(e.rootDir,"inputs",i,"_last.compiled.json"),n),l.rmSync(W(e,i,".json"),{force:!0})):(x(o,n),l.rmSync(W(e,i,".dsl"),{force:!0}),l.rmSync(c.join(e.rootDir,"inputs",i,"_last.compiled.json"),{force:!0})),C(e,"inputs",i,Pe,o)}function C(e,t,n,s,i){const r=I(n),o=I(s),a=t==="inputs"?`aib:input:${r}:${o}`:`aib:${r}:${o}`,f=new Date().toISOString(),d=e[t],p=d[r]??{items:{}},S={handle:a,file:i,createdAt:p.items[o]?.createdAt??f,updatedAt:f};return p.items[o]=S,p.last=o,d[r]=p,S}function Oe(e){const t=e.split(":");if(t[0]!=="aib")throw new u.CliError("INVALID_SESSION_HANDLE",`Invalid session handle: ${e}`);if(t[1]==="input"&&t.length===4)return{scope:"input",kind:t[2]??"",name:t[3]??""};if(t.length===3)return{scope:t[1]??"",kind:t[1]??"",name:t[2]??""};throw new u.CliError("INVALID_SESSION_HANDLE",`Invalid session handle: ${e}`,{expected:"aib:<kind>:<name> or aib:input:<kind>:<name>"})}function Mt(e){const t={};for(const[n,s]of Object.entries(e.outputs))s.last&&(t[n]=`aib:${n}:${s.last}`);for(const[n,s]of Object.entries(e.inputs))s.last&&(t[`input:${n}`]=`aib:input:${n}:${s.last}`);return t}function Vt(e,t){return{outputs:h(e,c.join(t.rootDir,"outputs")),inputs:h(e,c.join(t.rootDir,"inputs"))}}function w(e,t){const n=e.indexOf(t);return n>=0?e[n+1]:void 0}function X(e){return typeof e=="string"&&e.trim()!==""?e.trim():void 0}function q(e,t){if(e===void 0)return;const n=typeof e=="number"?e:typeof e=="string"?Number(e):Number.NaN;if(!Number.isInteger(n)||n<0)throw new u.CliError("INVALID_SESSION_READ_RANGE",t);return n}function zt(e,t){if(e===void 0)return;const n=q(e,t);if(n!==void 0){if(n<=0)throw new u.CliError("INVALID_SESSION_READ_RANGE",t);return n}}function y(e){return!!e&&typeof e=="object"&&!Array.isArray(e)}function I(e){const t=e.trim().replace(/[^A-Za-z0-9._-]/g,"-").replace(/^-+|-+$/g,"");if(!t)throw new u.CliError("INVALID_SESSION_ARTIFACT_NAME",`Invalid session artifact name: ${e}`);return t}function $(e){const t=e.trim().replace(/[^A-Za-z0-9._-]/g,"-").replace(/^-+|-+$/g,"");if(!t)throw new u.CliError("INVALID_SESSION_ID",`Invalid session id: ${e}`);return t}function Jt(){return`${Le}${Math.random().toString(16).slice(2,8)}`}function ee(e){return(e.startsWith(".")?e:`.${e}`).replace(/[^A-Za-z0-9.]/g,"")||".txt"}function j(e){return typeof e=="number"&&Number.isFinite(e)?e:0}function te(e,t){return e===1?t:`${t}s`}function h(e,t){const n=c.relative(e,t);return n&&!n.startsWith("..")?n.replace(/\\/g,"/"):t}
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSessionHandle = isSessionHandle;
+exports.runWithSessionOverride = runWithSessionOverride;
+exports.runSessionWorkspaceCommand = runSessionWorkspaceCommand;
+exports.resolveSessionFileArgument = resolveSessionFileArgument;
+exports.saveSessionOutputJson = saveSessionOutputJson;
+exports.saveSessionOutputText = saveSessionOutputText;
+exports.saveSessionResultJson = saveSessionResultJson;
+exports.saveSessionResultViewJson = saveSessionResultViewJson;
+exports.readSessionResultViewJson = readSessionResultViewJson;
+exports.readSessionResultJson = readSessionResultJson;
+exports.captureSessionInputJson = captureSessionInputJson;
+exports.captureSessionInput = captureSessionInput;
+exports.sessionWorkspaceExists = sessionWorkspaceExists;
+exports.useSessionGuidance = useSessionGuidance;
+exports.readSessionBooleanPref = readSessionBooleanPref;
+exports.readSessionNumberPref = readSessionNumberPref;
+exports.readSessionStringPref = readSessionStringPref;
+exports.readEffectiveSessionPathAliases = readEffectiveSessionPathAliases;
+exports.readSessionPathAliasOverrides = readSessionPathAliasOverrides;
+exports.tryResolveCurrentSessionId = tryResolveCurrentSessionId;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_async_hooks_1 = require("node:async_hooks");
+const env_vars_1 = require("../config/env-vars");
+const workspace_root_1 = require("../config/workspace-root");
+const path_aliases_1 = require("../config/path-aliases");
+const agent_text_1 = require("../shared/agent-text");
+const errors_1 = require("../shared/errors");
+const DEFAULT_SESSION_ROOT = path.join(".tmp", "aib");
+const SESSION_DIR_CONFIG_KEY = "sessionDir";
+const SESSION_REGISTRY_FILE_NAME = "session.json";
+const ACTIVE_SESSION_FILE_NAME = "active.json";
+const HANDLE_PREFIX = "aib:";
+const SESSION_ID_PREFIX = "s_";
+const DEFAULT_AUTO_SESSION_ID = "_default";
+const LAST_INPUT_NAME = "last";
+const LAST_INPUT_FILE_NAME = "_last.json";
+const sessionOverrideStorage = new node_async_hooks_1.AsyncLocalStorage();
+const OUTPUT_KINDS = [
+    "graph",
+    "inspect",
+    "code",
+    "slice",
+    "members",
+    "exports",
+    "deps",
+    "usages",
+    "duplicates",
+    "mutate",
+    "execution",
+    "imports"
+];
+const INPUT_KINDS = [
+    "inspect",
+    "graph",
+    "mutate",
+    "imports",
+    "generic"
+];
+const SESSION_PREF_DEFS = {
+    "guidance.nextLimit": { type: "number", default: 2, min: 0, max: 100, hidden: true },
+    "diagnostics.hintLimit": { type: "number", default: 2, min: 0, max: 100, hidden: true },
+    "inspect.code.show": { type: "boolean", default: true, hidden: true },
+    "inspect.code.maxNonEmptyLines": { type: "number", default: 120, min: 1, max: 10000 },
+    "inspect.code.meta": { type: "boolean", default: true, hidden: true },
+    "inspect.members.maxItems": { type: "number", default: 20, min: 1, max: 1000 },
+    "inspect.members.all": { type: "boolean", default: false, hidden: true },
+    "inspect.exports.ranges": { type: "boolean", default: false, hidden: true },
+    "inspect.exports.resolveStar": { type: "boolean", default: false, hidden: true },
+    "inspect.graph.hubs": { type: "boolean", default: true },
+    "inspect.graph.entrypoints": { type: "boolean", default: true },
+    "inspect.graph.leaves": { type: "boolean", default: true },
+    "inspect.graph.edges": { type: "boolean", default: true },
+    "inspect.graph.symbols": { type: "boolean", default: false, hidden: true },
+    "inspect.graph.symbolUsage": { type: "boolean", default: false },
+    "inspect.usages.detail": { type: "string", default: "locations", values: ["summary", "locations", "code"], hidden: true },
+    "inspect.usages.maxLocations": { type: "number", default: 12, min: 1, max: 10000 },
+    "inspect.usages.maxCodeBlocks": { type: "number", default: 8, min: 1, max: 10000 },
+    "inspect.usages.excludeTarget": { type: "boolean", default: false, hidden: true }
+};
+function isSessionHandle(value) {
+    return value.startsWith(HANDLE_PREFIX);
+}
+function runWithSessionOverride(sessionId, callback) {
+    if (!sessionId) {
+        return callback();
+    }
+    return sessionOverrideStorage.run(sessionId, callback);
+}
+function runSessionWorkspaceCommand(cwd, restArgs, stdinPayload) {
+    const command = restArgs[0] ?? "status";
+    const resolvedWorkspace = (0, workspace_root_1.resolveWorkspaceRoot)(cwd);
+    if (!resolvedWorkspace) {
+        if (command === "status") {
+            return (0, agent_text_1.attachAgentText)({
+                initialized: false,
+                active: null,
+                source: "none",
+                available: [],
+                next: "Run aib help first-setup"
+            }, [
+                "session not ready",
+                "",
+                "No aib.json was found.",
+                "",
+                "If you are a user:",
+                "ask your agent to set up AIB for this repo:",
+                "aib help first-setup",
+                "",
+                "If you are an agent:",
+                "run:",
+                "aib help first-setup",
+                "",
+                "Then follow the setup from the intended repository root."
+            ].join("\n"));
+        }
+        (0, workspace_root_1.resolveRequiredWorkspaceRoot)(cwd);
+    }
+    const workspaceRoot = resolvedWorkspace?.root ?? cwd;
+    cleanupExpiredSessions(workspaceRoot);
+    if (command === "init") {
+        return initSessionWorkspace(workspaceRoot, restArgs.slice(1));
+    }
+    if (command === "status") {
+        return sessionWorkspaceStatus(workspaceRoot);
+    }
+    if (command === "list") {
+        return sessionWorkspaceList(workspaceRoot);
+    }
+    if (command === "use") {
+        return sessionWorkspaceUse(workspaceRoot, restArgs.slice(1));
+    }
+    if (command === "where") {
+        return sessionWorkspaceWhere(workspaceRoot, restArgs.slice(1));
+    }
+    if (command === "read") {
+        return sessionWorkspaceRead(workspaceRoot, restArgs.slice(1), stdinPayload);
+    }
+    if (command === "write") {
+        return sessionWorkspaceWrite(workspaceRoot, restArgs.slice(1), stdinPayload);
+    }
+    if (command === "prefs") {
+        return sessionWorkspacePrefs(workspaceRoot, restArgs.slice(1), stdinPayload);
+    }
+    if (command === "aliases") {
+        return sessionWorkspaceAliases(workspaceRoot, restArgs.slice(1), stdinPayload);
+    }
+    if (command === "clear") {
+        return clearSessionWorkspace(workspaceRoot);
+    }
+    throw new errors_1.CliError("UNKNOWN_SESSION_WORKSPACE_COMMAND", `Unknown session workspace command: ${command}`);
+}
+function sessionWorkspaceAliases(cwd, args, stdinPayload) {
+    const command = args[0] ?? "get";
+    if (command === "get") {
+        const workspace = readRequiredWorkspace(cwd);
+        const config = (0, path_aliases_1.readConfigPathAliases)(cwd);
+        const session = (0, path_aliases_1.normalizePathAliasMap)(workspace.pathAliases ?? {}, "session path aliases");
+        const response = {
+            aliases: (0, path_aliases_1.effectivePathAliases)(cwd, session),
+            config,
+            session
+        };
+        return (0, agent_text_1.attachAgentText)(response, formatSessionAliasesAgentText(response));
+    }
+    if (command === "set") {
+        const workspace = readRequiredWorkspace(cwd);
+        const updates = args.includes("--stdin")
+            ? readAliasesStdinPayload(stdinPayload)
+            : readAliasesPairArgs(args.slice(1));
+        const aliases = (0, path_aliases_1.normalizePathAliasMap)(workspace.pathAliases ?? {}, "session path aliases");
+        const updated = {};
+        for (const [name, target] of Object.entries(updates)) {
+            const alias = (0, path_aliases_1.normalizePathAliasName)(name, "session path aliases");
+            if (typeof target !== "string" || target.trim() === "") {
+                throw new errors_1.CliError("INVALID_PATH_ALIAS_TARGET", `session path alias ${name} must be a non-empty path string.`);
+            }
+            aliases[alias] = target.trim().replace(/\\/g, "/");
+            updated[alias] = aliases[alias];
+        }
+        workspace.pathAliases = aliases;
+        writeWorkspace(cwd, workspace);
+        const response = {
+            updated,
+            aliases: (0, path_aliases_1.effectivePathAliases)(cwd, aliases)
+        };
+        return (0, agent_text_1.attachAgentText)(response, formatSessionAliasesAgentText(response));
+    }
+    if (command === "clear") {
+        const workspace = readRequiredWorkspace(cwd);
+        const keys = args.slice(1).filter((item) => !item.startsWith("--"));
+        const aliases = (0, path_aliases_1.normalizePathAliasMap)(workspace.pathAliases ?? {}, "session path aliases");
+        const cleared = [];
+        if (keys.length === 0) {
+            cleared.push(...Object.keys(aliases).sort());
+            delete workspace.pathAliases;
+        }
+        else {
+            for (const key of keys) {
+                const alias = (0, path_aliases_1.normalizePathAliasName)(key, "session path aliases");
+                if (Object.prototype.hasOwnProperty.call(aliases, alias)) {
+                    cleared.push(alias);
+                    delete aliases[alias];
+                }
+            }
+            if (Object.keys(aliases).length > 0) {
+                workspace.pathAliases = aliases;
+            }
+            else {
+                delete workspace.pathAliases;
+            }
+        }
+        writeWorkspace(cwd, workspace);
+        const response = {
+            cleared,
+            aliases: (0, path_aliases_1.effectivePathAliases)(cwd, workspace.pathAliases ?? {})
+        };
+        return (0, agent_text_1.attachAgentText)(response, formatSessionAliasesAgentText(response));
+    }
+    throw new errors_1.CliError("UNKNOWN_SESSION_ALIASES_COMMAND", `Unknown session aliases command: ${command}`, {
+        expected: "aib session aliases get | set | clear"
+    });
+}
+function readAliasesStdinPayload(stdinPayload) {
+    if (!isObject(stdinPayload)) {
+        throw new errors_1.CliError("INVALID_SESSION_ALIASES_STDIN", "session aliases set --stdin expects a JSON object.");
+    }
+    const rawAliases = isObject(stdinPayload.aliases) ? stdinPayload.aliases : stdinPayload;
+    const aliases = {};
+    for (const [key, value] of Object.entries(rawAliases)) {
+        if (typeof value === "string") {
+            aliases[key] = value;
+        }
+    }
+    return aliases;
+}
+function readAliasesPairArgs(args) {
+    if (args.length === 0 || args.length % 2 !== 0) {
+        throw new errors_1.CliError("SESSION_ALIASES_SET_USAGE", "Usage: aib session aliases set <name> <path> [<name> <path>...] or session aliases set --stdin");
+    }
+    const aliases = {};
+    for (let index = 0; index < args.length; index += 2) {
+        aliases[args[index] ?? ""] = args[index + 1] ?? "";
+    }
+    return aliases;
+}
+function formatSessionAliasesAgentText(response) {
+    if (isObject(response.updated)) {
+        return formatAliasesMap("aliases.updated", response.updated);
+    }
+    if (Array.isArray(response.cleared)) {
+        const cleared = response.cleared.filter((item) => typeof item === "string");
+        return cleared.length > 0 ? ["aliases.cleared", ...cleared].join("\n") : "aliases.cleared none";
+    }
+    if (isObject(response.aliases)) {
+        const lines = formatAliasesMap("aliases", response.aliases).split("\n");
+        if (lines.length === 1) {
+            lines.push("none");
+        }
+        return lines.join("\n");
+    }
+    return null;
+}
+function formatAliasesMap(title, aliases) {
+    const lines = [title];
+    for (const [key, value] of Object.entries(aliases).sort(([left], [right]) => left.localeCompare(right))) {
+        lines.push(`@${key}/=${String(value)}`);
+    }
+    return lines.join("\n");
+}
+function sessionWorkspaceWrite(cwd, args, stdinPayload) {
+    const kind = args[0] ?? "";
+    const name = args[1] ?? "";
+    if (!kind || !name) {
+        throw new errors_1.CliError("SESSION_WRITE_USAGE", "Usage: aib session write <kind> <name> --stdin");
+    }
+    if (stdinPayload === undefined) {
+        throw new errors_1.CliError("STDIN_REQUIRED", "session write expects JSON on stdin and the --stdin flag.");
+    }
+    const workspace = readRequiredWorkspace(cwd);
+    const file = sessionInputPath(workspace, kind, name);
+    writeJsonFile(file, stdinPayload);
+    const artifact = registerArtifact(workspace, "inputs", kind, name, file);
+    registerLastInputArtifact(workspace, kind, stdinPayload);
+    writeWorkspace(cwd, workspace);
+    const result = {
+        written: artifact.handle,
+        file: toDisplayPath(cwd, file)
+    };
+    const next = useSessionGuidance(cwd, "session.write.from", `Use with --from ${artifact.handle}`);
+    if (next) {
+        result.next = next;
+    }
+    return result;
+}
+function sessionWorkspacePrefs(cwd, args, stdinPayload) {
+    const command = args[0] ?? "get";
+    if (command === "get") {
+        const workspace = readRequiredWorkspace(cwd);
+        const full = args.includes("--all");
+        const prefix = args.slice(1).find((item) => !item.startsWith("--"));
+        const prefs = full ? effectivePrefs(workspace) : visiblePrefs(workspace.prefs ?? {});
+        const selected = selectPrefs(prefs, prefix);
+        const response = full
+            ? {
+                prefs: selected
+            }
+            : {
+                overrides: selected,
+                defaults: "omitted; use session prefs get --all"
+            };
+        return (0, agent_text_1.attachAgentText)(response, formatSessionPrefsAgentText(response));
+    }
+    if (command === "set") {
+        const workspace = readRequiredWorkspace(cwd);
+        const updates = args.includes("--stdin")
+            ? readPrefsStdinPayload(stdinPayload)
+            : readPrefsPairArgs(args.slice(1));
+        const prefs = workspace.prefs ?? {};
+        const updated = {};
+        for (const [key, value] of Object.entries(updates)) {
+            const normalizedKey = normalizeSessionPrefKey(key);
+            const parsed = parseSessionPrefValue(normalizedKey, value);
+            prefs[normalizedKey] = parsed;
+            updated[normalizedKey] = parsed;
+        }
+        workspace.prefs = prefs;
+        writeWorkspace(cwd, workspace);
+        const response = { updated };
+        return (0, agent_text_1.attachAgentText)(response, formatSessionPrefsAgentText(response));
+    }
+    if (command === "clear") {
+        const workspace = readRequiredWorkspace(cwd);
+        const keys = args.slice(1).filter((item) => !item.startsWith("--"));
+        const currentPrefs = workspace.prefs ?? {};
+        const cleared = [];
+        if (keys.length === 0) {
+            cleared.push(...Object.keys(currentPrefs).sort());
+            delete workspace.prefs;
+        }
+        else {
+            for (const key of keys) {
+                const normalizedKey = normalizeSessionPrefKey(key);
+                if (Object.prototype.hasOwnProperty.call(currentPrefs, normalizedKey)) {
+                    cleared.push(normalizedKey);
+                    delete currentPrefs[normalizedKey];
+                }
+            }
+            if (Object.keys(currentPrefs).length > 0) {
+                workspace.prefs = currentPrefs;
+            }
+            else {
+                delete workspace.prefs;
+            }
+        }
+        writeWorkspace(cwd, workspace);
+        const response = {
+            cleared
+        };
+        return (0, agent_text_1.attachAgentText)(response, formatSessionPrefsAgentText(response));
+    }
+    throw new errors_1.CliError("UNKNOWN_SESSION_PREFS_COMMAND", `Unknown session prefs command: ${command}`, {
+        expected: "aib session prefs get | set | clear"
+    });
+}
+function selectPrefs(prefs, prefix) {
+    if (!prefix) {
+        return prefs;
+    }
+    const selected = {};
+    for (const [key, value] of Object.entries(prefs)) {
+        if (key === prefix || key.startsWith(`${prefix}.`)) {
+            selected[key] = value;
+        }
+    }
+    return selected;
+}
+function formatSessionPrefsAgentText(response) {
+    if (isObject(response.updated)) {
+        return formatPrefsMap("prefs.updated", response.updated);
+    }
+    if (Array.isArray(response.cleared)) {
+        const cleared = response.cleared.filter((item) => typeof item === "string");
+        return cleared.length > 0 ? ["prefs.cleared", ...cleared].join("\n") : "prefs.cleared none";
+    }
+    if (isObject(response.overrides)) {
+        const lines = formatPrefsMap("prefs", response.overrides).split("\n");
+        if (lines.length === 1) {
+            lines.push("no overrides");
+        }
+        if (typeof response.defaults === "string") {
+            lines.push(response.defaults);
+        }
+        return lines.join("\n");
+    }
+    if (isObject(response.prefs)) {
+        return formatPrefsMap("prefs", response.prefs);
+    }
+    return null;
+}
+function formatPrefsMap(title, prefs) {
+    const lines = [title];
+    for (const [key, value] of Object.entries(prefs).sort(([left], [right]) => left.localeCompare(right))) {
+        lines.push(`${key}=${String(value)}`);
+    }
+    return lines.join("\n");
+}
+function readPrefsStdinPayload(stdinPayload) {
+    if (!isObject(stdinPayload)) {
+        throw new errors_1.CliError("INVALID_SESSION_PREFS_STDIN", "session prefs set --stdin expects a JSON object.");
+    }
+    const rawPrefs = isObject(stdinPayload.prefs) ? stdinPayload.prefs : stdinPayload;
+    const prefs = {};
+    for (const [key, value] of Object.entries(rawPrefs)) {
+        prefs[key] = value;
+    }
+    return prefs;
+}
+function readPrefsPairArgs(args) {
+    if (args.length === 0 || args.length % 2 !== 0) {
+        throw new errors_1.CliError("SESSION_PREFS_SET_USAGE", "Usage: aib session prefs set <key> <value> [<key> <value>...] or session prefs set --stdin");
+    }
+    const prefs = {};
+    for (let index = 0; index < args.length; index += 2) {
+        const key = args[index] ?? "";
+        const value = args[index + 1] ?? "";
+        prefs[key] = value;
+    }
+    return prefs;
+}
+function normalizeSessionPrefKey(key) {
+    if (Object.prototype.hasOwnProperty.call(SESSION_PREF_DEFS, key)) {
+        return key;
+    }
+    throw new errors_1.CliError("UNKNOWN_SESSION_PREF", `Unknown session preference: ${key}`, {
+        available: Object.keys(SESSION_PREF_DEFS)
+    });
+}
+function parseSessionPrefValue(key, value) {
+    const definition = SESSION_PREF_DEFS[key];
+    if (definition.type === "boolean") {
+        if (typeof value === "boolean") {
+            return value;
+        }
+        if (typeof value === "string") {
+            const normalized = value.trim().toLowerCase();
+            if (normalized === "true") {
+                return true;
+            }
+            if (normalized === "false") {
+                return false;
+            }
+        }
+        throw new errors_1.CliError("INVALID_SESSION_PREF_VALUE", `${key} expects true or false.`);
+    }
+    if (definition.type === "string") {
+        if (typeof value !== "string") {
+            throw new errors_1.CliError("INVALID_SESSION_PREF_VALUE", `${key} expects one of: ${definition.values.join(", ")}.`);
+        }
+        const normalized = value.trim();
+        if (!definition.values.includes(normalized)) {
+            throw new errors_1.CliError("INVALID_SESSION_PREF_VALUE", `${key} expects one of: ${definition.values.join(", ")}.`);
+        }
+        return normalized;
+    }
+    const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+    if (!Number.isInteger(parsed) || parsed < definition.min || parsed > definition.max) {
+        throw new errors_1.CliError("INVALID_SESSION_PREF_VALUE", `${key} expects an integer from ${definition.min} to ${definition.max}.`);
+    }
+    return parsed;
+}
+function effectivePrefs(workspace) {
+    const prefs = {};
+    for (const key of Object.keys(SESSION_PREF_DEFS)) {
+        const definition = SESSION_PREF_DEFS[key];
+        if ("hidden" in definition && definition.hidden) {
+            continue;
+        }
+        if (definition.type === "boolean") {
+            prefs[key] = readWorkspaceBooleanPref(workspace, key, definition.default);
+        }
+        else if (definition.type === "number") {
+            prefs[key] = readWorkspaceNumberPref(workspace, key, definition.default);
+        }
+        else {
+            prefs[key] = readWorkspaceStringPref(workspace, key, definition.default);
+        }
+    }
+    return prefs;
+}
+function visiblePrefs(prefs) {
+    const visible = {};
+    for (const [key, value] of Object.entries(prefs)) {
+        if (!isHiddenSessionPrefKey(key)) {
+            visible[key] = value;
+        }
+    }
+    return visible;
+}
+function isHiddenSessionPrefKey(key) {
+    if (!Object.prototype.hasOwnProperty.call(SESSION_PREF_DEFS, key)) {
+        return false;
+    }
+    const definition = SESSION_PREF_DEFS[key];
+    return "hidden" in definition && definition.hidden === true;
+}
+function resolveSessionFileArgument(cwd, value) {
+    if (!isSessionHandle(value)) {
+        return value;
+    }
+    const workspace = readRequiredWorkspace(cwd);
+    const parsed = parseSessionHandle(value);
+    const bucketGroup = parsed.scope === "input" ? workspace.inputs : workspace.outputs;
+    const kind = parsed.scope === "input" ? parsed.kind : parsed.scope;
+    const bucket = bucketGroup[kind];
+    const name = parsed.name === "last" ? bucket?.last : parsed.name;
+    const artifact = name ? bucket?.items[name] : undefined;
+    if (!artifact) {
+        throw new errors_1.CliError("SESSION_HANDLE_NOT_FOUND", `Session handle not found: ${value}`, {
+            handle: value,
+            sessionDir: toDisplayPath(cwd, workspace.rootDir)
+        });
+    }
+    return artifact.file;
+}
+function saveSessionOutputJson(cwd, kind, name, value) {
+    const workspace = readRequiredWorkspaceForSave(cwd);
+    const file = sessionOutputPath(workspace, kind, name, ".json");
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+    const artifact = registerArtifact(workspace, "outputs", kind, name, file);
+    writeWorkspace(cwd, workspace);
+    return {
+        saved: artifact.handle,
+        last: `aib:${kind}:last`,
+        file: toDisplayPath(cwd, file)
+    };
+}
+function saveSessionOutputText(cwd, kind, name, value, extension = ".txt") {
+    const workspace = readRequiredWorkspaceForSave(cwd);
+    const file = sessionOutputPath(workspace, kind, name, extension);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, value);
+    const artifact = registerArtifact(workspace, "outputs", kind, name, file);
+    writeWorkspace(cwd, workspace);
+    return {
+        saved: artifact.handle,
+        last: `aib:${kind}:last`,
+        file: toDisplayPath(cwd, file)
+    };
+}
+function saveSessionResultJson(cwd, kind, id, value) {
+    const workspace = readWorkspaceForSave(cwd);
+    if (!workspace) {
+        return null;
+    }
+    const normalizedKind = sanitizePathSegment(kind);
+    const normalizedId = sanitizePathSegment(id);
+    const file = path.join(workspace.rootDir, "outputs", "result", normalizedKind, `${normalizedId}.json`);
+    writeJsonFile(file, value);
+    return {
+        saved: `aib:result:${normalizedKind}:${normalizedId}`,
+        file: toDisplayPath(cwd, file)
+    };
+}
+function saveSessionResultViewJson(cwd, id, value) {
+    const workspace = readWorkspaceForSave(cwd);
+    if (!workspace) {
+        return null;
+    }
+    const normalizedId = sanitizePathSegment(id);
+    const file = path.join(workspace.rootDir, "outputs", "result", `${normalizedId}.json`);
+    writeJsonFile(file, value);
+    return {
+        saved: `aib:${normalizedId}`,
+        file: toDisplayPath(cwd, file)
+    };
+}
+function readSessionResultViewJson(cwd, id) {
+    const workspace = readRequiredWorkspace(cwd);
+    const normalizedId = sanitizePathSegment(id);
+    const file = path.join(workspace.rootDir, "outputs", "result", `${normalizedId}.json`);
+    if (!fs.existsSync(file)) {
+        throw new errors_1.CliError("SESSION_RESULT_NOT_FOUND", `Result handle not found: aib:${normalizedId}`, {
+            handle: `aib:${normalizedId}`,
+            sessionDir: toDisplayPath(cwd, workspace.rootDir)
+        });
+    }
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new errors_1.CliError("INVALID_SESSION_RESULT", `Result artifact is not a JSON object: aib:${normalizedId}`);
+    }
+    return parsed;
+}
+function readSessionResultJson(cwd, kind, id) {
+    const workspace = readRequiredWorkspace(cwd);
+    const normalizedKind = sanitizePathSegment(kind);
+    const normalizedId = sanitizePathSegment(id);
+    const file = path.join(workspace.rootDir, "outputs", "result", normalizedKind, `${normalizedId}.json`);
+    if (!fs.existsSync(file)) {
+        throw new errors_1.CliError("SESSION_RESULT_NOT_FOUND", `Result handle not found: aib:result:${normalizedKind}:${normalizedId}`, {
+            handle: `aib:result:${normalizedKind}:${normalizedId}`,
+            sessionDir: toDisplayPath(cwd, workspace.rootDir)
+        });
+    }
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new errors_1.CliError("INVALID_SESSION_RESULT", `Result artifact is not a JSON object: aib:result:${normalizedKind}:${normalizedId}`);
+    }
+    return parsed;
+}
+function captureSessionInputJson(cwd, kind, name, value) {
+    return captureSessionInput(cwd, kind, name, value, { format: "json", text: JSON.stringify(value, null, 2) });
+}
+function captureSessionInput(cwd, kind, name, value, source) {
+    const workspace = readWorkspaceForSave(cwd);
+    if (!workspace) {
+        return null;
+    }
+    const inputSource = source ?? { format: "json", text: JSON.stringify(value, null, 2) };
+    const file = inputSource.format === "dsl"
+        ? sessionInputPath(workspace, kind, name, ".dsl")
+        : sessionInputPath(workspace, kind, name, ".json");
+    if (inputSource.format === "dsl") {
+        writeTextFile(file, inputSource.text);
+        writeJsonFile(sessionCompiledInputPath(workspace, kind, name), value);
+    }
+    else {
+        writeJsonFile(file, value);
+    }
+    const artifact = registerArtifact(workspace, "inputs", kind, name, file);
+    registerLastInputArtifact(workspace, kind, value, inputSource);
+    writeWorkspace(cwd, workspace);
+    return {
+        handle: artifact.handle,
+        file: toDisplayPath(cwd, file)
+    };
+}
+function sessionWorkspaceExists(cwd) {
+    return fs.existsSync(workspaceMarkerPath(cwd));
+}
+function useSessionGuidance(cwd, key, message, limit = -1) {
+    const workspace = readWorkspace(cwd);
+    if (!workspace) {
+        return message;
+    }
+    const configuredLimit = limit >= 0 ? limit : readWorkspaceNumberPref(workspace, "guidance.nextLimit", 2);
+    const guidance = workspace.guidance ?? {};
+    const state = guidance[key] ?? { shown: 0, limit: configuredLimit };
+    state.limit = configuredLimit;
+    if (state.shown >= state.limit) {
+        guidance[key] = state;
+        workspace.guidance = guidance;
+        writeWorkspace(cwd, workspace);
+        return undefined;
+    }
+    state.shown += 1;
+    guidance[key] = state;
+    workspace.guidance = guidance;
+    writeWorkspace(cwd, workspace);
+    return message;
+}
+function readSessionBooleanPref(cwd, key, fallback) {
+    const workspace = readWorkspace(cwd);
+    const definition = SESSION_PREF_DEFS[key];
+    const defaultValue = typeof fallback === "boolean" ? fallback : definition.type === "boolean" ? definition.default : false;
+    return workspace ? readWorkspaceBooleanPref(workspace, key, defaultValue) : defaultValue;
+}
+function readSessionNumberPref(cwd, key, fallback) {
+    const workspace = readWorkspace(cwd);
+    const definition = SESSION_PREF_DEFS[key];
+    const defaultValue = typeof fallback === "number" ? fallback : definition.type === "number" ? definition.default : 0;
+    const configValue = (0, workspace_root_1.readWorkspaceNumberConfig)(cwd, key, defaultValue);
+    return workspace ? readWorkspaceNumberPref(workspace, key, configValue) : configValue;
+}
+function readSessionStringPref(cwd, key, fallback) {
+    const workspace = readWorkspace(cwd);
+    const definition = SESSION_PREF_DEFS[key];
+    const defaultValue = typeof fallback === "string" ? fallback : definition.type === "string" ? definition.default : "";
+    return workspace ? readWorkspaceStringPref(workspace, key, defaultValue) : defaultValue;
+}
+function readEffectiveSessionPathAliases(cwd) {
+    try {
+        const workspace = readWorkspace(cwd);
+        return (0, path_aliases_1.effectivePathAliases)(cwd, workspace?.pathAliases ?? {});
+    }
+    catch (error) {
+        if (error instanceof errors_1.CliError && error.code === "MULTIPLE_AIB_SESSIONS") {
+            return (0, path_aliases_1.effectivePathAliases)(cwd, {});
+        }
+        throw error;
+    }
+}
+function readSessionPathAliasOverrides(cwd) {
+    try {
+        const workspace = readWorkspace(cwd);
+        return (0, path_aliases_1.normalizePathAliasMap)(workspace?.pathAliases ?? {}, "session path aliases");
+    }
+    catch (error) {
+        if (error instanceof errors_1.CliError && error.code === "MULTIPLE_AIB_SESSIONS") {
+            return {};
+        }
+        throw error;
+    }
+}
+function readWorkspaceBooleanPref(workspace, key, fallback) {
+    const value = workspace.prefs?.[key];
+    return typeof value === "boolean" ? value : fallback;
+}
+function readWorkspaceNumberPref(workspace, key, fallback) {
+    const value = workspace.prefs?.[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function readWorkspaceStringPref(workspace, key, fallback) {
+    const value = workspace.prefs?.[key];
+    return typeof value === "string" ? value : fallback;
+}
+function initSessionWorkspace(cwd, args) {
+    const requestedDir = readFlagValue(args, "--dir");
+    const explicitName = readFlagValue(args, "--name");
+    const sessionId = sanitizeSessionId(explicitName ?? currentSessionId() ?? createSessionId());
+    if (explicitName && sessionId === DEFAULT_AUTO_SESSION_ID) {
+        throw new errors_1.CliError("SESSION_ID_RESERVED", `${DEFAULT_AUTO_SESSION_ID} is reserved for AIB's automatic default session.`, {
+            session: sessionId,
+            next: "Use aib session init --name <name>"
+        });
+    }
+    const sessionRoot = resolveSessionRoot(cwd, requestedDir, true);
+    const rootDir = path.join(sessionRoot.rootDir, sessionId);
+    const now = new Date().toISOString();
+    const existing = readWorkspaceById(cwd, sessionId);
+    const workspace = existing ?? {
+        version: 1,
+        sessionId,
+        cwd: path.resolve(cwd),
+        rootDir,
+        createdAt: now,
+        updatedAt: now,
+        outputs: {},
+        inputs: {},
+        guidance: {}
+    };
+    workspace.sessionId = sessionId;
+    workspace.rootDir = rootDir;
+    workspace.updatedAt = now;
+    ensureWorkspaceDirs(workspace);
+    writeWorkspace(cwd, workspace);
+    upsertRegistrySession(cwd, workspace, true);
+    const registry = readRegistry(cwd);
+    const sessionCount = registry ? Object.keys(registry.sessions).length : 1;
+    const result = {
+        session: sessionId,
+        dir: toDisplayPath(cwd, workspace.rootDir),
+        sessionDir: toDisplayPath(cwd, sessionRoot.rootDir),
+        sessionDirSource: sessionRoot.source,
+        sessionCount,
+        bind: `${env_vars_1.CLI_ENV.session}=${sessionId}`,
+        next: sessionCount === 1
+            ? "Run AIB commands without -s for now. AIB will tell you if multiple sessions exist."
+            : `Use aib -s ${sessionId} <command> or set ${env_vars_1.CLI_ENV.session}=${sessionId}.`
+    };
+    if (sessionRoot.ignoredRequestedDir) {
+        result.note = `${SESSION_DIR_CONFIG_KEY} from aib.json is in effect; --dir was ignored.`;
+        result.requestedDir = sessionRoot.ignoredRequestedDir;
+    }
+    return (0, agent_text_1.attachAgentText)(result, formatSessionInitAgentText(result));
+}
+function formatSessionInitAgentText(result) {
+    const sessionId = String(result.session ?? "");
+    const sessionCount = typeof result.sessionCount === "number" ? result.sessionCount : 1;
+    const lines = [`session ready: ${sessionId}`, ""];
+    if (typeof result.note === "string" && result.note) {
+        lines.push("aib.json sessionDir is in effect; --dir was ignored.");
+        lines.push("");
+    }
+    if (sessionCount === 1) {
+        lines.push("Only one AIB session exists in this repo.");
+        lines.push("You can run AIB commands without -s for now.");
+        lines.push("AIB will tell you if multiple sessions exist and you need to choose one.");
+    }
+    else {
+        lines.push("Multiple AIB sessions exist in this repo.");
+        lines.push("Use this session explicitly:");
+        lines.push(`aib -s ${sessionId} <command>`);
+        lines.push("");
+        lines.push("Or bind it in this shell:");
+        lines.push(`${env_vars_1.CLI_ENV.session}=${sessionId}`);
+    }
+    return lines.join("\n");
+}
+function sessionWorkspaceList(cwd) {
+    const registry = readRegistry(cwd);
+    const selected = resolveSelectedSessionForList(cwd);
+    return {
+        active: selected.sessionId ?? registry?.activeSessionId ?? null,
+        source: selected.source,
+        sessions: registry
+            ? Object.values(registry.sessions)
+                .sort((left, right) => left.sessionId.localeCompare(right.sessionId))
+                .map((session) => `${session.sessionId} -> ${toDisplayPath(cwd, session.rootDir)}`)
+            : []
+    };
+}
+function sessionWorkspaceUse(cwd, args) {
+    const rawSessionId = args[0] ?? "";
+    if (!rawSessionId) {
+        throw new errors_1.CliError("SESSION_USE_ID_REQUIRED", "Usage: aib session use <sessionId>");
+    }
+    const sessionId = sanitizeSessionId(rawSessionId);
+    const registry = readRegistry(cwd);
+    const entry = registry?.sessions[sessionId];
+    if (!entry) {
+        throw new errors_1.CliError("SESSION_NOT_FOUND", `Session not found: ${sessionId}`, {
+            available: registry ? Object.keys(registry.sessions).sort() : []
+        });
+    }
+    writeRegistry(cwd, {
+        ...(registry ?? createEmptyRegistry(cwd)),
+        activeSessionId: sessionId
+    });
+    return {
+        session: sessionId,
+        dir: toDisplayPath(cwd, entry.rootDir),
+        bind: `${env_vars_1.CLI_ENV.session}=${sessionId}`,
+        next: `Use aib -s ${sessionId} <command> or set ${env_vars_1.CLI_ENV.session}=${sessionId}.`
+    };
+}
+function sessionWorkspaceWhere(cwd, args) {
+    const handle = args[0] ?? "";
+    if (!handle) {
+        throw new errors_1.CliError("SESSION_WHERE_HANDLE_REQUIRED", "Usage: aib session where <handle>");
+    }
+    const file = resolveSessionFileArgument(cwd, handle);
+    const response = {
+        handle,
+        file: toDisplayPath(cwd, file)
+    };
+    return (0, agent_text_1.attachAgentText)(response, [
+        handle,
+        response.file
+    ].join("\n"));
+}
+function sessionWorkspaceRead(cwd, args, stdinPayload) {
+    if (args.includes("--stdin")) {
+        if (!isObject(stdinPayload)) {
+            throw new errors_1.CliError("INVALID_SESSION_READ_STDIN", "session read --stdin expects a JSON object payload.");
+        }
+        const readRequests = parseSessionReadBatchPayload(stdinPayload);
+        if (readRequests.length === 1) {
+            const result = readSessionArtifact(cwd, readRequests[0]);
+            return (0, agent_text_1.attachAgentText)(result, formatSessionReadAgentText(result));
+        }
+        const result = {
+            reads: readRequests.map((request) => readSessionArtifactRow(cwd, request))
+        };
+        return (0, agent_text_1.attachAgentText)(result, formatSessionReadAgentText(result));
+    }
+    const handle = args[0] ?? "";
+    if (!handle) {
+        throw new errors_1.CliError("SESSION_READ_HANDLE_REQUIRED", "Usage: aib session read <handle> [--head <n> | --offset <n> --limit <n>]");
+    }
+    const result = readSessionArtifact(cwd, {
+        handle,
+        ...readSessionReadOptions(args.slice(1))
+    });
+    return (0, agent_text_1.attachAgentText)(result, formatSessionReadAgentText(result));
+}
+function parseSessionReadBatchPayload(payload) {
+    if (Array.isArray(payload.reads)) {
+        return payload.reads.map((row, index) => {
+            if (typeof row === "string") {
+                if (!isSessionHandle(row)) {
+                    throw new errors_1.CliError("INVALID_SESSION_READ_ROW", `session read row at index ${index} must be an aib: handle string or an object.`);
+                }
+                return { handle: row };
+            }
+            if (!isObject(row)) {
+                throw new errors_1.CliError("INVALID_SESSION_READ_ROW", `session read row at index ${index} must be an aib: handle string or an object.`);
+            }
+            return parseSessionReadRow(row, index);
+        });
+    }
+    if (typeof payload.handle === "string" || typeof payload.read === "string") {
+        return [parseSessionReadRow(payload, 0)];
+    }
+    throw new errors_1.CliError("INVALID_SESSION_READ_STDIN", "Expected { reads: [{ handle }] } or { handle }.");
+}
+function parseSessionReadRow(row, index) {
+    const handle = readString(row.handle) ?? readString(row.read);
+    if (!handle) {
+        throw new errors_1.CliError("SESSION_READ_HANDLE_REQUIRED", `session read row at index ${index} requires handle.`);
+    }
+    return {
+        handle,
+        ...(row.rawInput === true ? { rawInput: true } : {}),
+        ...readSessionReadObjectOptions(row, index)
+    };
+}
+function readSessionArtifactRow(cwd, request) {
+    try {
+        return readSessionArtifact(cwd, request);
+    }
+    catch (error) {
+        if (error instanceof errors_1.CliError) {
+            const details = isObject(error.details) ? error.details : {};
+            return {
+                read: request.handle,
+                error: error.code,
+                ...(typeof details.next === "string" ? { next: details.next } : {})
+            };
+        }
+        return {
+            read: request.handle,
+            error: "UNEXPECTED_ERROR"
+        };
+    }
+}
+function readSessionArtifact(cwd, request) {
+    validateSessionReadOptions(request);
+    const parsed = parseSessionHandle(request.handle);
+    const file = resolveSessionFileArgument(cwd, request.handle);
+    if (parsed.scope === "input" && !request.rawInput) {
+        const rerun = buildInputRerunCommand(parsed.kind, request.handle);
+        return {
+            read: request.handle,
+            file: toDisplayPath(cwd, file),
+            next: rerun
+                ? `Edit file, then rerun: ${rerun}`
+                : "Edit file, then rerun the command with --from <handle>."
+        };
+    }
+    if (parsed.scope === "graph" || parsed.scope === "usages") {
+        const next = parsed.scope === "graph"
+            ? `aib inspect graph --from-file ${request.handle} --focus <file>`
+            : `aib inspect usages --from-file ${request.handle} --focus <name>`;
+        throw new errors_1.CliError("SESSION_ARTIFACT_NOT_READABLE", `${parsed.scope} artifacts are reusable indexes, not agent-readable context.`, {
+            handle: request.handle,
+            kind: parsed.scope,
+            next
+        });
+    }
+    if (parsed.scope === "duplicates") {
+        const content = fs.readFileSync(file, "utf8");
+        return {
+            read: request.handle,
+            content: readSavedDuplicatesContent(cwd, request.handle, file, content, request)
+        };
+    }
+    const content = fs.readFileSync(file, "utf8");
+    return {
+        read: request.handle,
+        content: readSessionArtifactContent(file, content, request)
+    };
+}
+function readSavedDuplicatesContent(cwd, handle, file, content, request) {
+    const text = formatSavedDuplicatesContent(cwd, handle, file, content);
+    return request.head !== undefined || request.offset !== undefined || request.limit !== undefined
+        ? applyReadWindow(text, request)
+        : text;
+}
+function formatSavedDuplicatesContent(cwd, handle, file, content) {
+    let payload;
+    try {
+        payload = JSON.parse(content);
+    }
+    catch {
+        return applySavedArtifactFallback(handle, file, content);
+    }
+    if (!isObject(payload)) {
+        return applySavedArtifactFallback(handle, file, content);
+    }
+    const lines = [];
+    const targets = Array.isArray(payload.targetPaths)
+        ? payload.targetPaths.filter((item) => typeof item === "string" && item !== "")
+        : [];
+    const targetLabel = targets.length === 1
+        ? toDisplayPath(cwd, targets[0])
+        : targets.length > 1 ? `${targets.length} scopes` : "";
+    lines.push(targetLabel ? `duplicates ${targetLabel}` : "duplicates");
+    const summary = typeof payload.summary === "string"
+        ? payload.summary
+        : `${numberOrZero(payload.itemCount)} ${plural(numberOrZero(payload.itemCount), "name")}`;
+    lines.push(summary);
+    const items = Array.isArray(payload.items) ? payload.items.filter(isObject) : [];
+    for (const item of items) {
+        const name = typeof item.name === "string" ? item.name : "";
+        const count = numberOrZero(item.declarationCount);
+        const variants = numberOrZero(item.variantCount);
+        const exactCopies = numberOrZero(item.exactCopyCount);
+        if (name) {
+            lines.push(`${name} x${count}, ${variants} ${plural(variants, "variant")}${exactCopies > 0 ? `, exact x${exactCopies}` : ""}`);
+        }
+    }
+    const hidden = numberOrZero(payload.hiddenItemCount);
+    if (hidden > 0) {
+        lines.push(`+ ${hidden} ${plural(hidden, "name")}`);
+    }
+    lines.push(`raw: aib session where ${handle}`);
+    return lines.join("\n");
+}
+function applySavedArtifactFallback(handle, file, content) {
+    return [
+        `saved artifact ${handle}`,
+        `${content.length} bytes`,
+        `raw: ${file}`
+    ].join("\n");
+}
+function readSessionArtifactContent(file, content, request) {
+    if (request.head !== undefined || request.offset !== undefined || request.limit !== undefined) {
+        return applyReadWindow(content, request);
+    }
+    if (path.extname(file).toLowerCase() !== ".json") {
+        return content;
+    }
+    try {
+        return JSON.parse(content);
+    }
+    catch {
+        return content;
+    }
+}
+function formatSessionReadAgentText(response) {
+    const rows = Array.isArray(response.reads) ? response.reads.filter(isObject) : [response];
+    if (rows.length === 0) {
+        return null;
+    }
+    const parts = [];
+    const includeHeaders = rows.length > 1;
+    for (const row of rows) {
+        const handle = typeof row.read === "string" ? row.read : "";
+        const content = row.content;
+        const formattedContent = formatSessionReadContent(content);
+        if (formattedContent !== null) {
+            if (includeHeaders && handle) {
+                parts.push(`// ${handle}`);
+            }
+            parts.push(formattedContent.trimEnd());
+            continue;
+        }
+        if (typeof row.file === "string") {
+            if (includeHeaders && handle) {
+                parts.push(`// ${handle}`);
+            }
+            else if (handle) {
+                parts.push(`input ${handle}`);
+            }
+            parts.push(`file: ${row.file}`);
+            if (typeof row.next === "string") {
+                parts.push(`next: ${row.next}`);
+            }
+            continue;
+        }
+        const error = typeof row.error === "string" ? row.error : "";
+        if (error) {
+            if (includeHeaders && handle) {
+                parts.push(`// ${handle}`);
+            }
+            parts.push(`error: ${error}`);
+            if (typeof row.next === "string") {
+                parts.push(`next: ${row.next}`);
+            }
+            continue;
+        }
+        return null;
+    }
+    return parts.join("\n");
+}
+function formatSessionReadContent(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (content === undefined) {
+        return null;
+    }
+    return JSON.stringify(content, null, 2);
+}
+function buildInputRerunCommand(kind, handle) {
+    if (kind === "inspect") {
+        return `aib inspect --from ${handle}`;
+    }
+    if (kind === "graph") {
+        return `aib inspect graph --from ${handle}`;
+    }
+    if (kind === "rename") {
+        return `aib mutate preview --from ${handle}`;
+    }
+    if (kind === "move") {
+        return `aib mutate preview --from ${handle}`;
+    }
+    if (kind === "refactor") {
+        return `aib mutate preview --from ${handle}`;
+    }
+    if (kind === "modulePlan") {
+        return `aib mutate preview --from ${handle}`;
+    }
+    if (kind === "imports") {
+        return `aib mutate preview --from ${handle}`;
+    }
+    return null;
+}
+function validateSessionReadOptions(options) {
+    if (options.head !== undefined && (options.offset !== undefined || options.limit !== undefined)) {
+        throw new errors_1.CliError("SESSION_READ_RANGE_CONFLICT", "Use either head or offset/limit, not both.");
+    }
+}
+function readSessionReadOptions(args) {
+    const row = {};
+    const head = readFlagValue(args, "--head");
+    const offset = readFlagValue(args, "--offset");
+    const limit = readFlagValue(args, "--limit");
+    if (head !== undefined) {
+        row.head = head;
+    }
+    if (offset !== undefined) {
+        row.offset = offset;
+    }
+    if (limit !== undefined) {
+        row.limit = limit;
+    }
+    return {
+        ...(args.includes("--raw-input") ? { rawInput: true } : {}),
+        ...readSessionReadObjectOptions(row, 0)
+    };
+}
+function readSessionReadObjectOptions(row, index) {
+    const head = readOptionalNonNegativeInteger(row.head, `session read row at index ${index} has invalid head.`);
+    const offset = readOptionalNonNegativeInteger(row.offset, `session read row at index ${index} has invalid offset.`);
+    const limit = readOptionalPositiveInteger(row.limit, `session read row at index ${index} has invalid limit.`);
+    return {
+        ...(head !== undefined ? { head } : {}),
+        ...(offset !== undefined ? { offset } : {}),
+        ...(limit !== undefined ? { limit } : {})
+    };
+}
+function applyReadWindow(content, options) {
+    if (options.head === undefined && options.offset === undefined && options.limit === undefined) {
+        return content;
+    }
+    const lines = content.split(/\r?\n/);
+    const start = options.head !== undefined ? 0 : options.offset ?? 0;
+    const end = options.head !== undefined ? options.head : options.limit !== undefined ? start + options.limit : undefined;
+    return lines.slice(start, end).join("\n");
+}
+function sessionWorkspaceStatus(cwd) {
+    const registry = readRegistry(cwd);
+    const selected = resolveSelectedSessionForList(cwd);
+    const available = registry ? Object.keys(registry.sessions).sort() : [];
+    if (selected.source === "ambiguous") {
+        return (0, agent_text_1.attachAgentText)({
+            ok: false,
+            code: "MULTIPLE_AIB_SESSIONS",
+            error: "Multiple AIB sessions exist. Select one explicitly.",
+            available,
+            next: `Use aib -s <session> <command> or set ${env_vars_1.CLI_ENV.session}=<session>.`
+        }, formatMultipleSessionsStatusText(available));
+    }
+    const workspace = selected.sessionId ? readWorkspaceById(cwd, selected.sessionId) : null;
+    if (!workspace) {
+        const response = {
+            initialized: false,
+            active: selected.sessionId ?? null,
+            source: selected.source,
+            available,
+            next: selected.sessionId
+                ? `Run aib session init --name ${selected.sessionId}`
+                : "Run aib session init --name <name>"
+        };
+        return (0, agent_text_1.attachAgentText)(response, formatSessionNotReadyStatusText(response));
+    }
+    writeWorkspace(cwd, workspace);
+    const response = {
+        initialized: true,
+        session: workspace.sessionId ?? selected.sessionId,
+        active: workspace.sessionId ?? selected.sessionId,
+        source: selected.source,
+        available,
+        sessionDir: toDisplayPath(cwd, workspace.rootDir),
+        aliases: (0, path_aliases_1.effectivePathAliases)(cwd, workspace.pathAliases ?? {}),
+        latest: latestHandles(workspace),
+        dirs: sessionDirsPayload(cwd, workspace)
+    };
+    return (0, agent_text_1.attachAgentText)(response, formatSessionStatusText(response));
+}
+function formatSessionNotReadyStatusText(response) {
+    const active = typeof response.active === "string" && response.active ? response.active : null;
+    if (active) {
+        return [
+            "session not ready",
+            "",
+            `Session ${active} was not found.`,
+            "Create it:",
+            `aib session init --name ${active}`
+        ].join("\n");
+    }
+    return [
+        "session not ready",
+        "",
+        "No AIB sessions exist in this repo.",
+        "Create one:",
+        "aib session init --name <name>"
+    ].join("\n");
+}
+function formatSessionStatusText(response) {
+    const sessionId = String(response.session ?? "");
+    const aliases = response.aliases && typeof response.aliases === "object" && !Array.isArray(response.aliases)
+        ? response.aliases
+        : {};
+    const lines = [`session: ${sessionId}`];
+    const aliasLines = Object.entries(aliases)
+        .filter(([, target]) => typeof target === "string" && target.trim() !== "")
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([name, target]) => `@${name} -> ${String(target)}`);
+    if (aliasLines.length > 0) {
+        lines.push("", "aliases:", ...aliasLines);
+    }
+    if (response.source === "single") {
+        lines.push("", "Only one AIB session exists in this repo.", "You can run AIB commands without -s.");
+    }
+    return lines.join("\n");
+}
+function formatMultipleSessionsStatusText(available) {
+    return [
+        "multiple AIB sessions",
+        "",
+        "available:",
+        ...available,
+        "",
+        "Choose one:",
+        "aib -s <session> <command>",
+        "",
+        "Or bind it in this shell:",
+        `${env_vars_1.CLI_ENV.session}=<session>`,
+        "",
+        "If none of these sessions is yours, create a new one:",
+        "aib session init --name <name>"
+    ].join("\n");
+}
+function clearSessionWorkspace(cwd) {
+    const selected = resolveSelectedSessionForList(cwd);
+    const registry = readRegistry(cwd);
+    const available = registry ? Object.keys(registry.sessions).sort() : [];
+    if (selected.source === "ambiguous") {
+        return (0, agent_text_1.attachAgentText)({
+            ok: false,
+            code: "MULTIPLE_AIB_SESSIONS",
+            error: "Multiple AIB sessions exist. Select one explicitly.",
+            available,
+            next: "Use aib -s <session> session clear."
+        }, formatMultipleSessionsClearText(available));
+    }
+    const workspace = selected.sessionId ? readWorkspaceById(cwd, selected.sessionId) : null;
+    if (!workspace) {
+        return (0, agent_text_1.attachAgentText)({
+            cleared: false,
+            reason: "session-not-initialized"
+        }, [
+            "No AIB sessions exist in this repo.",
+            "",
+            "Create one:",
+            "aib session init --name <name>"
+        ].join("\n"));
+    }
+    pruneSessionWorkspaceData(workspace, { touch: true });
+    writeWorkspace(cwd, workspace);
+    const sessionId = workspace.sessionId ?? selected.sessionId ?? "";
+    return (0, agent_text_1.attachAgentText)({
+        cleared: true,
+        session: sessionId,
+        dir: toDisplayPath(cwd, workspace.rootDir)
+    }, [
+        `session cleared: ${sessionId}`,
+        "",
+        "Inputs and outputs were pruned.",
+        "You can keep using this session."
+    ].join("\n"));
+}
+function pruneSessionWorkspaceData(workspace, options) {
+    fs.rmSync(path.join(workspace.rootDir, "inputs"), { recursive: true, force: true });
+    fs.rmSync(path.join(workspace.rootDir, "outputs"), { recursive: true, force: true });
+    workspace.inputs = {};
+    workspace.outputs = {};
+    workspace.guidance = {};
+    if (options.touch) {
+        workspace.updatedAt = new Date().toISOString();
+    }
+    ensureWorkspaceDirs(workspace);
+}
+function formatMultipleSessionsClearText(available) {
+    return [
+        "multiple AIB sessions",
+        "",
+        "available:",
+        ...available,
+        "",
+        "Clear one explicitly only if it is yours:",
+        "aib -s <session> session clear",
+        "",
+        "If none of these sessions is yours, create a new one:",
+        "aib session init --name <name>"
+    ].join("\n");
+}
+function cleanupExpiredSessions(cwd) {
+    const policy = readSessionTtlPolicy(cwd);
+    const registry = readRegistry(cwd);
+    if (!registry) {
+        return;
+    }
+    const now = Date.now();
+    let changed = false;
+    for (const [sessionId, entry] of Object.entries(registry.sessions)) {
+        const sessionFile = workspaceFilePath(entry.rootDir);
+        if (!fs.existsSync(sessionFile)) {
+            delete registry.sessions[sessionId];
+            changed = true;
+            if (registry.activeSessionId === sessionId) {
+                delete registry.activeSessionId;
+            }
+            continue;
+        }
+        const updatedAt = Date.parse(entry.updatedAt);
+        if (!Number.isFinite(updatedAt)) {
+            continue;
+        }
+        const inactiveMs = now - updatedAt;
+        if (policy.autoDelete && policy.ttlDeleteMs > 0 && inactiveMs > policy.ttlDeleteMs) {
+            fs.rmSync(entry.rootDir, { recursive: true, force: true });
+            delete registry.sessions[sessionId];
+            changed = true;
+            if (registry.activeSessionId === sessionId) {
+                delete registry.activeSessionId;
+            }
+            continue;
+        }
+        if (policy.autoClean && policy.ttlCleanMs > 0 && inactiveMs > policy.ttlCleanMs) {
+            const workspace = readWorkspaceFile(cwd, entry.rootDir, sessionId);
+            if (workspace) {
+                pruneSessionWorkspaceData(workspace, { touch: false });
+                writeWorkspacePreservingTimestamp(workspace);
+            }
+        }
+    }
+    if (!changed) {
+        return;
+    }
+    if (!registry.activeSessionId) {
+        const nextSessionId = Object.keys(registry.sessions).sort()[0];
+        if (nextSessionId) {
+            registry.activeSessionId = nextSessionId;
+        }
+    }
+    writeRegistry(cwd, registry);
+}
+function readSessionTtlPolicy(cwd) {
+    const legacyTtlMinutes = (0, workspace_root_1.readWorkspaceNumberConfig)(cwd, "session.ttlMinutes", 60);
+    const ttlDeleteMinutes = (0, workspace_root_1.readWorkspaceNumberConfig)(cwd, "session.ttlDeleteMinutes", legacyTtlMinutes);
+    const ttlCleanMinutes = (0, workspace_root_1.readWorkspaceNumberConfig)(cwd, "session.ttlCleanMinutes", legacyTtlMinutes);
+    return {
+        autoDelete: (0, workspace_root_1.readWorkspaceBooleanConfig)(cwd, "session.autoDelete", true),
+        ttlDeleteMs: ttlDeleteMinutes > 0 ? ttlDeleteMinutes * 60_000 : 0,
+        autoClean: (0, workspace_root_1.readWorkspaceBooleanConfig)(cwd, "session.autoClean", true),
+        ttlCleanMs: ttlCleanMinutes > 0 ? ttlCleanMinutes * 60_000 : 0
+    };
+}
+function ensureWorkspaceDirs(workspace) {
+    for (const kind of OUTPUT_KINDS) {
+        fs.mkdirSync(path.join(workspace.rootDir, "outputs", kind), { recursive: true });
+    }
+    for (const kind of INPUT_KINDS) {
+        fs.mkdirSync(path.join(workspace.rootDir, "inputs", kind), { recursive: true });
+    }
+}
+function readWorkspaceById(cwd, sessionId) {
+    const registry = readRegistry(cwd);
+    const entry = registry?.sessions[sessionId];
+    if (!entry) {
+        return null;
+    }
+    return readWorkspaceFile(cwd, entry.rootDir, sessionId);
+}
+function readWorkspace(cwd) {
+    const selected = resolveSelectedSession(cwd);
+    return selected.sessionId ? readWorkspaceById(cwd, selected.sessionId) : null;
+}
+function readWorkspaceForSave(cwd) {
+    cleanupExpiredSessions(cwd);
+    const workspace = readWorkspace(cwd);
+    return workspace ?? createDefaultSessionWorkspace(cwd);
+}
+function createDefaultSessionWorkspace(cwd) {
+    const workspaceRoot = (0, workspace_root_1.resolveWorkspaceRoot)(cwd);
+    if (!workspaceRoot) {
+        return null;
+    }
+    const sessionRoot = resolveSessionRoot(workspaceRoot.root, undefined, false);
+    const rootDir = path.join(sessionRoot.rootDir, DEFAULT_AUTO_SESSION_ID);
+    const now = new Date().toISOString();
+    const existing = readWorkspaceFile(workspaceRoot.root, rootDir, DEFAULT_AUTO_SESSION_ID);
+    const workspace = existing ?? {
+        version: 1,
+        sessionId: DEFAULT_AUTO_SESSION_ID,
+        auto: true,
+        cwd: path.resolve(workspaceRoot.root),
+        rootDir,
+        createdAt: now,
+        updatedAt: now,
+        outputs: {},
+        inputs: {},
+        guidance: {}
+    };
+    workspace.sessionId = DEFAULT_AUTO_SESSION_ID;
+    workspace.auto = true;
+    workspace.cwd = path.resolve(workspaceRoot.root);
+    workspace.rootDir = rootDir;
+    workspace.updatedAt = now;
+    ensureWorkspaceDirs(workspace);
+    writeWorkspace(workspaceRoot.root, workspace);
+    return workspace;
+}
+function readWorkspaceFile(cwd, rootDir, sessionId) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(workspaceFilePath(rootDir), "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return null;
+        }
+        const candidate = parsed;
+        if (candidate.version !== 1 || typeof candidate.rootDir !== "string") {
+            return null;
+        }
+        candidate.sessionId = candidate.sessionId ?? sessionId;
+        return candidate;
+    }
+    catch {
+        return null;
+    }
+}
+function readRequiredWorkspace(cwd) {
+    const workspace = readWorkspace(cwd);
+    if (!workspace) {
+        throw new errors_1.CliError("SESSION_WORKSPACE_NOT_INITIALIZED", "Session workspace is not initialized.", {
+            session: currentSessionId() ?? null,
+            next: "Run aib session init --name <name>",
+            help: "aib help session"
+        });
+    }
+    writeWorkspace(cwd, workspace);
+    return workspace;
+}
+function readRequiredWorkspaceForSave(cwd) {
+    const workspace = readWorkspaceForSave(cwd);
+    if (!workspace) {
+        throw new errors_1.CliError("SESSION_WORKSPACE_NOT_INITIALIZED", "Session workspace is not initialized.", {
+            session: currentSessionId() ?? null,
+            next: "Run aib session init --name <name>",
+            help: "aib help session"
+        });
+    }
+    return workspace;
+}
+function writeWorkspace(cwd, workspace) {
+    workspace.updatedAt = new Date().toISOString();
+    fs.mkdirSync(workspace.rootDir, { recursive: true });
+    fs.writeFileSync(workspaceFilePath(workspace.rootDir), `${JSON.stringify(workspace, null, 2)}\n`);
+    upsertRegistrySession(cwd, workspace, false);
+}
+function writeWorkspacePreservingTimestamp(workspace) {
+    fs.mkdirSync(workspace.rootDir, { recursive: true });
+    fs.writeFileSync(workspaceFilePath(workspace.rootDir), `${JSON.stringify(workspace, null, 2)}\n`);
+}
+function resolveSessionRoot(cwd, requestedDir, persistDefault = false) {
+    const workspace = (0, workspace_root_1.resolveWorkspaceRoot)(cwd);
+    const workspaceRoot = workspace?.root ?? cwd;
+    const configuredDir = workspace ? readString(workspace.config[SESSION_DIR_CONFIG_KEY]) : undefined;
+    if (configuredDir) {
+        return {
+            rootDir: normalizeSessionRootDir(workspaceRoot, configuredDir),
+            source: "aib.json",
+            ...(requestedDir ? { ignoredRequestedDir: requestedDir } : {})
+        };
+    }
+    const rawDir = requestedDir ?? DEFAULT_SESSION_ROOT;
+    const rootDir = normalizeSessionRootDir(workspaceRoot, rawDir);
+    if (persistDefault && workspace) {
+        (0, workspace_root_1.updateWorkspaceConfig)(workspaceRoot, {
+            [SESSION_DIR_CONFIG_KEY]: toConfigRelativePath(workspaceRoot, rootDir)
+        });
+    }
+    return {
+        rootDir,
+        source: requestedDir ? "request" : "default"
+    };
+}
+function normalizeSessionRootDir(workspaceRoot, rawDir) {
+    const resolved = path.resolve(workspaceRoot, rawDir);
+    return path.basename(resolved).toLowerCase() === "aib" ? resolved : path.join(resolved, "aib");
+}
+function toConfigRelativePath(workspaceRoot, filePath) {
+    const relative = path.relative(workspaceRoot, filePath);
+    return relative && !relative.startsWith("..") && !path.isAbsolute(relative)
+        ? relative.replace(/\\/g, "/")
+        : filePath.replace(/\\/g, "/");
+}
+function workspaceMarkerPath(cwd) {
+    return path.join(resolveSessionRoot(cwd).rootDir, SESSION_REGISTRY_FILE_NAME);
+}
+function activeSessionPath(cwd) {
+    return path.join(resolveSessionRoot(cwd).rootDir, ACTIVE_SESSION_FILE_NAME);
+}
+function workspaceFilePath(rootDir) {
+    return path.join(rootDir, "session.json");
+}
+function readRegistry(cwd) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(workspaceMarkerPath(cwd), "utf8"));
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return null;
+        }
+        const candidate = parsed;
+        if (candidate.version !== 1 || !candidate.sessions || typeof candidate.sessions !== "object") {
+            return null;
+        }
+        return {
+            version: 1,
+            cwd: typeof candidate.cwd === "string" ? candidate.cwd : path.resolve(cwd),
+            ...(typeof candidate.activeSessionId === "string" ? { activeSessionId: candidate.activeSessionId } : {}),
+            sessions: candidate.sessions
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function writeRegistry(cwd, registry) {
+    registry.cwd = path.resolve((0, workspace_root_1.resolveWorkspaceRoot)(cwd)?.root ?? cwd);
+    fs.mkdirSync(path.dirname(workspaceMarkerPath(cwd)), { recursive: true });
+    fs.writeFileSync(workspaceMarkerPath(cwd), `${JSON.stringify(registry, null, 2)}\n`);
+    writeActiveSession(cwd, registry.activeSessionId);
+}
+function createEmptyRegistry(cwd) {
+    return {
+        version: 1,
+        cwd: path.resolve(cwd),
+        sessions: {}
+    };
+}
+function writeActiveSession(cwd, sessionId) {
+    const file = activeSessionPath(cwd);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    if (!sessionId) {
+        fs.rmSync(file, { force: true });
+        return;
+    }
+    fs.writeFileSync(file, `${JSON.stringify({ sessionId, updatedAt: new Date().toISOString() }, null, 2)}\n`);
+}
+function upsertRegistrySession(cwd, workspace, makeActive) {
+    const sessionId = workspace.sessionId ?? currentSessionId() ?? "";
+    if (!sessionId) {
+        return;
+    }
+    const registry = readRegistry(cwd) ?? createEmptyRegistry(cwd);
+    registry.sessions[sessionId] = {
+        sessionId,
+        ...(workspace.auto ? { auto: true } : {}),
+        rootDir: workspace.rootDir,
+        createdAt: registry.sessions[sessionId]?.createdAt ?? workspace.createdAt,
+        updatedAt: workspace.updatedAt
+    };
+    if (makeActive || !registry.activeSessionId) {
+        registry.activeSessionId = sessionId;
+    }
+    writeRegistry(cwd, registry);
+}
+function removeRegistrySession(cwd, sessionId) {
+    const registry = readRegistry(cwd);
+    if (!registry || !sessionId) {
+        return;
+    }
+    delete registry.sessions[sessionId];
+    if (registry.activeSessionId === sessionId) {
+        const nextSessionId = Object.keys(registry.sessions).sort()[0];
+        if (nextSessionId) {
+            registry.activeSessionId = nextSessionId;
+        }
+        else {
+            delete registry.activeSessionId;
+        }
+    }
+    writeRegistry(cwd, registry);
+}
+function resolveSelectedSession(cwd) {
+    const override = sessionOverrideStorage.getStore();
+    if (override) {
+        return { sessionId: sanitizeSessionId(override), source: "override" };
+    }
+    const envSession = process.env[env_vars_1.CLI_ENV.session];
+    if (envSession && envSession.trim()) {
+        return { sessionId: sanitizeSessionId(envSession), source: "env" };
+    }
+    const legacyEnvSession = process.env[env_vars_1.CLI_ENV.legacySession];
+    if (legacyEnvSession && legacyEnvSession.trim()) {
+        return { sessionId: sanitizeSessionId(legacyEnvSession), source: "legacy-env" };
+    }
+    const registry = readRegistry(cwd);
+    const sessions = registry ? Object.keys(registry.sessions).sort() : [];
+    if (sessions.length === 1) {
+        return { sessionId: sessions[0], source: "single" };
+    }
+    if (sessions.length > 1) {
+        throw new errors_1.CliError("MULTIPLE_AIB_SESSIONS", "Multiple AIB sessions exist. Select one explicitly.", {
+            available: sessions,
+            next: `Use aib -s <session> <command> or set ${env_vars_1.CLI_ENV.session}=<session>.`
+        });
+    }
+    return { sessionId: null, source: "none" };
+}
+function resolveSelectedSessionForList(cwd) {
+    try {
+        return resolveSelectedSession(cwd);
+    }
+    catch (error) {
+        if (error instanceof errors_1.CliError && error.code === "MULTIPLE_AIB_SESSIONS") {
+            return { sessionId: null, source: "ambiguous" };
+        }
+        throw error;
+    }
+}
+function tryResolveCurrentSessionId(cwd) {
+    const selected = resolveSelectedSessionForList(cwd);
+    return {
+        sessionId: selected.sessionId,
+        sessionSource: selected.source
+    };
+}
+function currentSessionId() {
+    const override = sessionOverrideStorage.getStore();
+    if (override) {
+        return sanitizeSessionId(override);
+    }
+    const envSession = process.env[env_vars_1.CLI_ENV.session];
+    if (envSession && envSession.trim()) {
+        return sanitizeSessionId(envSession);
+    }
+    const legacyEnvSession = process.env[env_vars_1.CLI_ENV.legacySession];
+    return legacyEnvSession && legacyEnvSession.trim() ? sanitizeSessionId(legacyEnvSession) : null;
+}
+function sessionOutputPath(workspace, kind, name, extension) {
+    return path.join(workspace.rootDir, "outputs", sanitizePathSegment(kind), `${sanitizePathSegment(name)}${sanitizeExtension(extension)}`);
+}
+function sessionInputPath(workspace, kind, name, extension = ".json") {
+    return path.join(workspace.rootDir, "inputs", sanitizePathSegment(kind), `${sanitizePathSegment(name)}${sanitizeExtension(extension)}`);
+}
+function sessionCompiledInputPath(workspace, kind, name) {
+    return path.join(workspace.rootDir, "inputs", sanitizePathSegment(kind), `${sanitizePathSegment(name)}.compiled.json`);
+}
+function sessionLastInputPath(workspace, kind, extension = ".json") {
+    return path.join(workspace.rootDir, "inputs", sanitizePathSegment(kind), extension === ".json" ? LAST_INPUT_FILE_NAME : `_last${sanitizeExtension(extension)}`);
+}
+function writeJsonFile(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`);
+}
+function writeTextFile(file, value) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, value.endsWith("\n") ? value : `${value}\n`, "utf8");
+}
+function registerLastInputArtifact(workspace, kind, value, source) {
+    const normalizedKind = sanitizePathSegment(kind);
+    const inputSource = source ?? { format: "json", text: JSON.stringify(value, null, 2) };
+    const file = inputSource.format === "dsl"
+        ? sessionLastInputPath(workspace, normalizedKind, ".dsl")
+        : sessionLastInputPath(workspace, normalizedKind, ".json");
+    if (inputSource.format === "dsl") {
+        writeTextFile(file, inputSource.text);
+        writeJsonFile(path.join(workspace.rootDir, "inputs", normalizedKind, "_last.compiled.json"), value);
+        fs.rmSync(sessionLastInputPath(workspace, normalizedKind, ".json"), { force: true });
+    }
+    else {
+        writeJsonFile(file, value);
+        fs.rmSync(sessionLastInputPath(workspace, normalizedKind, ".dsl"), { force: true });
+        fs.rmSync(path.join(workspace.rootDir, "inputs", normalizedKind, "_last.compiled.json"), { force: true });
+    }
+    registerArtifact(workspace, "inputs", normalizedKind, LAST_INPUT_NAME, file);
+}
+function registerArtifact(workspace, group, kind, name, file) {
+    const normalizedKind = sanitizePathSegment(kind);
+    const normalizedName = sanitizePathSegment(name);
+    const handle = group === "inputs"
+        ? `aib:input:${normalizedKind}:${normalizedName}`
+        : `aib:${normalizedKind}:${normalizedName}`;
+    const now = new Date().toISOString();
+    const buckets = workspace[group];
+    const bucket = buckets[normalizedKind] ?? { items: {} };
+    const artifact = {
+        handle,
+        file,
+        createdAt: bucket.items[normalizedName]?.createdAt ?? now,
+        updatedAt: now
+    };
+    bucket.items[normalizedName] = artifact;
+    bucket.last = normalizedName;
+    buckets[normalizedKind] = bucket;
+    return artifact;
+}
+function parseSessionHandle(handle) {
+    const parts = handle.split(":");
+    if (parts[0] !== "aib") {
+        throw new errors_1.CliError("INVALID_SESSION_HANDLE", `Invalid session handle: ${handle}`);
+    }
+    if (parts[1] === "input" && parts.length === 4) {
+        return { scope: "input", kind: parts[2] ?? "", name: parts[3] ?? "" };
+    }
+    if (parts.length === 3) {
+        return { scope: parts[1] ?? "", kind: parts[1] ?? "", name: parts[2] ?? "" };
+    }
+    throw new errors_1.CliError("INVALID_SESSION_HANDLE", `Invalid session handle: ${handle}`, {
+        expected: "aib:<kind>:<name> or aib:input:<kind>:<name>"
+    });
+}
+function latestHandles(workspace) {
+    const latest = {};
+    for (const [kind, bucket] of Object.entries(workspace.outputs)) {
+        if (bucket.last) {
+            latest[kind] = `aib:${kind}:${bucket.last}`;
+        }
+    }
+    for (const [kind, bucket] of Object.entries(workspace.inputs)) {
+        if (bucket.last) {
+            latest[`input:${kind}`] = `aib:input:${kind}:${bucket.last}`;
+        }
+    }
+    return latest;
+}
+function sessionDirsPayload(cwd, workspace) {
+    return {
+        outputs: toDisplayPath(cwd, path.join(workspace.rootDir, "outputs")),
+        inputs: toDisplayPath(cwd, path.join(workspace.rootDir, "inputs"))
+    };
+}
+function readFlagValue(args, flag) {
+    const index = args.indexOf(flag);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function readString(value) {
+    return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+function readOptionalNonNegativeInteger(value, message) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        throw new errors_1.CliError("INVALID_SESSION_READ_RANGE", message);
+    }
+    return parsed;
+}
+function readOptionalPositiveInteger(value, message) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const parsed = readOptionalNonNegativeInteger(value, message);
+    if (parsed === undefined) {
+        return undefined;
+    }
+    if (parsed <= 0) {
+        throw new errors_1.CliError("INVALID_SESSION_READ_RANGE", message);
+    }
+    return parsed;
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function sanitizePathSegment(value) {
+    const sanitized = value.trim().replace(/[^A-Za-z0-9._-]/g, "-").replace(/^-+|-+$/g, "");
+    if (!sanitized) {
+        throw new errors_1.CliError("INVALID_SESSION_ARTIFACT_NAME", `Invalid session artifact name: ${value}`);
+    }
+    return sanitized;
+}
+function sanitizeSessionId(value) {
+    const sanitized = value.trim().replace(/[^A-Za-z0-9._-]/g, "-").replace(/^-+|-+$/g, "");
+    if (!sanitized) {
+        throw new errors_1.CliError("INVALID_SESSION_ID", `Invalid session id: ${value}`);
+    }
+    return sanitized;
+}
+function createSessionId() {
+    return `${SESSION_ID_PREFIX}${Math.random().toString(16).slice(2, 8)}`;
+}
+function sanitizeExtension(value) {
+    const extension = value.startsWith(".") ? value : `.${value}`;
+    return extension.replace(/[^A-Za-z0-9.]/g, "") || ".txt";
+}
+function numberOrZero(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+function plural(count, singular) {
+    return count === 1 ? singular : `${singular}s`;
+}
+function toDisplayPath(cwd, filePath) {
+    const relative = path.relative(cwd, filePath);
+    return relative && !relative.startsWith("..") ? relative.replace(/\\/g, "/") : filePath;
+}