create-pmos 0.52.0 → 0.53.1

package/workspace/guide/proactive-engine.md

@@ -1,20 +1,35 @@
 ---
 type: Guide
 title: "Guide: Today and the proactive engine"
-description: "What the Today item shows, how the morning brief is made, and how the workspace works out what is waiting for you."
-timestamp: 2026-10-04
+description: "What the Today item shows, how your goals for the day are prepared, how the morning brief is made, and how the workspace works out what is waiting for you."
+timestamp: 2026-10-06
 ---
 
 # Guide: Today and the proactive engine
 
 The today item shows what is waiting for you now. The workspace works it out by itself from the records of your repositories. You do not ask for it.
 
+## Goals for today
+
+At the top of Today you can list what you want done today. A goal is one line of text, and it can name an initiative.
+
+- Open **Goals for today** and type a goal. Press Enter to add it. A day has at most 7 goals, each at most 140 characters.
+- Press **Done**, **Drop**, **Reopen** or **Remove** on a goal. A goal is open, done or dropped.
+- Press **Prepare my day**. The workspace makes the daily 06:45 morning-brief schedule if this repository has none, and runs it now. The session reads your goals, your calendar, and the mentions of you in Slack, Jira and Confluence. It ties each meeting, mention and step that moves a goal to that goal.
+- Each goal shows its steps: yours first, then the agent's. A step comes from the brief, or from a Today card on the goal's initiative. A goal with no step says so. The session does not invent a step.
+- A step is under a goal only when the brief names the goal, or when the step and the goal name the same initiative. The workspace never matches words.
+- An agent step that names an initiative has **Prepare**. It shows the step, the branch and the prompt, the same as background preparation. **Queue it** approves that exact prompt. Background preparation must be on in the settings. Otherwise the queue says so and nothing is queued.
+- What fits no goal is listed under **Also on your plate**, and items the session is less than 0.5 sure about under **Worth asking**.
+- Today also says how much free time you have until 18:00, the event coming up, and which sources were not read.
+- If the brief is for another day, it is not used. Only the Today cards are shown under the goals.
+- The goals are stored in the workspace state folder on this computer, one file for each day (`goals/<date>.json`). They are not committed.
+
 ## The morning brief
 
 The top of Today is the morning brief: a greeting, the day's calendar, the priorities and a list of things worth asking about. The brief is not computed by the workspace. A skill called morning-brief runs in an agent session. The session reads the sources, and then submits one brief with `pmos proactive brief submit`. The workspace server only checks the brief and stores it. It makes no model call and reaches no calendar or mailbox.
 
 - Press **schedule the morning brief** in Today to make a daily schedule at 06:45. The schedule is an ordinary scheduled task, so it runs only while the workspace server runs. A sleeping computer gets no brief. A schedule that is made after its time of day for the first time runs within a minute, so pressing the button at 10:00 starts one brief session straight away.
-- Each source is a setting: calendar, wispr, mail, jira and confluence. Mail is off by default and the skill reads only subjects and senders, never bodies. A source that is off cannot be reported as read.
+- Each source is a setting: calendar, wispr, mail, slack, jira and confluence. Mail is off by default and the skill reads only subjects and senders, never bodies. Slack is on by default. In Slack, Jira and Confluence the skill reads the mentions of you: where, who, and a one-line summary. It never copies a message. A source that is off cannot be reported as read.
 - The brief names the day it is for. If that is not today, Today says it is out of date.
 - An item the session is less than 0.5 sure about is shown under worth asking, not as a priority. The workspace sets that bucket from the confidence. The session cannot choose it.
 - The order is fixed: higher confidence first, then your items before the agent's, then by title.
@@ -85,7 +100,7 @@ A verdict never changes a status, a lifecycle record or an acceptance. It is rec
 |---|---|
 | engine on | Off stops automatic scans. The scan now button still works. |
 | watch: needs, returned, review, schedule, stalled | Turn one trigger off. |
-| brief sources | One switch for each of calendar, wispr, mail, jira and confluence. |
+| brief sources | One switch for each of calendar, wispr, mail, slack, jira and confluence. |
 | background prepare | Off by default. On lets the workspace start a session for a plan you approved. |
 | typed scoring | Off by default. On lets the skill send titles and metadata to the Typesafe service. |
 | name | Used in the greeting. |
