@iiiokojiadbi/shift 0.37.0 → 0.38.1

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.
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![downloads](https://img.shields.io/npm/dm/@iiiokojiadbi/shift)](https://www.npmjs.com/package/@iiiokojiadbi/shift)
5
5
  [![license](https://img.shields.io/npm/l/@iiiokojiadbi/shift)](https://github.com/iiiokojiadbi/shift/blob/main/LICENSE)
6
6
 
7
- The agent decides by itself when to **shift**. At a stage boundary it updates its work board and task folders, writes a letter to itself, and has the harness let the stretch's history go, with a direction of what to hold. Right after the shift it gets its letter, board and tasks in progress back whole and continues from where it stopped.
7
+ The agent decides by itself when to **shift**. At a stage boundary it updates its work board and task folders, writes a letter to itself, and has the harness let the stretch's history go, with a direction of what to hold. Right after the shift it gets its letter, board, open track items and recent closures back and continues from where it stopped.
8
8
 
9
9
  One package for both harnesses: pi loads `index.ts`, opencode loads `server.ts`.
10
10
 
@@ -13,7 +13,7 @@ pi install npm:@iiiokojiadbi/shift
13
13
  opencode plugin add @iiiokojiadbi/shift
14
14
  ```
15
15
 
16
- It adds a "Shift" section to the system prompt, the `shift` tool with its companions (`shift_guide`, `shift_status`, `shift_history`, `shift_setup`, `task_open`, `task_track`, `task_archive`, `doc_outline`, `docs_mentioning`), and three commands: `/shift` asks the agent to shift now, `/shift-tasks` lists the open tasks, `/unshift` picks up the last shift in a fresh session. It hints a shift as the history grows.
16
+ It adds a "Shift" section to the system prompt, the `shift` tool with its companions (`shift_guide`, `shift_status`, `shift_history`, `shift_setup`, `shift_sizes`, `task_open`, `task_track`, `task_archive`, `doc_outline`, `docs_mentioning`), and three commands: `/shift` asks the agent to shift now, `/shift-tasks` lists the open tasks, `/unshift` picks up the last shift in a fresh session. It hints a shift as the history grows.
17
17
 
18
18
  The records live in the project's `.shift/` folder and stay out of its git unless `commit = true` in `.shift/settings.toml`.
19
19
 
package/core/delivery.ts CHANGED
@@ -1,10 +1,12 @@
1
1
  // Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
2
2
  import { docStamps, followWrite, refreshDocs, settleDocs } from './docs'
3
- import { type ChangedBy, changedRecords, type Seen } from './flows'
3
+ import { type ChangedBy, type ConfirmedEdit, changedRecords, type Seen } from './flows'
4
4
  import type { GaugeKeeper } from './hint'
5
- import { MOD } from './layout'
5
+ import { DIR, MOD } from './layout'
6
6
  import { type Loop, loopHint, loopOffer, waitingNote } from './loop'
7
7
  import type { Project } from './project'
8
+ import { noteLinks } from './records'
9
+ import { readTask } from './store'
8
10
  import { NOTE_KINDS, type NoteKind } from './texts/prompts'
9
11
  import { TOLD } from './texts/rows'
10
12
 
@@ -16,19 +18,26 @@ import { TOLD } from './texts/rows'
16
18
  // What the mod last saw of the records and how many of the main agent's tools run now: a change seen while one runs
17
19
  // may be that tool's own. `written`: the files written since the docs were last settled, from the project's root.
18
20
  // `docs`: the documents' stamps as the last prompt saw them, so one a script changed is settled like one written.
19
- export type Looks = { seen: Seen | null; running: number; written?: readonly string[]; docs?: Record<string, string> }
21
+ export type Looks = {
22
+ seen: Seen | null
23
+ running: number
24
+ pendingLinks?: readonly string[]
25
+ written?: readonly string[]
26
+ docs?: Record<string, string>
27
+ }
20
28
 
21
29
  export const FRESH_LOOKS: Looks = { seen: null, running: 0 }
22
30
 
23
- export type Courier = {
24
- loop: Loop
25
- gauge: GaugeKeeper
31
+ export type RecordCourier = {
32
+ confirmedEdit?: ConfirmedEdit
26
33
  project(): Promise<Project>
27
34
  looks(): Promise<Looks>
28
35
  // A change applied to the looks as they are then.
29
36
  updateLooks(change: (current: Looks) => Looks): Promise<void>
30
37
  }
31
38
 
39
+ export type Courier = RecordCourier & { loop: Loop; gauge: GaugeKeeper }
40
+
32
41
  // A note before it goes: its kind and what it says.
33
42
  export type Note = { kind: NoteKind; body: string }
34
43
 
@@ -36,6 +45,8 @@ export type Note = { kind: NoteKind; body: string }
36
45
  export type ToolEnd = {
37
46
  // The mod's own tool: it writes the records validly, so what it wrote is only remembered.
38
47
  own: boolean
48
+ // How the adapter attributes changes without a file receipt.
49
+ recordSource?: ChangedBy
39
50
  // A tool that ran read-only changed nothing: no look after it.
40
51
  readOnly: boolean
41
52
  // The file it wrote, absolute, when it wrote one and did not fail: the docs follow it, settled with the next prompt.
@@ -47,7 +58,7 @@ export type ToolEnd = {
47
58
  // Of tools started together only the first looks: the count is claimed in one change, so two never tell the same change.
48
59
  // What it saw is kept at once: a tool that throws loses its note, which only a failing harness does, while a look kept
49
60
  // open would let a sibling tool take the change as its own or put back what it saw.
50
- export async function beforeTool(courier: Courier): Promise<Note[]> {
61
+ export async function beforeTool(courier: RecordCourier): Promise<Note[]> {
51
62
  const claim: { first?: boolean } = {}
52
63
  await courier.updateLooks(current => {
53
64
  claim.first = current.running === 0
@@ -64,17 +75,23 @@ export async function beforeTool(courier: Courier): Promise<Note[]> {
64
75
  // After a tool of the main agent: the notes from before it, what it changed in the records, and a hint if the fill
65
76
  // calls for one — wrapped, each told to the owner as it goes into the result. A file it wrote is only followed.
66
77
  export async function afterTool(courier: Courier, before: readonly Note[], done: ToolEnd | null): Promise<string[]> {
78
+ const notes = await afterToolRecords(courier, before, done)
79
+ if (done === null) return []
80
+ const hint = await loopHint(courier.loop, courier.gauge).catch(() => null)
81
+ if (hint !== null) notes.push({ kind: 'hint', body: hint })
82
+
83
+ return deliver(courier.loop, notes)
84
+ }
85
+
86
+ export async function afterToolRecords(courier: RecordCourier, before: readonly Note[], done: ToolEnd | null): Promise<Note[]> {
67
87
  await courier.updateLooks(current => ({ ...current, running: Math.max(0, current.running - 1) }))
68
88
  if (done === null) return []
69
89
  const notes = [...before]
70
- const own = done.readOnly ? null : await look(courier, 'agent')
90
+ const own = done.readOnly ? null : await look(courier, done.recordSource ?? 'agent')
71
91
  if (own !== null) await remember(courier, own.seen)
72
92
  if (own?.body != null && !done.own) notes.push({ kind: 'records', body: own.body })
73
93
  if (done.written !== undefined) await follow(courier, done.written)
74
- const hint = await loopHint(courier.loop, courier.gauge).catch(() => null)
75
- if (hint !== null) notes.push({ kind: 'hint', body: hint })
76
-
77
- return deliver(courier.loop, notes)
94
+ return notes
78
95
  }
79
96
 
80
97
  // A file written by a subagent: the docs follow it, settled with the main agent's next prompt.
@@ -90,6 +107,24 @@ export async function atPrompt(
90
107
  courier: Courier,
91
108
  { runStarts, owner }: { runStarts: boolean; owner: boolean },
92
109
  ): Promise<{ notes: string[]; delivered(): Promise<void> }> {
110
+ const records = await promptRecords(courier, runStarts)
111
+ const notes = records.notes
112
+ const hint = await loopOffer(courier.loop, courier.gauge).catch(() => null)
113
+ if (hint !== null) notes.push({ kind: 'hint', body: hint.text })
114
+ const letter = owner ? await waitingNote(courier.loop) : null
115
+
116
+ return {
117
+ notes: [...notes.map(wrap), ...(letter === null ? [] : [letter.context])],
118
+ delivered: async () => {
119
+ await records.delivered()
120
+ await hint?.take()
121
+ for (const note of notes) courier.loop.tell(TOLD(note.body), 'info')
122
+ await letter?.delivered()
123
+ },
124
+ }
125
+ }
126
+
127
+ export async function promptRecords(courier: RecordCourier, runStarts: boolean) {
93
128
  if (runStarts) await courier.updateLooks(current => ({ ...current, running: 0 }))
94
129
  const notes: Note[] = []
95
130
  const { running } = await courier.looks()
@@ -97,16 +132,22 @@ export async function atPrompt(
97
132
  const outside = running === 0 ? await look(courier, 'other') : null
98
133
  if (outside?.body === null) await remember(courier, outside.seen)
99
134
  if (outside?.body != null) notes.push({ kind: 'records', body: outside.body })
135
+ const pending = running === 0 ? ((await courier.looks()).pendingLinks ?? []) : []
136
+ if (pending.length) {
137
+ const project = await courier.project()
138
+ const problems = await Promise.all(pending.map(async name => noteLinks(await readTask(project.store, `${project.root}/${DIR}`, name))))
139
+ const body = problems.filter(Boolean).join('\n')
140
+ if (body) notes.push({ kind: 'records', body })
141
+ else await courier.updateLooks(now => ({ ...now, pendingLinks: now.pendingLinks?.filter(name => !pending.includes(name)) }))
142
+ }
100
143
  if (running === 0) await scripted(courier)
101
144
  const docs = running === 0 ? await settle(courier) : null
102
145
  if (docs !== null) notes.push({ kind: 'docs', body: docs.body })
103
- const hint = await loopOffer(courier.loop, courier.gauge).catch(() => null)
104
- if (hint !== null) notes.push({ kind: 'hint', body: hint.text })
105
- const letter = owner ? await waitingNote(courier.loop) : null
106
-
107
146
  return {
108
- notes: [...notes.map(wrap), ...(letter === null ? [] : [letter.context])],
147
+ notes,
109
148
  delivered: async () => {
149
+ if (pending.length)
150
+ await courier.updateLooks(now => ({ ...now, pendingLinks: now.pendingLinks?.filter(name => !pending.includes(name)) }))
110
151
  // Kept unless a look since has kept newer records: putting back the older ones would tell their change again.
111
152
  if (outside?.body != null)
112
153
  await courier.updateLooks(current => (same(current.seen, seen) ? { ...current, seen: outside.seen } : current))
@@ -116,9 +157,6 @@ export async function atPrompt(
116
157
  await forget(courier, settled)
117
158
  await restamp(courier, settled)
118
159
  }
119
- await hint?.take()
120
- for (const note of notes) courier.loop.tell(TOLD(note.body), 'info')
121
- await letter?.delivered()
122
160
  },
123
161
  }
124
162
  }
@@ -130,20 +168,25 @@ export async function runEnded(courier: Courier): Promise<void> {
130
168
 
131
169
  // The records changed since the last look and what they are now, kept by `remember`; the first look finds nothing to
132
170
  // tell. A look that fails says nothing: it must never stand between the agent and its tool.
133
- async function look(courier: Courier, by: ChangedBy): Promise<{ body: string | null; seen: Seen } | null> {
171
+ async function look(courier: RecordCourier, by: ChangedBy): Promise<{ body: string | null; seen: Seen } | null> {
134
172
  try {
135
- return await changedRecords(await courier.project(), (await courier.looks()).seen, by)
173
+ const tasks = new Set<string>()
174
+ const result = await changedRecords(await courier.project(), (await courier.looks()).seen, by, courier.confirmedEdit, name =>
175
+ tasks.add(name),
176
+ )
177
+ if (tasks.size) await courier.updateLooks(now => ({ ...now, pendingLinks: [...new Set([...(now.pendingLinks ?? []), ...tasks])] }))
178
+ return result
136
179
  } catch {
137
180
  return null
138
181
  }
139
182
  }
140
183
 
141
- async function remember(courier: Courier, seen: Seen): Promise<void> {
184
+ async function remember(courier: RecordCourier, seen: Seen): Promise<void> {
142
185
  await courier.updateLooks(current => ({ ...current, seen }))
143
186
  }
144
187
 
145
188
  // A written file the docs follow is remembered for the next prompt; the map follows a document at once.
146
- async function follow(courier: Courier, file: string): Promise<void> {
189
+ async function follow(courier: RecordCourier, file: string): Promise<void> {
147
190
  const path = await followWrite(await courier.project(), file).catch(() => null)
148
191
  if (path === null) return
149
192
  await courier.updateLooks(current =>
@@ -153,7 +196,9 @@ async function follow(courier: Courier, file: string): Promise<void> {
153
196
 
154
197
  // The files written since the last settling, settled now and forgotten once told; a settling that fails says nothing.
155
198
  // Nothing to tell is settled and forgotten at once: an adapter calls `delivered` only when a note goes.
156
- async function settle(courier: Courier): Promise<{ body: string; paths: readonly string[]; write(): Promise<readonly string[]> } | null> {
199
+ async function settle(
200
+ courier: RecordCourier,
201
+ ): Promise<{ body: string; paths: readonly string[]; write(): Promise<readonly string[]> } | null> {
157
202
  const written = (await courier.looks()).written ?? []
158
203
  if (written.length === 0) return null
159
204
  const settled = await settleDocs(await courier.project(), written).catch(() => null)
@@ -168,7 +213,7 @@ async function settle(courier: Courier): Promise<{ body: string; paths: readonly
168
213
 
169
214
  // The documents changed since the last prompt that no write of the agent's tools named — a script, a command — are
170
215
  // taken as written, and the map follows them. The first look only remembers: there is nothing to compare with yet.
171
- async function scripted(courier: Courier): Promise<void> {
216
+ async function scripted(courier: RecordCourier): Promise<void> {
172
217
  try {
173
218
  const project = await courier.project()
174
219
  const now = await docStamps(project)
@@ -190,7 +235,7 @@ async function scripted(courier: Courier): Promise<void> {
190
235
  }
191
236
 
192
237
  // A document settled is remembered as it is now, the toc the mod wrote included, so it is not taken for a script's change.
193
- async function restamp(courier: Courier, paths: readonly string[]): Promise<void> {
238
+ async function restamp(courier: RecordCourier, paths: readonly string[]): Promise<void> {
194
239
  if (paths.length === 0) return
195
240
  const now = await docStamps(await courier.project()).catch(() => null)
196
241
  if (now === null) return
@@ -210,7 +255,7 @@ function same(a: Seen | null, b: Seen | null): boolean {
210
255
  return JSON.stringify(a) === JSON.stringify(b)
211
256
  }
212
257
 
213
- async function forget(courier: Courier, paths: readonly string[]): Promise<void> {
258
+ async function forget(courier: RecordCourier, paths: readonly string[]): Promise<void> {
214
259
  await courier.updateLooks(current => ({ ...current, written: (current.written ?? []).filter(path => !paths.includes(path)) }))
215
260
  }
216
261
 
package/core/docs.ts CHANGED
@@ -400,8 +400,15 @@ export function withMap(shift: string | null, map: string): string {
400
400
  if (shift === null) {
401
401
  return `# Shift\n\nHow this project keeps its knowledge. The rules are written on the owner's word; the map below is the mod's.\n\n${map}\n`
402
402
  }
403
- // The markers on lines of their own, outside code fences: a sentence or an example that names them is the owner's.
404
403
  const lines = shift.split('\n')
404
+ const { start, end } = mapBounds(lines)
405
+ if (end === -1) return `${shift.trimEnd()}\n\n${map}\n`
406
+
407
+ return [...lines.slice(0, start), map, ...lines.slice(end + 1)].join('\n')
408
+ }
409
+
410
+ export function mapBounds(lines: readonly string[]) {
411
+ // The markers on lines of their own, outside code fences: a sentence or an example that names them is the owner's.
405
412
  // The opener as any version of the mod wrote it: one comment, the whole line, that starts as the mod's does.
406
413
  const opener = `${MAP_START.slice(0, MAP_START.indexOf(' — '))} — `
407
414
  const start = lineOutside(lines, line => {
@@ -409,9 +416,25 @@ export function withMap(shift: string | null, map: string): string {
409
416
  return trimmed.startsWith(opener) && trimmed.indexOf('-->') === trimmed.length - 3
410
417
  })
411
418
  const end = start === -1 ? -1 : lineOutside(lines, line => line.trim() === MAP_END, start + 1)
412
- if (end === -1) return `${shift.trimEnd()}\n\n${map}\n`
419
+ return { start, end }
420
+ }
413
421
 
414
- return [...lines.slice(0, start), map, ...lines.slice(end + 1)].join('\n')
422
+ // Group the rendered map by its actual entries, including the sections and pins under each.
423
+ // A reduced map uses folder entries. Rules and map-level notices can be refreshed by path.
424
+ export function mapParts(text: string) {
425
+ const lines = text.split('\n')
426
+ const { start, end } = mapBounds(lines)
427
+ const entries = new Map<string, string>()
428
+ if (end < 0) return { other: '', entries }
429
+ const other: string[] = []
430
+ let key: string | undefined
431
+ for (const line of lines.slice(start + 1, end)) {
432
+ if (!line.trim() || line.startsWith('### ')) continue
433
+ if (!line.startsWith(' ')) key = /^- `([^`]+)`/.exec(line)?.[1]
434
+ if (!key) other.push(line)
435
+ else entries.set(key, entries.has(key) ? `${entries.get(key)}\n${line}` : line)
436
+ }
437
+ return { other: other.join('\n'), entries }
415
438
  }
416
439
 
417
440
  // Every document read once: its toc rewritten when the settings ask for one, then the map in SHIFT.md written when it
package/core/flows.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  // Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
2
2
  import { OUTCOME, readAbout, renderAbout, shiftFill } from './about'
3
3
  import { addToIndex, checkArchive, indexLine } from './archive'
4
- import { docsReport, refreshDocs } from './docs'
4
+ import { docsReport, isDoc, refreshDocs, withMap, withToc } from './docs'
5
5
  import { renderHistory, renderSummary, segment, shiftDir } from './history'
6
6
  import {
7
7
  ARCHIVE,
@@ -25,7 +25,7 @@ import {
25
25
  TRACK_TOOL,
26
26
  taskFile,
27
27
  } from './layout'
28
- import { formatItem, formatK, itemsOf, sections } from './markdown'
28
+ import { formatItem, formatK, itemsOf, sections, trackTimes } from './markdown'
29
29
  import { basename, dirname, join, resolvePath } from './paths'
30
30
  import type { Project } from './project'
31
31
  import { checkLetter, checkTask, checkWork, checkWritten, listedTasks } from './records'
@@ -44,7 +44,19 @@ import {
44
44
  } from './texts/prompts'
45
45
  import { CONTINUING, NOT_MADE, renderTasks, type TaskView, UNSETTLED, WAITING } from './texts/rows'
46
46
  import { numberTracks } from './track'
47
- import type { ArchiveInput, HandedBack, OpenInput, PendingShift, SessionFile, Settled, ShiftInput, Stuck, TaskFiles, Work } from './types'
47
+ import type {
48
+ ArchiveInput,
49
+ HandedBack,
50
+ OpenInput,
51
+ PendingShift,
52
+ SessionFile,
53
+ Settled,
54
+ ShiftInput,
55
+ Stuck,
56
+ TaskFiles,
57
+ WaitNote,
58
+ Work,
59
+ } from './types'
48
60
 
49
61
  // The flows that do not depend on the harness: an adapter hands them the loaded project and what only it knows.
50
62
 
@@ -60,15 +72,30 @@ export type ChangedBy = 'agent' | 'other'
60
72
 
61
73
  // The records changed since the mod last looked, each checked by the checks of its file, so what the shift would refuse
62
74
  // is told as it is written, not hundreds of K later. The agent's own change is told only when broken; someone else's
63
- // is told always, so the agent reads it before writing over it. The first look only remembers; a removed file is the
64
- // shift's to tell.
65
- export async function changedRecords(project: Project, seen: Seen | null, by: ChangedBy): Promise<{ seen: Seen; body: string | null }> {
75
+ // is told always, so the agent reads it before writing over it. The first look only remembers. Generated map and toc changes have their own delivery slot.
76
+ export type ConfirmedEdit = (path: string, current: string | null, previous: string | undefined) => boolean
77
+
78
+ export function recordFingerprint(project: Project, path: string, text: string): string {
79
+ let observed = text
80
+ if (path === project.settings.files.shift) observed = withMap(text, '').trim()
81
+ else if (project.settings.docs.toc && isDoc(path, project.settings.docs.dirs)) observed = withToc(text) ?? text
82
+ return String(fingerprint(observed))
83
+ }
84
+
85
+ export async function changedRecords(
86
+ project: Project,
87
+ seen: Seen | null,
88
+ by: ChangedBy,
89
+ confirmed?: ConfirmedEdit,
90
+ deferLinks?: (name: string) => void,
91
+ ): Promise<{ seen: Seen; body: string | null }> {
66
92
  if (!project.settings.enabled) return { seen: seen ?? {}, body: null }
67
93
  // A new stamp alone is not a change: a file rewritten with the same text, or edited and put back, says nothing.
68
- const now: Seen = {}
94
+ const now: Seen = Object.create(null)
69
95
  const changed: string[] = []
96
+ const external = new Set<string>()
70
97
  for (const [path, stamp] of Object.entries(await recordStamps(project))) {
71
- const was = seen?.[path] ?? ''
98
+ const was = seen && Object.hasOwn(seen, path) ? (seen[path] ?? '') : ''
72
99
  const at = was.lastIndexOf('#')
73
100
  if (at !== -1 && was.slice(0, at) === stamp) {
74
101
  now[path] = was
@@ -76,19 +103,33 @@ export async function changedRecords(project: Project, seen: Seen | null, by: Ch
76
103
  }
77
104
  const text = await project.store.read(`${project.root}/${path}`)
78
105
  if (text === null) continue
79
- const hash = String(fingerprint(text))
106
+ const hash = recordFingerprint(project, path, text)
80
107
  now[path] = `${stamp}#${hash}`
81
- if (seen !== null && was.slice(at + 1) !== hash) changed.push(path)
108
+ const generated = !was && path === project.settings.files.shift && withMap(text, '').trim() === withMap(null, '').trim()
109
+ if (seen !== null && was.slice(at + 1) !== hash && !generated) {
110
+ changed.push(path)
111
+ if (by === 'other' && !confirmed?.(path, text, was ? was.slice(at + 1) : undefined)) external.add(path)
112
+ }
113
+ }
114
+ const lines: string[] = []
115
+ if (by === 'other' && seen) {
116
+ for (const path of Object.keys(seen))
117
+ if (
118
+ !(path in now) &&
119
+ !(await project.store.exists(`${project.root}/${path}`)) &&
120
+ !confirmed?.(path, null, seen[path]?.split('#').pop())
121
+ )
122
+ lines.push(`\`${path}\` was removed outside your tools.`)
82
123
  }
83
- if (changed.length === 0) return { seen: now, body: null }
124
+ if (changed.length === 0) return { seen: now, body: lines.join('\n') || null }
84
125
 
85
126
  const work = await readRecords(project)
86
- const lines: string[] = []
87
127
  let broken = false
88
128
  for (const path of changed) {
89
- const problem = path === LETTER ? await letterProblem(project) : work === null ? null : checkWritten(path, work, project)
129
+ const problem = path === LETTER ? await letterProblem(project) : work === null ? null : checkWritten(path, work, project, deferLinks)
90
130
  broken ||= problem !== null
91
- if (by === 'other') lines.push(`\`${path}\` changed outside your tools — by the owner or another session: read it before you write it.`)
131
+ if (external.has(path))
132
+ lines.push(`\`${path}\` changed outside your tools — by the owner or another session: read it before you write it.`)
92
133
  if (problem !== null) lines.push(`\`${path}\`: ${problem}`)
93
134
  }
94
135
  if (broken) lines.push('The shift refuses until they are fixed; if you are still writing them, go on.')
@@ -102,15 +143,22 @@ async function recordStamps({ store, root, settings }: Project): Promise<Seen> {
102
143
  const stamped = async (dir: string, only?: (name: string) => boolean): Promise<Seen> =>
103
144
  Object.fromEntries(
104
145
  Object.entries(await store.stamps(join(root, dir)))
105
- .filter(([name]) => (name.endsWith('.md') || join(dir, name) === SETTINGS) && (only?.(name) ?? true))
146
+ .filter(([name]) => (only ? only(name) : name.endsWith('.md')))
106
147
  .map(([name, stamp]) => [join(dir, name), stamp]),
107
148
  )
108
- const own = new Set([BOARD, TASK_LIST, LETTER, SETTINGS, settings.files.owner, settings.files.glossary])
149
+ const own = new Set([
150
+ BOARD,
151
+ TASK_LIST,
152
+ LETTER,
153
+ SETTINGS,
154
+ settings.files.owner,
155
+ settings.files.glossary,
156
+ settings.files.shift,
157
+ ...settings.files.always,
158
+ ])
109
159
  const tasks = await store.list(`${root}/${TASKS}`, 'dir')
110
160
  const parts = await Promise.all([
111
- ...[...new Set([DIR, dirname(settings.files.owner), dirname(settings.files.glossary)])].map(dir =>
112
- stamped(dir, name => own.has(join(dir, name))),
113
- ),
161
+ ...[...new Set([...own].map(dirname))].map(dir => stamped(dir, name => own.has(join(dir, name)))),
114
162
  ...tasks.flatMap(name => [
115
163
  stamped(`${TASKS}/${name}`, file => file === NAMES.task || file === NAMES.track),
116
164
  stamped(`${TASKS}/${name}/${NAMES.notes}`),
@@ -229,17 +277,22 @@ function knowledgeText(work: Work): string {
229
277
  // Moves a finished or dropped task's folder to the archive and adds its line to the index.
230
278
  // A task opened valid by construction: task.md by its sections, track.md with its first items, and its line with the
231
279
  // links in TASKS.md — all checked before anything is written, so a refusal leaves the records as they were.
232
- export async function openTask(project: Project, input: OpenInput): Promise<{ deny: string } | { result: string }> {
280
+ export async function openTask(
281
+ project: Project,
282
+ input: OpenInput,
283
+ now: number | null = null,
284
+ ): Promise<{ deny: string } | { result: string }> {
233
285
  const { store, root } = project
234
286
  const folder = `${root}/${TASKS}/${input.name}`
235
287
  if (await store.exists(folder)) return { deny: `${TASKS}/${input.name}/ already exists: set its status with ${TRACK_TOOL}.` }
236
288
  const archived = await store.list(`${root}/${ARCHIVE}`, 'dir')
237
289
  if (archived.includes(input.name))
238
290
  return { deny: `${input.name} is archived: open a task under another name with continues: ${input.name}.` }
291
+ const initial = input.items.map((item, n) => formatItem('open', n + 1, item.name, item.note))
239
292
  const task: TaskFiles = {
240
293
  name: input.name,
241
294
  task: renderTask(input),
242
- track: input.items.map((item, n) => `${formatItem('open', n + 1, item.name, item.note)}\n`).join(''),
295
+ track: initial.map(line => `${line + trackTimes(now, null)}\n`).join(''),
243
296
  notes: [],
244
297
  }
245
298
  const listPath = `${root}/${TASK_LIST}`
@@ -252,7 +305,7 @@ export async function openTask(project: Project, input: OpenInput): Promise<{ de
252
305
  await store.write(`${folder}/${NAMES.track}`, task.track ?? '')
253
306
  await store.write(listPath, list)
254
307
 
255
- return { result: OPENED(input.name, formatTaskLine(input.status, input.name, input.name, input.about), task.track ?? '') }
308
+ return { result: OPENED(input.name, formatTaskLine(input.status, input.name, input.name, input.about), initial.join('\n')) }
256
309
  }
257
310
 
258
311
  function renderTask(input: OpenInput): string {
@@ -385,6 +438,7 @@ async function recordFailure(project: Project, shift: PendingShift, about: strin
385
438
 
386
439
  export type LetGo = {
387
440
  shift: PendingShift
441
+ parkWait?(note: WaitNote): Promise<void>
388
442
  // What the history was let go into, as the harness gives it back.
389
443
  messages: readonly { role: string; text: string }[]
390
444
  before: number | undefined
@@ -415,8 +469,10 @@ export async function settleShift(project: Project, letGo: LetGo, back?: HandedB
415
469
  return { after: 'continue', prompt, note: { context: prompt, dir: shift.dir, files }, row: CONTINUING(name, shrank, shift.dir) }
416
470
  }
417
471
 
418
- await outcome(OUTCOME.waiting(shrank, 'waiting for the owner'))
419
472
  const note = { context: waitContext(shift.letter, handed), dir: shift.dir, files }
473
+ // Publish the waiting outcome only once a harness with durable thread history has parked the letter.
474
+ await letGo.parkWait?.(note)
475
+ await outcome(OUTCOME.waiting(shrank, 'waiting for the owner'))
420
476
 
421
477
  return { after: 'wait', note, row: WAITING(name, shrank) }
422
478
  }
@@ -461,7 +517,7 @@ export async function sessionFiles(project: Project, { refresh = true }: { refre
461
517
  const { store, root, settings } = project
462
518
  if (!settings.enabled || (await staleLayout(project)) !== null) return []
463
519
  if (refresh) await refreshDocs(project)
464
- const paths = [settings.files.shift, settings.files.owner, settings.files.glossary, TASK_LIST, ...settings.files.always]
520
+ const paths = [...new Set([settings.files.shift, settings.files.owner, settings.files.glossary, TASK_LIST, ...settings.files.always])]
465
521
  const files = await Promise.all(paths.map(async path => ({ path, text: await store.read(`${root}/${path}`) })))
466
522
 
467
523
  return files.filter((file): file is SessionFile => file.text !== null)
package/core/hint.ts CHANGED
@@ -1,22 +1,28 @@
1
1
  // Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
2
2
  import { BOARD, TASK_LIST, TASKS, TOOL } from './layout'
3
3
  import { formatK } from './markdown'
4
- import type { Gauge, Reading } from './types'
4
+ import type { Gauge, HintTargets, Reading } from './types'
5
5
 
6
- // Every step is a share of the limit — the harness's own threshold, or the window when it is unknown — so the rhythm is the same on any window.
7
- // Soft hints come every max(150K, 40%) of growth: a shorter stretch does not pay for its letter, its records and the cache
8
- // built anew after it. On a small window the step does not fit before the final hint, so the final one is the only one.
9
- export function softStep(limit: number): number {
10
- return Math.max(150_000, Math.round(limit * 0.4))
6
+ // A stretch needs enough new work to justify the cost of a voluntary shift.
7
+ function nextSoft(base: number, tokens: number, limit: number, targets: HintTargets): number | null {
8
+ if (targets.soft === null) return null
9
+ const at = Math.max(tokens, targets.soft, base + 200_000)
10
+ return at + Math.round(limit * 0.1) <= targets.final ? at : null
11
11
  }
12
12
 
13
- // The final hint comes at 80% of the limit, with room left to finish a stage, and again every 5% after it.
14
13
  export function finalAt(limit: number): number {
15
- return Math.round(limit * 0.8)
14
+ return Math.round(limit * 0.84)
16
15
  }
17
16
 
18
- export function finalStep(limit: number): number {
19
- return Math.round(limit / 20)
17
+ function hintTargets(limit: number, overrides?: HintTargets): HintTargets {
18
+ return overrides ?? { soft: Math.round(limit * 0.6), final: finalAt(limit) }
19
+ }
20
+
21
+ // Give a new stretch some room even when the previous shift left a full history.
22
+ function firstFinal(base: number, limit: number, final: number): number {
23
+ if (base < final) return final
24
+ const growth = Math.min(limit * 0.05, (limit - base) / 2)
25
+ return base + Math.max(1, Math.round(growth))
20
26
  }
21
27
 
22
28
  export const FRESH_GAUGE: Gauge = { base: null, hinted: null, unassisted: false, growth: {}, whole: false }
@@ -35,36 +41,33 @@ function rebased(gauge: Gauge, tokens: number): Gauge {
35
41
  return gauge.base !== null && tokens < (gauge.hinted ?? gauge.base) ? { ...gauge, base: tokens, hinted: null, growth: {} } : gauge
36
42
  }
37
43
 
38
- // One hint at most per new growth; an ignored one is not repeated until the history grows again.
39
- export function shiftHint(current: Gauge, { tokens, window, threshold }: Reading): { gauge: Gauge; text: string | null } {
44
+ // A reading that crosses both milestones gives only the final hint.
45
+ export function shiftHint(
46
+ current: Gauge,
47
+ { tokens, window, threshold, hintTargets: overrides }: Reading,
48
+ ): { gauge: Gauge; text: string | null } {
40
49
  if (tokens === undefined) return { gauge: current, text: null }
41
50
  const gauge = rebased(current, tokens)
42
51
  if (gauge.base === null) return { gauge: { ...gauge, base: tokens, unassisted: false }, text: gauge.unassisted ? UNASSISTED_HINT : null }
43
52
 
44
53
  const limit = threshold ?? window
45
- const final = finalAt(limit)
46
- const grown = tokens - gauge.base
47
- const since = tokens - (gauge.hinted ?? gauge.base)
54
+ const targets = hintTargets(limit, overrides)
48
55
  const hinted = { ...gauge, hinted: tokens }
49
- if (grown < finalStep(limit)) return { gauge, text: null }
56
+ if (tokens >= firstFinal(gauge.base, limit, targets.final) && (gauge.hinted === null || gauge.hinted < targets.final))
57
+ return { gauge: hinted, text: finalHint(tokens, limit, gauge.growth) }
50
58
 
51
- if (tokens >= final) {
52
- const isFirst = gauge.hinted === null || gauge.hinted < final
53
- return isFirst || since >= finalStep(limit) ? { gauge: hinted, text: finalHint(tokens, limit, gauge.growth) } : { gauge, text: null }
54
- }
55
- // No soft hint right before the final one: it would come twice in a row.
56
- const step = softStep(limit)
57
- if (since >= step && tokens + step / 2 <= final) return { gauge: hinted, text: softHint(grown, gauge.growth) }
59
+ if (gauge.hinted === null && nextSoft(gauge.base, tokens, limit, targets) === tokens)
60
+ return { gauge: hinted, text: softHint(tokens - gauge.base, gauge.growth) }
58
61
 
59
62
  return { gauge, text: null }
60
63
  }
61
64
 
62
65
  function softHint(grown: number, growth: Record<string, number>): string {
63
- return `Shift hint: the history has grown by ${formatK(grown)} since the last shift.${sources(growth)} This is not an alarm — running out of room gets a hint of its own. If you are at a stage boundary and the stretch's history is not needed whole any more, shift; if not, go on — the next hint comes after new growth.`
66
+ return `Shift hint: the history has grown by ${formatK(grown)} since the last shift.${sources(growth)} This is not an alarm — running out of room gets a hint of its own. If you are at a stage boundary and the stretch's history is not needed whole any more, shift; otherwise keep working.`
64
67
  }
65
68
 
66
69
  function finalHint(tokens: number, limit: number, growth: Record<string, number>): string {
67
- return `Shift hint: ${formatK(tokens)} of ${formatK(limit)} used — close to the point where the harness lets the history go by itself, without your letter.${sources(growth)} Shift at the nearest stage boundary: board, tasks, letter, \`${TOOL}\`.`
70
+ return `Shift hint: ${formatK(tokens)} of ${formatK(limit)} used — close to the point where the harness lets the history go by itself, without your letter.${sources(growth)} Shift now. Check the records, write your letter and call \`${TOOL}\`.`
68
71
  }
69
72
 
70
73
  // Token counts per row are not known, so the growth is counted in characters and named by shares.
@@ -134,20 +137,21 @@ export function growthOf(messages: readonly { role: string; content: unknown }[]
134
137
  }
135
138
 
136
139
  // What the status tool answers: the fill, the limit, the growth since the last shift, when the next hints come, and what grew.
137
- export function renderStatus(current: Gauge, { tokens, window, threshold }: Reading): string {
140
+ export function renderStatus(current: Gauge, { tokens, window, threshold, hintTargets: overrides }: Reading): string {
138
141
  if (tokens === undefined) return 'No reading yet: the first response since the last let-go has not come back.'
139
142
  const gauge = rebased(current, tokens)
140
143
  const limit = threshold ?? window
141
- const final = finalAt(limit)
144
+ const targets = hintTargets(limit, overrides)
145
+ const base = gauge.base ?? tokens
146
+ const final = firstFinal(base, limit, targets.final)
142
147
  const lines = [
143
- `Used: ${formatK(tokens)} of ${formatK(window)} window; ${threshold === undefined ? 'the harness lets nothing go by itself, or its threshold is not read yet: the window stands for it' : `the harness lets the history go by itself at ${formatK(threshold)}`}.`,
148
+ `Used: ${formatK(tokens)} of ${formatK(window)} window; ${threshold === undefined ? 'the automatic threshold is unknown' : `the harness lets the history go by itself at ${formatK(threshold)}`}.`,
144
149
  ]
145
150
  if (gauge.base !== null) lines.push(`Since the last shift: +${formatK(Math.max(0, tokens - gauge.base))}.`)
146
- if (tokens >= final) lines.push(`Past the final hint at ${formatK(final)}: shift at the nearest stage boundary.`)
151
+ if (tokens >= final) lines.push(`Past the final hint at ${formatK(final)}: shift now.`)
147
152
  else {
148
- const step = softStep(limit)
149
- const soft = Math.max(tokens, (gauge.hinted ?? gauge.base ?? tokens) + step)
150
- const next = soft + step / 2 <= final ? `next soft hint at ${formatK(soft)}` : 'no soft hint before the final'
153
+ const soft = gauge.hinted === null ? nextSoft(base, tokens, limit, targets) : null
154
+ const next = soft === null ? 'no soft hint before the final' : `next soft hint at ${formatK(soft)}`
151
155
  lines.push(`Hints: ${next}; final at ${formatK(final)}.`)
152
156
  }
153
157
  const shares = growthShares(gauge.growth)
@@ -282,16 +286,12 @@ async function restore(keeper: GaugeKeeper): Promise<void> {
282
286
  })
283
287
  }
284
288
 
285
- // The last step the history has passed since the base: its hint was given before the restart, so it is not repeated,
286
- // and the next step still hints. Past the final the hint is taken as given now: the final repeats every 5%, and a step
287
- // placed below the real one would repeat it at once.
288
- export function lastStep(base: number | null, { tokens, window, threshold }: Reading): number | null {
289
+ // On restore, infer the milestones already passed in this stretch.
290
+ export function lastStep(base: number | null, { tokens, window, threshold, hintTargets: overrides }: Reading): number | null {
289
291
  if (base === null || tokens === undefined || tokens < base) return null
290
292
  const limit = threshold ?? window
291
- const final = finalAt(limit)
292
- if (tokens >= final) return tokens
293
- const step = softStep(limit)
294
- const passed = Math.floor((tokens - base) / step)
295
-
296
- return passed > 0 ? base + passed * step : null
293
+ const targets = hintTargets(limit, overrides)
294
+ if (tokens >= firstFinal(base, limit, targets.final)) return tokens
295
+ const soft = nextSoft(base, base, limit, targets)
296
+ return soft !== null && tokens >= soft ? soft : null
297
297
  }
package/core/index.ts CHANGED
@@ -15,6 +15,7 @@ export * from './project'
15
15
  export * from './records'
16
16
  export * from './settings'
17
17
  export * from './setup'
18
+ export * from './sizes'
18
19
  export * from './store'
19
20
  export * from './texts/doctrine'
20
21
  export * from './texts/prompts'