@cleocode/core 2026.9.25 → 2026.9.26

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (208) hide show
  1. package/dist/admin/import-tasks.d.ts.map +1 -1
  2. package/dist/admin/import-tasks.js +5 -2
  3. package/dist/admin/import-tasks.js.map +1 -1
  4. package/dist/admin/import.d.ts.map +1 -1
  5. package/dist/admin/import.js +7 -2
  6. package/dist/admin/import.js.map +1 -1
  7. package/dist/build-provenance.json +2 -2
  8. package/dist/cloud/index.d.ts +1 -0
  9. package/dist/cloud/index.d.ts.map +1 -1
  10. package/dist/cloud/index.js +1 -0
  11. package/dist/cloud/index.js.map +1 -1
  12. package/dist/cloud/nexus-auth.d.ts +26 -1
  13. package/dist/cloud/nexus-auth.d.ts.map +1 -1
  14. package/dist/cloud/nexus-auth.js +61 -32
  15. package/dist/cloud/nexus-auth.js.map +1 -1
  16. package/dist/cloud/nexus-credentials.js +2 -2
  17. package/dist/cloud/nexus-credentials.js.map +1 -1
  18. package/dist/cloud/nexus-device.d.ts +809 -0
  19. package/dist/cloud/nexus-device.d.ts.map +1 -0
  20. package/dist/cloud/nexus-device.js +1680 -0
  21. package/dist/cloud/nexus-device.js.map +1 -0
  22. package/dist/cloud/nexus-enrol.d.ts +210 -0
  23. package/dist/cloud/nexus-enrol.d.ts.map +1 -0
  24. package/dist/cloud/nexus-enrol.js +1023 -0
  25. package/dist/cloud/nexus-enrol.js.map +1 -0
  26. package/dist/cloud/nexus-link.d.ts +3 -0
  27. package/dist/cloud/nexus-link.d.ts.map +1 -1
  28. package/dist/cloud/nexus-link.js +38 -4
  29. package/dist/cloud/nexus-link.js.map +1 -1
  30. package/dist/cloud/signing.d.ts +20 -0
  31. package/dist/cloud/signing.d.ts.map +1 -1
  32. package/dist/cloud/signing.js +14 -0
  33. package/dist/cloud/signing.js.map +1 -1
  34. package/dist/crypto/credentials.d.ts +61 -0
  35. package/dist/crypto/credentials.d.ts.map +1 -1
  36. package/dist/crypto/credentials.js +154 -58
  37. package/dist/crypto/credentials.js.map +1 -1
  38. package/dist/docs/export-document.js +830 -190
  39. package/dist/docs/export-document.js.map +3 -3
  40. package/dist/doctor/dependency-cycles.d.ts +41 -0
  41. package/dist/doctor/dependency-cycles.d.ts.map +1 -0
  42. package/dist/doctor/dependency-cycles.js +39 -0
  43. package/dist/doctor/dependency-cycles.js.map +1 -0
  44. package/dist/doctor/index.d.ts +2 -0
  45. package/dist/doctor/index.d.ts.map +1 -1
  46. package/dist/doctor/index.js +1 -0
  47. package/dist/doctor/index.js.map +1 -1
  48. package/dist/doctor/row-identity.d.ts +11 -0
  49. package/dist/doctor/row-identity.d.ts.map +1 -1
  50. package/dist/doctor/row-identity.js +67 -9
  51. package/dist/doctor/row-identity.js.map +1 -1
  52. package/dist/error-catalog.d.ts.map +1 -1
  53. package/dist/error-catalog.js +4 -0
  54. package/dist/error-catalog.js.map +1 -1
  55. package/dist/error-registry.d.ts.map +1 -1
  56. package/dist/error-registry.js +8 -0
  57. package/dist/error-registry.js.map +1 -1
  58. package/dist/llm/plugin-facade.js +857 -217
  59. package/dist/llm/plugin-facade.js.map +3 -3
  60. package/dist/nexus/workspace.d.ts.map +1 -1
  61. package/dist/nexus/workspace.js +54 -4
  62. package/dist/nexus/workspace.js.map +1 -1
  63. package/dist/orchestrate/lifecycle-ops.js +1 -1
  64. package/dist/orchestrate/lifecycle-ops.js.map +1 -1
  65. package/dist/orchestrate/pivot.d.ts.map +1 -1
  66. package/dist/orchestrate/pivot.js +4 -2
  67. package/dist/orchestrate/pivot.js.map +1 -1
  68. package/dist/orchestrate/query-ops.d.ts.map +1 -1
  69. package/dist/orchestrate/query-ops.js +3 -3
  70. package/dist/orchestrate/query-ops.js.map +1 -1
  71. package/dist/orchestrate/spawn-ops.js +1 -1
  72. package/dist/orchestrate/spawn-ops.js.map +1 -1
  73. package/dist/orchestration/index.js +1 -1
  74. package/dist/orchestration/index.js.map +1 -1
  75. package/dist/orchestration/lead-rollup.d.ts.map +1 -1
  76. package/dist/orchestration/lead-rollup.js +3 -3
  77. package/dist/orchestration/lead-rollup.js.map +1 -1
  78. package/dist/orchestration/parallel.js +1 -1
  79. package/dist/orchestration/parallel.js.map +1 -1
  80. package/dist/orchestration/wave-topic.d.ts +4 -2
  81. package/dist/orchestration/wave-topic.d.ts.map +1 -1
  82. package/dist/orchestration/wave-topic.js +6 -4
  83. package/dist/orchestration/wave-topic.js.map +1 -1
  84. package/dist/orchestration/waves.d.ts +2 -1
  85. package/dist/orchestration/waves.d.ts.map +1 -1
  86. package/dist/orchestration/waves.js +4 -3
  87. package/dist/orchestration/waves.js.map +1 -1
  88. package/dist/phases/index.d.ts.map +1 -1
  89. package/dist/phases/index.js +4 -2
  90. package/dist/phases/index.js.map +1 -1
  91. package/dist/selfimprove/fix-gen.js +856 -216
  92. package/dist/selfimprove/fix-gen.js.map +3 -3
  93. package/dist/session/engine-ops.d.ts.map +1 -1
  94. package/dist/session/engine-ops.js +77 -49
  95. package/dist/session/engine-ops.js.map +1 -1
  96. package/dist/sessions/focus-state-store.d.ts +69 -23
  97. package/dist/sessions/focus-state-store.d.ts.map +1 -1
  98. package/dist/sessions/focus-state-store.js +113 -27
  99. package/dist/sessions/focus-state-store.js.map +1 -1
  100. package/dist/sessions/handoff.js +1 -1
  101. package/dist/sessions/handoff.js.map +1 -1
  102. package/dist/sessions/index.d.ts.map +1 -1
  103. package/dist/sessions/index.js +24 -13
  104. package/dist/sessions/index.js.map +1 -1
  105. package/dist/sessions/terminal-identity.d.ts +165 -17
  106. package/dist/sessions/terminal-identity.d.ts.map +1 -1
  107. package/dist/sessions/terminal-identity.js +341 -32
  108. package/dist/sessions/terminal-identity.js.map +1 -1
  109. package/dist/skills/orchestrator/startup.js +2 -2
  110. package/dist/skills/orchestrator/startup.js.map +1 -1
  111. package/dist/snapshot/index.d.ts +4 -0
  112. package/dist/snapshot/index.d.ts.map +1 -1
  113. package/dist/snapshot/index.js +50 -3
  114. package/dist/snapshot/index.js.map +1 -1
  115. package/dist/store/db-helpers.d.ts +15 -2
  116. package/dist/store/db-helpers.d.ts.map +1 -1
  117. package/dist/store/db-helpers.js +84 -3
  118. package/dist/store/db-helpers.js.map +1 -1
  119. package/dist/store/dependency-cycles.d.ts +164 -0
  120. package/dist/store/dependency-cycles.d.ts.map +1 -0
  121. package/dist/store/dependency-cycles.js +360 -0
  122. package/dist/store/dependency-cycles.js.map +1 -0
  123. package/dist/store/display-id-alias.d.ts +93 -37
  124. package/dist/store/display-id-alias.d.ts.map +1 -1
  125. package/dist/store/display-id-alias.js +590 -115
  126. package/dist/store/display-id-alias.js.map +1 -1
  127. package/dist/store/dual-scope-db.d.ts.map +1 -1
  128. package/dist/store/dual-scope-db.js +34 -7
  129. package/dist/store/dual-scope-db.js.map +1 -1
  130. package/dist/store/exodus/migrate.d.ts.map +1 -1
  131. package/dist/store/exodus/migrate.js +8 -1
  132. package/dist/store/exodus/migrate.js.map +1 -1
  133. package/dist/store/global-salt.d.ts +35 -0
  134. package/dist/store/global-salt.d.ts.map +1 -1
  135. package/dist/store/global-salt.js +136 -16
  136. package/dist/store/global-salt.js.map +1 -1
  137. package/dist/store/migration-sqlite.d.ts.map +1 -1
  138. package/dist/store/migration-sqlite.js +19 -11
  139. package/dist/store/migration-sqlite.js.map +1 -1
  140. package/dist/store/portable-bundle-scan.d.ts.map +1 -1
  141. package/dist/store/portable-bundle-scan.js +6 -0
  142. package/dist/store/portable-bundle-scan.js.map +1 -1
  143. package/dist/store/row-identity-registry.d.ts.map +1 -1
  144. package/dist/store/row-identity-registry.js +11 -3
  145. package/dist/store/row-identity-registry.js.map +1 -1
  146. package/dist/store/row-identity.d.ts +91 -1
  147. package/dist/store/row-identity.d.ts.map +1 -1
  148. package/dist/store/row-identity.js +276 -7
  149. package/dist/store/row-identity.js.map +1 -1
  150. package/dist/store/safety-data-accessor.d.ts +3 -2
  151. package/dist/store/safety-data-accessor.d.ts.map +1 -1
  152. package/dist/store/safety-data-accessor.js +5 -2
  153. package/dist/store/safety-data-accessor.js.map +1 -1
  154. package/dist/store/session-store.d.ts +63 -3
  155. package/dist/store/session-store.d.ts.map +1 -1
  156. package/dist/store/session-store.js +121 -8
  157. package/dist/store/session-store.js.map +1 -1
  158. package/dist/store/split-brain-import.d.ts.map +1 -1
  159. package/dist/store/split-brain-import.js +36 -0
  160. package/dist/store/split-brain-import.js.map +1 -1
  161. package/dist/store/sqlite-data-accessor.d.ts +50 -3
  162. package/dist/store/sqlite-data-accessor.d.ts.map +1 -1
  163. package/dist/store/sqlite-data-accessor.js +246 -13
  164. package/dist/store/sqlite-data-accessor.js.map +1 -1
  165. package/dist/store/tasks-sqlite.d.ts.map +1 -1
  166. package/dist/store/tasks-sqlite.js +14 -2
  167. package/dist/store/tasks-sqlite.js.map +1 -1
  168. package/dist/store/umbrella-data-accessor.d.ts +3 -2
  169. package/dist/store/umbrella-data-accessor.d.ts.map +1 -1
  170. package/dist/store/umbrella-data-accessor.js +5 -2
  171. package/dist/store/umbrella-data-accessor.js.map +1 -1
  172. package/dist/system/health.d.ts +2 -0
  173. package/dist/system/health.d.ts.map +1 -1
  174. package/dist/system/health.js +54 -0
  175. package/dist/system/health.js.map +1 -1
  176. package/dist/task-work/index.d.ts.map +1 -1
  177. package/dist/task-work/index.js +9 -6
  178. package/dist/task-work/index.js.map +1 -1
  179. package/dist/tasks/analyze.d.ts.map +1 -1
  180. package/dist/tasks/analyze.js +3 -2
  181. package/dist/tasks/analyze.js.map +1 -1
  182. package/dist/tasks/evidence.d.ts +19 -1
  183. package/dist/tasks/evidence.d.ts.map +1 -1
  184. package/dist/tasks/evidence.js +79 -18
  185. package/dist/tasks/evidence.js.map +1 -1
  186. package/dist/tasks/infer-add-params.js +1 -1
  187. package/dist/tasks/infer-add-params.js.map +1 -1
  188. package/dist/tasks/task-context.d.ts.map +1 -1
  189. package/dist/tasks/task-context.js +3 -1
  190. package/dist/tasks/task-context.js.map +1 -1
  191. package/dist/tasks/task-import.d.ts.map +1 -1
  192. package/dist/tasks/task-import.js +11 -3
  193. package/dist/tasks/task-import.js.map +1 -1
  194. package/dist/tasks/task-next.d.ts +5 -1
  195. package/dist/tasks/task-next.d.ts.map +1 -1
  196. package/dist/tasks/task-next.js +7 -2
  197. package/dist/tasks/task-next.js.map +1 -1
  198. package/dist/validation/engine-ops.d.ts.map +1 -1
  199. package/dist/validation/engine-ops.js +3 -2
  200. package/dist/validation/engine-ops.js.map +1 -1
  201. package/dist/workgraph/scaffold-apply.d.ts.map +1 -1
  202. package/dist/workgraph/scaffold-apply.js +14 -5
  203. package/dist/workgraph/scaffold-apply.js.map +1 -1
  204. package/migrations/drizzle-cleo-project/20260930160000_t12886-dependency-cycle-guard/migration.sql +76 -0
  205. package/migrations/drizzle-cleo-project/20260930160000_t12886-dependency-cycle-guard/revert.sql +7 -0
  206. package/package.json +13 -13
  207. package/templates/CLEO-INJECTION.md +2 -2
  208. package/templates/CLEO-REFERENCE.md +1 -1