@@ -102,6 +117,7 @@ Text that you type in a setting (the name, the stalled days, the quiet hours) or
 - `pmos proactive today` lists the items.
 - `pmos proactive scan` scans now.
 - `pmos proactive settings` shows the settings. Add `--enabled`, `--trigger NAME=on|off`, `--stalled-days`, `--quiet HH:MM-HH:MM|none`, `--pause-learning`, `--background-prepare on|off`, `--brief-source NAME=on|off`, `--brief-scoring on|off` or `--name` to change one.
+- `pmos proactive goals` lists today's goals with their steps. `pmos proactive goals add TEXT [--initiative ID]` adds one. `done N`, `drop N`, `reopen N` and `remove N` change the Nth goal. `pmos proactive goals plan` does the same as **Prepare my day**.
 - `pmos proactive brief` shows today's brief. `pmos proactive brief submit --file PATH` submits one. `pmos proactive brief schedule` makes the 06:45 schedule for the current repository.
 - `pmos proactive prepare` shows the queue. `pmos proactive prepare plan --initiative ID` shows a plan and its hash. `pmos proactive prepare queue --initiative ID --item ITEM --sha HASH` approves it. `pmos proactive prepare cancel ID` cancels an entry. `pmos proactive prepare run` looks at the queue now.
 - `pmos proactive learn` shows the rollup, the weights, the narrowed triggers and the lessons. `pmos proactive learn run` takes the weekly review now. `pmos proactive learn lessons` lists the approved lessons. `pmos proactive learn approve ID`, `reject ID` and `retire ID` decide a lesson. `pmos proactive learn restore TRIGGER` brings back a narrowed trigger. `pmos proactive learn reset` makes it ignore earlier feedback.
@@ -110,7 +126,7 @@ Text that you type in a setting (the name, the stalled days, the quiet hours) or
 ## Limits
 
 - It runs only while the workspace server runs. It does not catch up for time the server was off. A sleeping computer gets no scan.
-- The items from the records come from this computer. The workspace itself does not read your mail or your calendar. Only the morning-brief session does, and only the sources you switched on.
+- The items from the records come from this computer. The workspace itself does not read your mail, your calendar, Slack, Jira or Confluence. Only the morning-brief session does, and only the sources you switched on.
 - It does not start a session, push, send, post, accept or merge. It only shows items and records your feedback, and learns from it as described above. The one exception is background preparation, which starts a session only for a plan you approved, as described above.
 - An unreadable repository is listed as not read. An empty list is not proof that nothing waits there.
 - The records stay in the workspace state folder on this computer. They are not committed.

package/workspace/guide/reports-page.md

@@ -0,0 +1,80 @@
+---
+type: Guide
+title: "Reports: draft, read and issue"
+description: "How to draft a report, add your notes, issue it, and print or copy it. How the report schedules and the Today cards for reports work."
+timestamp: 2026-10-05
+---
+
+# Reports: draft, read and issue
+
+A report tells one audience what moved in the repository. The workspace drafts it from the repository's own files. You read it, add your notes and issue it. A report that you issued is frozen.
+
+The workspace keeps each report in a file of the repository, for example `planning/reports/biweekly/2026-10-16.md`. The issues ledger, `planning/runs/issues.jsonl`, records each Issue. The page and the `pmos report` command use the same writers, so they always show the same reports.
+
+## Open Reports
+
+Open the Reports tab with the shortcut `g r`, from the command palette, or from the Today card of a report. Reports shows the repository that is open.
+
+The page has three parts:
+
+- **Report schedules.** The schedules that draft a report.
+- **Reports.** The reports of the repository, newest first.
+- **The selected report.** Its text and the actions you can do on it.
+
+## Draft a report
+
+1. Press **Draft now**. The workspace writes the draft of the cadence you have selected, for example biweekly. A cadence is one kind of report: daily, weekly, biweekly or monthly.
+2. The new draft is selected. Every number in it comes from the repository's ledgers. The page never changes a number.
+
+A second **Draft now** for the same slot is refused. Press **Redraft** to write the draft again. A Redraft keeps every note. It moves a note with its initiative, even when the order of the initiatives changed. A note of an initiative that left the window stays at the end, under "Notes kept from an earlier draft".
+
+To draft another cadence, open the menu with the three dots and choose **Draft now** with the name of the cadence.
+
+## Edit notes
+
+Press **Edit notes**. One sheet shows every note of the draft: the headline, each initiative, and the needs-your-call part when the definition names an audience. Write your text and press **Save notes**. Saving a note draws the report again from the files as they are now, and keeps every note. Use it for the text, not to freeze a number: a number can change when the repository changed since the draft was written. A draft with no note markers has no note to edit. An issued report cannot be edited.
+
+## Issue a report
+
+Issue takes two presses.
+
+1. Press **Issue**. This button is on the page and on the Today card "A draft is ready to issue". A sheet reads the draft and shows its headline.
+2. Press **Issue** in the sheet. The workspace records the Issue in the issues ledger with the sha of the file you read.
+
+If the file changed after you read it, the workspace refuses and nothing is issued. Close the sheet, read the draft again and press Issue again.
+
+After Issue the file is frozen. **Redraft** and **Edit notes** are gone for that report. If someone edits the file anyway, the row shows "Edited after issue".
+
+Only you can issue. An agent cannot press Issue, and the page does not take a name from you: the workspace writes who pressed.
+
+## Print or copy an issued report
+
+An issued report offers two actions, in the sheet after Issue and on the page:
+
+- **Print / PDF** opens the print dialog with the report alone, in the light theme. Choose "Save as PDF" in that dialog to make a PDF.
+- **Copy as markdown** puts the report on the clipboard without its frontmatter and without the note markers.
+
+These are the only two ways a report leaves the page. The page has no control that moves a report out of the workspace. You decide where a printed or copied report goes.
+
+## Report schedules
+
+A schedule drafts a report at its time. It never issues one. A schedule belongs to a report by its skill: the skill `report-biweekly` feeds the biweekly report, whatever the cadence of the schedule says.
+
+- **Pause** stops a schedule. **Resume** starts it again.
+- **Set up report schedules** appears when the repository has none. One press creates the recommended schedules. It never creates one twice.
+- **Other schedules (n)** lists the schedules that feed no report. Manage them with the `pmos schedule` commands.
+
+A schedule fires only while the workspace server runs.
+
+## The Today cards
+
+| Card | When it shows | What the press does |
+|---|---|---|
+| A draft is ready to issue | A draft exists, it is newer than the last issued report of its cadence, and it is not issued. | Opens the Issue sheet. |
+| A schedule ran and left no draft | A schedule ran and no report file of its cadence is newer than the run, after two hours of grace. | Writes the draft now. |
+
+The card for the monthly kill-condition check is drawn with the initiative cards.
+
+## In a terminal
+
+The same acts exist as commands: `pmos report draft`, `pmos report issue` and `pmos report list`. The ledger records who ran each command.

package/workspace/guide/reports.md