@@ -22,24 +22,40 @@
22
22
  * in `session-id.ts`, whose values ARE CLEO ids). They are opaque identities
23
23
  * that only mean something through a persisted binding.
24
24
  *
25
- * ## ppid-chain fallback
25
+ * ## Harness-ancestor fallback (T12864)
26
26
  *
27
27
  * When no environment key is present, the identity falls back to the nearest
28
- * ancestor process that is not a launcher (node, pnpm, npx, mise, …) — in
29
- * practice the interactive shell of the terminal tab. The key carries the
30
- * process start time, so a recycled pid never matches a stale binding. The walk
31
- * is bounded ({@link PPID_CHAIN_MAX_DEPTH}) and never climbs past the first
32
- * non-launcher ancestor, because anything above the shell (the terminal
33
- * emulator, tmux server, launchd) is shared by every tab and would re-create the
34
- * cross-terminal bleed this module exists to remove.
28
+ * ancestor that identifies ONE caller ({@link resolveAncestor}): a long-lived
29
+ * interactive or script shell (the terminal tab's shell, a CI step or cron
30
+ * script), or — past throwaway `sh -c` / `bash -c` layers — a KNOWN agent
31
+ * harness process ({@link KNOWN_HARNESSES}: Kimi, aider, …). Such harnesses run every tool call in a fresh `bash -c`, so the
32
+ * immediate parent changes on each call; the harness process does not. Any
33
+ * other process (a node / python host that may run several agents, a daemon
34
+ * spawning `cleo` directly) identifies nobody unless `CLEO_AGENT_ID` names the
35
+ * agent. Pid 1 / launchd / systemd / init, an unreadable shell command line or
36
+ * depth exhaustion also yield no key: the caller keeps the single-session guard.
37
+ *
38
+ * Env tab keys are inherited by every descendant, so when a harness (or a
39
+ * `CLEO_AGENT_ID` agent) runs below one, its anchor is appended as a more
40
+ * specific key — two harnesses in one ssh login or CI step stay apart.
41
+ *
42
+ * Before T12864 the fallback stopped at the first non-launcher ancestor, which
43
+ * for a harness is the per-call `bash -c` — a new key on every call, so a
44
+ * session started in one call was invisible to the next (T12530 therefore
45
+ * stopped treating it as identity).
35
46
  *