@@ -0,0 +1,73 @@
+---
+type: Guide
+title: "Reports: draft and issue a cadence report"
+description: "How pmos report drafts a cadence report with every number, how the notes are kept when you draft again, and how you issue and freeze a report."
+timestamp: 2026-10-05
+---
+
+# Reports: draft and issue a cadence report
+
+A cadence report tells its readers where each initiative stands. The biweekly report is the first one. The `pmos report` command drafts a report, issues it and lists the reports. It reads files in the repository only. It sends nothing and it fetches nothing.
+
+## What a draft contains
+
+The script `pmos report draft` writes every number. No model runs. It reads the ledgers since the last issued report of the same cadence. If no report is issued yet, it reads the last 14 days (`report_cycle_days` in `planning/plan-rules.json`).
+
+The draft has these sections, in this order:
+
+1. **Headline.** A count of the initiatives that moved, are off track or are at risk.
+2. **Timeline.** The dated items of each initiative, as they were when the numbers were read.
+3. **One block for each initiative.** Only work initiatives that were active in the window get a block. Off track and at risk come first. A block shows the stage, the health and its reason, and the progress, for example "7 of 12 (+4)": 7 of 12 items are done, and 4 of them were done in this window. **Last cycle** lists the items done, the gates passed, the moves between Now, Next and Later, and the overdue items. **Coming cycle** lists the items that start or are due in the next window. If there are none, it lists the next 3 items in order.
+4. **New since last report.** The initiatives that were added in the window.
+5. **Decided this cycle.** The decisions you made in the window. A decision that waits for you is not in the report. It comes to you on the Cycle review card, and it does not stop you from issuing.
+6. **Needs your call.** The asks to the audience that the definition names, and to no one else.
+7. **Sources reached and not reached.** The files the script read, and each source it did not read, with the reason.
+
+A block shows a measured value only when a measurement line gives it, with its source as `<path>@<sha>`. The script does not calculate a value.
+
+If a block is off track or at risk and has no reason, the script stops and writes no draft.
+
+## The definition
+
+The definition file tells the script and the agent what the report is for. For PMOS itself it is `planning/reports/definitions/biweekly.md`. In a kit repository it is `pmos/state/reports/definitions/biweekly.md`. Its frontmatter gives the `cadence`, the `audience` and the `sections`. If the definition names no audience, Needs your call stays empty.
+
+## Notes
+
+Each block has a note between two markers:
+
+```
+<!-- pmos:note <initiative-id> -->
+Your note. Start it with "Warning:" when the block needs attention.
+<!-- /pmos:note -->
+```
+
+The headline note is `report.headline`. The asks are in the `report.asks` note, one ask on each line, each line starting with "- ". Write prose only between the markers. Do not type numbers: the script writes them.
+
+When you draft a slot again, every note stays as you wrote it, next to its initiative. The order of the blocks can change. A note for an initiative that is no longer in the window moves to "Notes kept from an earlier draft".
+
+## The commands
+
+`pmos report draft <cadence> [<slot>]` writes the draft to `planning/reports/<cadence>/<slot>.md`. The slot is a date, YYYY-MM-DD. If you do not give a slot, the slot is today. If a draft for the slot exists, the command stops and writes nothing. To draft the slot again and keep every note, add `--redraft`. To fix the clock, add `--now <time>`: two drafts with the same inputs and the same `--now` are the same, byte for byte.
+
+```
+pmos report draft biweekly 2026-10-16
+pmos report draft biweekly 2026-10-16 --redraft
+```
+
+`pmos report issue <cadence> <slot>` issues the report. Only you can do this, at a terminal. The command asks you to type the cadence and the slot, for example `biweekly-2026-10-16`. An agent session, a command with no terminal, or a different text is refused, and nothing is written. The command records the path and the git blob sha of the file in `planning/runs/issues.jsonl`. The report is then frozen: a draft of that slot is refused, and the Initiative Gate fails if the file changes. Nothing is sent. To share the report, print it or copy it as markdown.
+
+```
+pmos report issue biweekly 2026-10-16
+```
+
+`pmos report list [<cadence>]` shows each draft and each issued report, newest first, with who issued it.
+
+Every command accepts `--root <dir>` to name the repository. `draft` and `list` also accept `--json`.
+
+## The window
+
+The window starts at the time of the last issued report of the same cadence, so no time falls between two reports. The next draft starts where the last issued report stopped.
+
+## The report lane
+
+An initiative in the report lane completes its last step when you issue its report. The workflow engine reads the issued line for the initiative's `doc_path` in `issues.jsonl`.

package/workspace/guide/timeline.md