36
47
  * @module
37
48
  * @task T12499
38
49
  * @epic T12497
39
50
  */
40
51
  import { PS_STABLE_ENV } from '@cleocode/contracts';
41
- /** Where a terminal key comes from. */
42
- export type TerminalKeyKind = 'provider' | 'multiplexer' | 'terminal' | 'ppid';
52
+ /**
53
+ * Where a terminal key comes from. `process` is a long-lived ancestor shell
54
+ * (tab tier) and `harness` one agent below it or anywhere (pane tier) — both
55
+ * T12864; `ppid` is the pre-T12864 per-call fallback, never produced any more
56
+ * and kept only so rows written before it still type-check.
57
+ */
58
+ export type TerminalKeyKind = 'provider' | 'multiplexer' | 'terminal' | 'process' | 'harness' | 'ppid';
43
59
  /**
44
60
  * One row of the provider/terminal key map: an environment variable whose value
45
61
  * identifies a single harness session, multiplexer pane or terminal tab.
@@ -48,7 +64,7 @@ export interface TerminalKeySource {
48
64
  /** Environment variable carrying the identity value. */
49
65
  readonly envVar: string;
50
66
  /** Category of identity (drives precedence documentation only). */
51
- readonly kind: Exclude<TerminalKeyKind, 'ppid'>;
67
+ readonly kind: Exclude<TerminalKeyKind, 'ppid' | 'process' | 'harness'>;
52
68
  /** Harness / terminal that exports the variable. */