@@ -0,0 +1,70 @@
+---
+type: Guide
+title: "Breakdown › Timeline: the items on a time axis"
+description: "How to read the Timeline view of a Breakdown, move the dates of an item by dragging its bar, change a due date by dragging the end of a bar, and read the health flags."
+timestamp: 2026-10-05
+---
+
+# Breakdown › Timeline: the items on a time axis
+
+The Timeline view shows the items of one initiative on a time axis. Each item that has a start date or a due date has a bar. The bar runs from the start date to the due date.
+
+## Open the Timeline
+
+1. Open the Breakdown of an initiative.
+2. At the top of the Breakdown, press **Timeline**. The Timeline is next to **Tree** and **Board**.
+
+## Read the Timeline
+
+- **Months.** The months are across the top. The axis starts at the first month that has a date and stops at the last month that has a date. It always shows today and at least three months.
+- **Today.** A vertical line shows today. The label **Today** is on its own line above the month labels, next to the line.
+- **Scrolling.** The chart scrolls to the side inside its own area, on every screen width. When the Timeline opens, the chart scrolls so that today shows. The column with the titles stays in its position while the chart scrolls.
+- **All items.** The first row shows the full initiative, from the first start date to the last due date. It has one segment for each stage. A small gap shows where each stage starts, also when two stages overlap.
+- **Stage rows.** Under the first row, the items are in groups by stage. The stages are in the same order as in the Tree. Each stage row shows the dates of its items and the number of dated items, for example "Build, 3 dated items".
+- **Item rows.** Each item row shows the title, the dates and the bar. A Done item has a darker bar.
+- **Milestones.** An item that is a milestone shows a diamond on its due date. The diamond also shows on the stage row and on the first row.
+- **Proposed items.** An item that an agent proposed and that you did not keep yet has a lighter bar with a dashed edge and the signal **Proposed**. A proposed item does not make a stage bar or the first row longer.
+- **Items with no dates.** An item with no start date and no due date has no bar. A line under the chart gives the number of such items. To give an item dates, open it and set **Start** and **Due** in the item sheet.
+
+An item with only a start date or only a due date has a bar of one day.
+
+## Move the dates of an item
+
+- **Move both dates.** Drag the bar to the left or to the right. The start date and the due date move by the same number of days.
+- **Change the due date.** Drag the end of the bar (the line at its right edge). Only the due date changes. The due date cannot go before the start date.
+- **Short bars.** A bar that is narrower than about 24 pixels always moves whole. To change only its due date, use the keyboard or the item sheet.
+- **Open the item.** Press the bar without moving it. The item sheet opens.
+
+The bar shows the new dates while you drag it. When you let go, the workspace saves the change.
+
+With the keyboard:
+
+1. Press Tab until the bar has the focus.
+2. Press the Left or Right arrow key to move both dates by one day.
+3. Press Shift with the Left or Right arrow key to change only the due date.
+4. Press Enter to save. Press Escape to go back to the saved dates.
+
+If you move the focus away from a bar that has a change, the workspace saves the change. If you press Tab, the focus then goes to the next bar.
+
+What a move writes:
+
+- Each drag adds one line to `planning/runs/plan-items.jsonl`. The line is a `set` line with the dates of the item. When you change only the due date, the line has only the due date.
+- An item that has only a due date keeps only a due date when you move it.
+- A move changes one item only. The dates of other items do not change, also when they come after the item. The Timeline does not count effort in days.
+- If the workspace cannot save the change, a message gives the reason. The bar goes back to the saved dates.
+
+## Health
+
+The Timeline shows a flag only when an item is not on track. The flag is text and a small dot, on its own line under the dates of the item. The bar of the item has a coloured outline.
+
+- **At risk: starts before an item ends.** The item starts on or before the day that one of its predecessors ends. The flag names that predecessor and its due date. A Done predecessor does not cause this flag. A Done item never shows it.
+- **At risk: due on a date, not done.** The due date is before today and the item is not Done.
+- **Off track: milestone due on a date, not done.** A milestone has a due date before today and it is not Done. Its diamond has the same colour as the text of the flag.
+
+Limit: this view checks only the predecessors in the same initiative. A predecessor in a different initiative does not cause a flag here. To see such a clash, compare the dates of the two items.
+
+To remove a flag, change the dates of the item or of its predecessor, or move the item to Done.
+
+## On a phone
+
+On a narrow screen, the page does not scroll to the side: only the chart does. To move a bar, touch it and drag it to the side. A short bar takes a touch a little to its left or right. To scroll the chart, drag the empty part of a row.

package/workspace/guide/today.md