53
69
  readonly origin: string;
54
70
  /**
@@ -57,6 +73,12 @@ export interface TerminalKeySource {
57
73
  * pid, session index) to stay unique across servers.
58
74
  */
59
75
  readonly qualifierEnvVar?: string;
76
+ /**
77
+ * Further qualifiers, applied after {@link qualifierEnvVar} (T12864). A
78
+ * GitHub Actions run id alone is shared by every job of the run, so it is
79
+ * qualified by the attempt and the job id.
80
+ */
81
+ readonly extraQualifierEnvVars?: readonly string[];
60
82
  }
61
83
  /**
62
84
  * The provider/terminal key map, in precedence order (T12499).
@@ -83,13 +105,48 @@ export declare const PPID_CHAIN_LAUNCHERS: ReadonlySet<string>;
83
105
  * lock (T12506) renders start times identically.
84
106
  */
85
107
  export { PS_STABLE_ENV };
86
- /** Maximum number of ancestors the ppid-chain walk inspects. */
87
- export declare const PPID_CHAIN_MAX_DEPTH: 4;
108
+ /** Maximum number of ancestors the harness-ancestor walk inspects (T12864). */
109
+ export declare const PPID_CHAIN_MAX_DEPTH: 12;
110
+ /**
111
+ * Agent harnesses recognised by the ancestor walk (T12864), by PROGRAM name:
112
+ * the executable, or the script / `-m` module a `node` / `python` runtime runs
113
+ * (see {@link programName}). A listed process becomes a caller identity, even
114
+ * though it runs every tool call in a fresh `bash -c`.
115
+ *
116
+ * List ONLY processes that host exactly ONE agent session for their whole
117
+ * life. A process that hosts several (an IDE extension host, CrewAI,
118
+ * LangGraph, OpenHands, a server that clients attach to) must NOT be listed:
119
+ * its agents would share one session. Such hosts set `CLEO_AGENT_ID` per agent.
120
+ * Avoid names that other common tools also use.
121
+ *
122
+ * To add a harness: append the program name its process shows (check with
123
+ * `ps -o args= -p <pid>` while it runs a tool call), after confirming it is
124
+ * single-agent.
125
+ *
126
+ * Deliberately NOT listed:
127
+ * - `opencode`: `opencode serve` / `opencode web` run one server process that
128
+ * hosts many sessions and clients (`opencode attach`, `opencode run
129
+ * --attach`, `GET /session/status` for all sessions; opencode.ai/docs/server),
130
+ * and tools run in that server process.
131
+ * - `goose`: collides with pressly/goose, the database migration tool.
132
+ */
133
+ export declare const KNOWN_HARNESSES: ReadonlySet<string>;
134
+ /**
135
+ * Thin wrappers between a caller and `cleo` (T12864). They live exactly as long
136
+ * as the command they wrap, so the walk skips them. Matched on program name, so
137
+ * `npm exec …` (npx's process title) and `node …/npm-cli.js` both match.
138
+ */
139
+ export declare const ANCESTOR_WRAPPERS: ReadonlySet<string>;
140
+ /**
141
+ * The system's init / service manager (T12864). An ancestor walk that reaches
142
+ * one of these (or pid 1) found no caller-owned process.
143
+ */
144
+ export declare const INIT_PROCESSES: ReadonlySet<string>;
88
145
  /** One resolved identity key for the calling terminal. */
89
146
  export interface TerminalKey {
90
- /** Opaque, stable binding key (`env:<VAR>=<value>` or `ppid:<pid>@<start>`). */
147
+ /** Opaque, stable binding key (`env:<VAR>=<value>`, `proc:<pid>@<start>` or `harness:…`). */
91
148
  readonly key: string;
92
- /** Environment variable name, or `'ppid'` for the process-chain fallback. */
149
+ /** Environment variable name, or `'process'` for the harness-ancestor fallback. */
93
150
  readonly source: string;
94
151
  /** Identity category. */
95
152
  readonly kind: TerminalKeyKind;
@@ -107,6 +164,8 @@ export interface ProcessAncestor {
107
164
  }
108
165
  /** Reads one process-table entry; returns `null` when the pid is unknown. */
109
166
  export type ProcessLookup = (pid: number) => ProcessAncestor | null;
167
+ /** Reads a process's full command line; returns `null` when it cannot be read (T12864). */
168
+ export type ProcessArgsLookup = (pid: number) => string | null;
110
169
  /** Inputs for {@link resolveTerminalKeys}; every field defaults to the live process. */
111
170
  export interface ResolveTerminalKeysOptions {
112
171
  /** Environment to read (defaults to `process.env`). */
@@ -115,6 +174,8 @@ export interface ResolveTerminalKeysOptions {
115
174
  readonly ppid?: number;
116
175
  /** Process-table reader (defaults to {@link readProcessEntry}). */
117
176
  readonly lookupProcess?: ProcessLookup;
177
+ /** Command-line reader for shells (defaults to {@link readProcessArgs}). */
178
+ readonly lookupArgs?: ProcessArgsLookup;
118
179
  }
119
180
  /**
120
181
  * Read one entry from the OS process table via `ps` (POSIX only).
@@ -126,6 +187,91 @@ export interface ResolveTerminalKeysOptions {
126
187
  * @returns The process entry, or `null`.
127
188
  */
128
189
  export declare function readProcessEntry(pid: number): ProcessAncestor | null;
190
+ /**
191
+ * Read a process's command line via `ps -o args=` (POSIX only, T12864).
192
+ *
193
+ * Tells a throwaway `sh -c '…'` from a long-lived shell, and names the program
194
+ * a runtime runs. Returns `null` on Windows, for an unknown pid, or when `ps`
195
+ * fails.
196
+ *
197
+ * @param pid - Process id to inspect.
198
+ * @returns The command line, or `null`.
199
+ */
200
+ export declare function readProcessArgs(pid: number): string | null;
201
+ /**
202
+ * The program a process runs, from its command line (T12864): the executable's
203
+ * base name, or — for a language runtime ({@link RUNTIME_PATTERN}) — the
204
+ * `-m` module or script it runs (extension stripped). Matches on the FIRST
205
+ * word, so a process title such as `npm exec cleo` is `npm`.
206
+ *
207
+ * @param commandLine - `ps -o args=` output (or the bare command name).
208
+ * @returns The program name.
209
+ * @example
210
+ * ```ts
211
+ * programName('/usr/bin/python3.12 -m aider --yes'); // 'aider'
212
+ * programName('npm exec cleo start T1'); // 'npm'
213
+ * ```
214
+ */
215
+ export declare function programName(commandLine: string): string;
216
+ /**
217
+ * Whether a shell's command line runs a single command string (`sh -c '…'`,
218
+ * `bash -lc '…'`, `pwsh -Command …`) — a throwaway shell that exits with the
219
+ * command — rather than an interactive or script shell that outlives it (T12864).
220
+ *
221
+ * POSIX-style shells: options are read up to the first operand. `-c`,
222
+ * `--command` / `--commands` (fish, nu), or a short-option cluster containing
223
+ * `c` means command mode; the arguments of `-o` / `+o` / `-O` / `+O` /
224
+ * `--rcfile` / `--init-file` are skipped rather than read as the operand.
225
+ * PowerShell: any `-Command` / `-c` / `-EncodedCommand` / `-CommandWithArgs`.
226
+ *
227
+ * @param args - The shell's full command line.
228
+ * @returns `true` for a command-string shell.
229
+ */
230
+ export declare function isCommandStringShell(args: string): boolean;
231
+ /** What the ancestor walk anchored on (T12864). */
232
+ export interface AncestorAnchor {
233
+ /** The anchoring process. */
234
+ readonly entry: ProcessAncestor;
235
+ /** Its program name ({@link programName}). */
236
+ readonly program: string;
237
+ /**
238
+ * `shell` — a long-lived interactive / login / script shell (the terminal's
239
+ * own identity); `harness` — a {@link KNOWN_HARNESSES} process; `host` — any
240
+ * other process, anchored ONLY because `CLEO_AGENT_ID` names the agent. Set
241
+ * `CLEO_AGENT_ID` only in a LONG-LIVED host: with it, the first non-harness
242
+ * ancestor anchors, even a short-lived `make`, and the key then changes on
243
+ * every call.
244
+ */
245
+ readonly type: 'shell' | 'harness' | 'host';
246
+ }
247
+ /**
248
+ * Walk to the nearest ancestor that identifies ONE caller across its `cleo`
249
+ * calls (T12864).
250
+ *
251
+ * From `cleo`'s parent upwards, by program name ({@link programName}):
252
+ *
253
+ * - wrappers ({@link ANCESTOR_WRAPPERS}) are skipped;
254
+ * - a shell that is not a command-string shell ({@link isCommandStringShell})
255
+ * is long-lived — one per terminal tab, CI step or script: `shell`;
256
+ * - a command-string shell (`bash -c`) is skipped;
257
+ * - a {@link KNOWN_HARNESSES} process is `harness`;
258
+ * - any other process ends the walk: it may host SEVERAL agents (a node or
259
+ * python orchestrator, an IDE extension host, a daemon spawning `cleo`
260
+ * directly), so it identifies nobody — unless `agentId` (`CLEO_AGENT_ID`)
261
+ * names the agent, which makes it a `host` anchor.
262
+ *
263
+ * Returns `null` — no identity, the single-session guard applies — at pid 1 or
264
+ * an init process, when a shell's command line cannot be read, when the
265
+ * process table cannot be read, or past {@link PPID_CHAIN_MAX_DEPTH}.
266
+ *
267
+ * @param ppid - Parent pid to start from.
268
+ * @param lookupProcess - Process-table reader.
269
+ * @param lookupArgs - Command-line reader.
270
+ * @param agentId - `CLEO_AGENT_ID`, when set.
271
+ * @returns The anchor, or `null`.
272
+ * @task T12864
273
+ */
274
+ export declare function resolveAncestor(ppid: number, lookupProcess: ProcessLookup, lookupArgs: ProcessArgsLookup, agentId?: string | null): AncestorAnchor | null;
129
275
  /** Interactive / script shells skipped by {@link resolveOwnerProcess}, beyond the launchers. */
130
276
  export declare const OWNER_PROCESS_SHELLS: ReadonlySet<string>;
131
277
  /** Maximum number of ancestors {@link resolveOwnerProcess} inspects. */
@@ -150,8 +296,10 @@ export declare function resolveOwnerProcess(ppid?: number, lookupProcess?: Proce
150
296
  * Resolve the calling terminal's identity keys, most specific first (T12499).
151
297
  *
152
298
  * Every {@link TERMINAL_KEY_SOURCES} row whose variable is set contributes one
153
- * key. Only when NO row matches does the ppid-chain fallback run, so the common
154
- * case (an agent harness or a mainstream terminal) never spawns `ps`.
299
+ * key. Unless a provider key is present, the ancestor walk
300
+ * ({@link resolveAncestor}) then runs: with no env key its anchor is the only
301
+ * key; under env keys an agent-level anchor (a harness, or `CLEO_AGENT_ID`) is
302
+ * appended as the most specific key. The walk is memoised per process.
155
303
  *
156
304
  * Synchronous and database-free; binding persistence and lookup live in
157
305
  * `store/session-binding-store.ts`.
@@ -1 +1 @@
1
- {"version":3,"file":"terminal-identity.d.ts","sourceRoot":"","sources":["../../src/sessions/terminal-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,uCAAuC;AACvC,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,aAAa,GAAG,UAAU,GAAG,MAAM,CAAC;AAE/E;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,eAAe,EAAE,MAAM,CAAC,CAAC;IAChD,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,iBAAiB,EA4B5D,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CAcnD,CAAC;AAEH;;;;;GAKG;AACH,OAAO,EAAE,aAAa,EAAE,CAAC;AAEzB,gEAAgE;AAChE,eAAO,MAAM,oBAAoB,EAAG,CAAU,CAAC;AAE/C,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,gFAAgF;IAChF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;CAChC;AAED,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,kBAAkB;IAClB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yBAAyB;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,6EAA6E;AAC7E,MAAM,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,eAAe,GAAG,IAAI,CAAC;AAEpE,wFAAwF;AACxF,MAAM,WAAW,0BAA0B;IACzC,uDAAuD;IACvD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;CACxC;AAWD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CA6BpE;AAsBD,gGAAgG;AAChG,eAAO,MAAM,oBAAoB,EAAE,WAAW,CAAC,MAAM,CASnD,CAAC;AAEH,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,EAAG,CAAU,CAAC;AAElD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,GAAE,MAAqB,EAC3B,aAAa,GAAE,aAAgC,GAC9C,eAAe,GAAG,IAAI,CAaxB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,GAAE,0BAA+B,GAAG,WAAW,EAAE,CA4B3F"}
1
+ {"version":3,"file":"terminal-identity.d.ts","sourceRoot":"","sources":["../../src/sessions/terminal-identity.ts"],"names":[],"mappings":"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"}