@@ -0,0 +1,85 @@
+---
+type: Guide
+title: "Today: what needs you"
+description: "The eight kinds of card on Today, the one button on each card, the count, the empty state, and the pmos today command."
+timestamp: 2026-10-05
+---
+
+# Today: what needs you
+
+Today lists only what waits for you. Each card is one thing that only you can close. When nothing waits, Today says so and names the next scheduled draft, for example "Nothing needs you. Next: biweekly draft Fri 16 Oct."
+
+Press **Today** in the top bar, or press `g` and then `t`, to open it. The number on the Today button is the number of cards in the scope you chose: the repository, or All repositories. It is the same number that Today shows at the top of the list.
+
+## A card
+
+Every card has four parts.
+
+- **Cause.** One sentence: why the card is here.
+- **Evidence.** The record that shows it, for example a run id, a file or a date.
+- **One button.** The act that closes the card. The verb comes first, for example **Review**, **Keep** or **Open**.
+- **The three dots.** A menu with **Open the initiative**, **Copy the command** and **Why is this here?**. The menu has the same items on every card. A touch screen and a keyboard reach them as a mouse does.
+
+When you finish the act, the card leaves and the count goes down by one. You do not dismiss a card. A card leaves only when its cause is gone.
+
+## The eight kinds
+
+Today puts the cards in this order. Within a kind, the cards keep a fixed order, so a card does not move while you read.
+
+| Kind | What it is | The button |
+|---|---|---|
+| 1. A gate is owed | A run waits for your acceptance, an outcome check is due, or a report is ready to issue. | Review, Check or Issue |
+| 2. A session is waiting | A session in a terminal asked you a question and waits for the answer. | Open |
+| 3. A step you returned | You returned an acceptance and the initiative has not been accepted since. | Open |
+| 4. Work to check | An item is in Review, or an item is Done with no evidence. | Open |
+| 5. Keep an agent breakdown | An agent proposed items. They count in no progress until you keep them. | Keep |
+| 6. A triaged capture | A capture was triaged and waits for you to add it or dismiss it. | Open |
+| 7. Cycle review | The cycle review is due. You confirm what is in Now, or move it. | Open |
+| 8. Needs repair | A schedule left no output, a line from the PM has no attestation, or a record has no anchor. Today shows the card until it is fixed. | Open |
+
+A stalled initiative is not a card. It shows as a health reason on the initiative, in the list and in its detail.
+
+A source that cannot be read is not a card either. It shows in the notice at the top of Today, so a source that fails never looks like an empty list.
+
+## Close a gate on a run
+
+A card of kind 1 for a run has the button **Review**. The steps are:
+
+1. Press **Review** on the card. The card opens in place and shows what the evaluator said.
+2. Press **Right** or **Wrong** to say whether the evaluator was right.
+3. Optional: press **Add a note** and write one line on why.
+4. Press **Accept** to accept the run, or **Return** to send it back.
+
+That is four taps, or three taps without the note. The workspace records your act in the acceptance ledger. The note and your label are part of that record. If the workspace cannot record the act, the card stays and a message says that nothing was recorded.
+
+## The scope
+
+The switch at the top of Today has two choices.
+
+- **Repository.** The cards of the repository you chose. The number on the Today button counts these cards.
+- **All repositories.** The cards of every repository. The count at the top says how many repositories it counts across.
+
+The number on the Today button and the number at the top of the list are the same in both choices.
+
+## Short lists
+
+Today shows the first three cards. Press **Show more** to see the rest, and **Show fewer** to fold them again. The count always includes every card.
+
+## A source that cannot be read
+
+When Today cannot read a source, for example a broken needs file, it says so in a notice at the top of the list. It does not show an empty list and it does not say that nothing needs you. The notice names the source and the reason. Today still shows the cards of the sources it could read.
+
+## From a terminal
+
+`pmos today` prints the same list as Today, in the same order, with the kind first.
+
+```
+pmos today                  # the repository you are in
+pmos today --ws <id>        # one repository by its id
+pmos today --json           # the list as JSON
+pmos today --root <dir>     # read a repository folder without a server
+```
+
+With the workspace server running, the command asks the server, so it also lists the sessions that wait for you. Without the server it reads the repository files and prints a line that says it did not read the sessions. The command prints "Nothing needs you" and the next draft when the list is empty. It exits with 0 when it read the list, 1 when it could not read it, and 2 when you gave it an option it does not have.
+
+The page and the command read the route `GET /api/today?ws=<id>`. The route changes nothing.

package/workspace/guide/validate-with-typesafe.md

@@ -102,7 +102,7 @@ The workspace reads the TypeSafe key only on this machine. After you save the ke
 
 ## Set it up
 
-1. Open **validate** in the settings and tools drawer.
+1. Open Settings. Under Validate consent, press **Open Validate**. Validate opens as a tab.
 2. Under **TypeSafe key**, paste the key and press **save**. Press **remove** to delete a saved key.
 3. Under **this repository**, press **turn on**. This choice applies to the selected repository only.
 4. Enter the paths that the workspace must never send, one for each line. A path ends with `/` for a folder. A `*` matches any characters. Press **save excluded paths**.

package/workspace/lib/actor.js

@@ -0,0 +1,91 @@
+'use strict';
+/* actor.js — who a write is, read from the CALL PATH, never from a field (pm-os-absorb, PRD R23 and R25).
+ *
+ *   fromUi()              → { by: 'pm:wawan', via: 'ui' }      the page, after the route's own checks
+ *   fromCli({isTTY, env}) → { by, via: 'cli' }                 a bound agent session, else a terminal (the PM), else unknown
+ *   isPm(actor) · isAgent(actor) · sessionOf(actor)
+ *   pageName(by)          → 'agent:sess-<n>' for 'agent:sess-<n>.<8hex>', else `by` unchanged
+ *
+ * F5: a ledger line's `by` carries the session token; the page must never see it. Every GET route and every needs
+ * provider maps each `by` it answers through pageName (proposals, moves, item owners, report attributions).
+ *
+ * The placements, measurements and issues writers take their actor from here, so the four ledgers attribute one way.
+ * A caller never passes `by` or `via`: a writer that accepted them would make attribution something a caller chooses.
+ *
+ * THE SESSION-TOKEN MAP (Run 2, slice 2A). server.js gives each agent session a token, `sess-<n>.<8 hex>`, in its PTY
+ * environment as PMOS_SESSION. The token itself is never written to disk or sent to the page (D08, F5). server.js
+ * persists its SHA-256 (`tokenHash`) in the session's own meta file, so after a restart the map still answers which
+ * session a token belongs to and which initiative that session is bound to. The map is read from the files each time
+ * (no cache, D33), so a CLI with no server reads the same answer as the server.
+ *
+ *   tokenHash(token)                       → 64 hex characters, or null for a value that is not a token
+ *   sessionForToken(token, { sessDir })    → { session, initiative } | null
+ *
+ * HONEST LIMIT. A token is an attribution, not a credential: a process that unsets PMOS_SESSION is no longer an agent
+ * to fromCli. pm-guard.js requirePmCli asks such a caller to type the id of a PM-only act (X12); CI detection is the
+ * backstop for the rest.
+ */
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const PM_SLUG = 'wawan';
+const SESSION_RE = /^sess-\d+\.[0-9a-f]{8}$/;
+const BY_RE = /^(?:pm:[a-z0-9_-]{1,40}|agent:unknown|agent:sess-\d+\.[0-9a-f]{8})$/;
+const VIA = ['ui', 'cli'];
+
+const PM = Object.freeze({ by: `pm:${PM_SLUG}`, via: 'ui' });
+
+/** The page. Call it only after the route has run its checks (pm-guard.js requirePmPress for a PM-only act). */
+function fromUi() { return { by: PM.by, via: 'ui' }; }
+
+/**
+ * A `pmos <verb>` call. A bound agent session FIRST, by its token: an agent that runs its commands in a PTY (or wraps
+ * them with `script`) still has a terminal, and a terminal must not turn its writes into the PM's. Only agent sessions
+ * get PMOS_SESSION (server.js spawnSession), so the PM's own shell is a terminal with no token: the PM. Else unknown.
+ */
+function fromCli({ isTTY = !!(process.stdin.isTTY && process.stdout.isTTY), env = process.env } = {}) {
+  const tok = env && env.PMOS_SESSION;
+  if (typeof tok === 'string' && SESSION_RE.test(tok)) return { by: `agent:${tok}`, via: 'cli' };
+  if (isTTY) return { by: `pm:${PM_SLUG}`, via: 'cli' };
+  return { by: 'agent:unknown', via: 'cli' };
+}
+
+const valid = (a) => !!a && typeof a.by === 'string' && BY_RE.test(a.by) && VIA.includes(a.via);
+const isPm = (a) => valid(a) && a.by.startsWith('pm:');
+const isAgent = (a) => valid(a) && a.by.startsWith('agent:');
+/** The session token of an agent actor, or null. */
+const sessionOf = (a) => (isAgent(a) && a.by !== 'agent:unknown' ? a.by.slice('agent:'.length) : null);
+
+/** The name the page may show. Strips the session token's secret suffix; anything else passes through. */
+function pageName(by) {
+  if (typeof by !== 'string') return by;
+  const m = /^(agent:sess-\d+)\.[0-9a-f]{8}$/.exec(by);
+  return m ? m[1] : by;
+}
+
+/** The SHA-256 of a session token. The map stores this, never the token. */
+function tokenHash(token) {
+  if (typeof token !== 'string' || !SESSION_RE.test(token)) return null;
+  return crypto.createHash('sha256').update(token).digest('hex');
+}
+
+/**
+ * The session a token belongs to, read from the session meta files server.js persists (`<sessDir>/<id>.json`). The id
+ * part of the token names the file, and the stored hash must match: a token with the right id and a wrong suffix is not
+ * that session. Null when there is no such session or no hash on record. `plan_item` is the item Hand to agent gave the
+ * session (null for any other session).
+ */
+function sessionForToken(token, { sessDir } = {}) {
+  const h = tokenHash(token);
+  if (!h || typeof sessDir !== 'string' || !sessDir) return null;
+  const id = token.slice(0, token.indexOf('.'));
+  let meta;
+  try { meta = JSON.parse(fs.readFileSync(path.join(sessDir, id + '.json'), 'utf8')); } catch { return null; }
+  if (!meta || meta.id !== id || typeof meta.tokenHash !== 'string' || meta.tokenHash.length !== h.length) return null;
+  if (!crypto.timingSafeEqual(Buffer.from(meta.tokenHash), Buffer.from(h))) return null;
+  const str = (v) => (typeof v === 'string' && v ? v : null);
+  return { session: id, initiative: str(meta.initiative), plan_item: str(meta.plan_item) };
+}
+
+module.exports = { tokenHash, sessionForToken, PM_SLUG, SESSION_RE, BY_RE, VIA, fromUi, fromCli, valid, isPm, isAgent, sessionOf, pageName };

package/workspace/lib/board-cache.js

@@ -32,9 +32,38 @@ const REFRESH_TIMEOUT_MS = 120000;   // a derivation that cannot finish in 2 min
 const cache = new Map();             // root -> { sig, at, value, error }
 const inflight = new Map();          // root -> true
 
+// headSha runs on every signature, and the needs poll asks for a signature per registered tree several times per
+// request, so a `git rev-parse` each time held the server for seconds with twenty trees registered. The answer is
+// kept per root while the files a commit, checkout or reset touches (HEAD, its ref, packed-refs, the HEAD reflog)
+// are unchanged; anything unreadable falls back to asking git.
+const headMemo = new Map();          // root -> { key, sha }
+function gitDirOf(root) {
+  const dotgit = path.join(root, '.git');
+  const st = fs.statSync(dotgit);
+  if (st.isDirectory()) return { dir: dotgit, common: dotgit };
+  const m = /^gitdir:\s*(.+)\s*$/m.exec(fs.readFileSync(dotgit, 'utf8'));
+  if (!m) throw new Error('no gitdir');
+  const dir = path.resolve(root, m[1].trim());
+  let common = dir;
+  try { common = path.resolve(dir, fs.readFileSync(path.join(dir, 'commondir'), 'utf8').trim()); } catch { /* not a linked worktree */ }
+  return { dir, common };
+}
+function headKey(root) {
+  const { dir, common } = gitDirOf(root);
+  const head = fs.readFileSync(path.join(dir, 'HEAD'), 'utf8').trim();
+  const stat = (f) => { try { const st = fs.statSync(f); return `${st.size}:${st.mtimeMs}:${st.ino}`; } catch { return '-'; } };
+  const ref = /^ref:\s*(.+)$/.exec(head);
+  return [head, ref ? stat(path.join(common, ref[1])) : '', stat(path.join(common, 'packed-refs')), stat(path.join(dir, 'logs', 'HEAD'))].join('|');
+}
 function headSha(root) {
+  let key = null;
+  try { key = headKey(root); } catch { key = null; }
+  const hit = headMemo.get(root);
+  if (key && hit && hit.key === key) return hit.sha;
   const r = spawnSync('git', ['rev-parse', 'HEAD'], { cwd: root, encoding: 'utf8', timeout: 5000 });
-  return r.status === 0 && r.stdout ? r.stdout.trim() : 'no-head';
+  const sha = r.status === 0 && r.stdout ? r.stdout.trim() : 'no-head';
+  if (key) headMemo.set(root, { key, sha });
+  return sha;
 }
 
 // The records' own state, so an UNCOMMITTED edit still invalidates. Cheap: one readdir + one stat
@@ -42,8 +71,9 @@ function headSha(root) {
 function recordsSig(root) {
   // Both layouts (pmos-self `planning/`, a PM repository's `pmos/state/`), and the ledgers the
   // board's rows depend on: an uncommitted lifecycle or acceptance line must not wait out the TTL (D70).
+  // pm-os-absorb: plan-items.jsonl (Run 4's Build rule reads items) and issues.jsonl (Run 5's report lane reads issues).
   const dirs = [path.join(root, 'planning', 'initiatives'), path.join(root, 'pmos', 'state', 'initiatives')];
-  const ledgers = ['lifecycle.jsonl', 'acceptances.jsonl'].flatMap((f) => [
+  const ledgers = ['lifecycle.jsonl', 'acceptances.jsonl', 'plan-items.jsonl', 'issues.jsonl'].flatMap((f) => [
     path.join(root, 'planning', 'runs', f), path.join(root, 'pmos', 'state', f)]);
   let total = 0; let newest = 0; let any = false;
   for (const dir of dirs) {