kankaku 0.7.0 → 0.8.0

package/src/domain/hub-entry.ts

@@ -207,10 +207,12 @@ export interface TaskEntryPayload {
   legacy_client_label: string;
   repo_project: string;
   schema: number;
+  /** Coding agent that MEASURED this task, lowercase slug — the orchestrator record's own {@link WorkRecordMetadata.agent} when it carries one (who measured, not who syncs), else `ctx.agent` (the syncing process's own identity) as a legacy fallback. See {@link WorkRecordMetadata.agent}. */
   agent: string;
   agent_version?: string;
   /** Non-default session directory, see `TaskView.sessionDir`. A measurement field, not assignment: sent on both create and update. */
   session_dir?: string;
+  /** The integration that wrote this task's records, lowercase slug — same record-wins-over-ctx rule as {@link agent}. */
   plugin: string;
   plugin_version?: string;
   waiting_quality: WaitingQuality;
@@ -218,12 +220,59 @@ export interface TaskEntryPayload {
   subagent_linkage: SubagentLinkage;
 }
 
-/** `TaskEntryPayload` minus the assignment fields — what an update sends. See the module docs' CRITICAL rule. */
-export type TaskEntryUpdatePayload = Omit<TaskEntryPayload, "client" | "project" | "task" | "legacy_client_label">;
+/**
+ * `TaskEntryPayload` minus the assignment fields — what an update sends. See
+ * the module docs' CRITICAL rule.
+ *
+ * `agent`/`agent_version`/`plugin`/`plugin_version` are optional here (unlike
+ * on `TaskEntryPayload`, where they are always sent on create): an update for
+ * a task whose orchestrator record carries no who-measured identity (a
+ * legacy record, written before this feature existed) omits them entirely,
+ * so a re-sync by a DIFFERENT process never overwrites a row's original
+ * identity with its own. See {@link buildTaskEntryUpdatePayload}.
+ */
+export type TaskEntryUpdatePayload = Omit<
+  TaskEntryPayload,
+  "client" | "project" | "task" | "legacy_client_label" | "agent" | "agent_version" | "plugin" | "plugin_version"
+> & {
+  agent?: string;
+  agent_version?: string;
+  plugin?: string;
+  plugin_version?: string;
+};
+
+/**
+ * The who-measured identity (`agent`/`agentVersion`/`plugin`/`pluginVersion`)
+ * for a task's payload: the orchestrator record's own fields, taken as a
+ * unit, when it carries an `agent` — a missing version on the record is
+ * omitted, never backfilled from `ctx` — otherwise `ctx`'s identity (the
+ * syncing process's own), exactly as before this feature existed. See
+ * `domain/work-record.ts#WorkRecordMetadata.agent`'s doc comment.
+ */
+function resolveTaskIdentity(
+  task: TaskView,
+  ctx: HubEntryContext,
+): { agent: string; agentVersion?: string; plugin: string; pluginVersion?: string } {
+  const orchestrator = task.orchestrator;
+  if (orchestrator.agent !== undefined) {
+    // The record's four fields are taken as a unit. A record written by an
+    // integration that stamped `agent` but not `plugin` gets the syncing
+    // context's `plugin` ONLY on create, so the row is never blank; the
+    // update payload below never resends a plugin the record does not own.
+    return {
+      agent: orchestrator.agent,
+      agentVersion: orchestrator.agentVersion,
+      plugin: orchestrator.plugin ?? ctx.plugin,
+      pluginVersion: orchestrator.plugin !== undefined ? orchestrator.pluginVersion : undefined,
+    };
+  }
+  return { agent: ctx.agent, agentVersion: ctx.agentVersion, plugin: ctx.plugin, pluginVersion: ctx.pluginVersion };
+}
 
 /** Build the full `task_entries` payload for a **create** request — every field, including assignment. */
 export function buildTaskEntryCreatePayload(task: TaskView, ctx: HubEntryContext): TaskEntryPayload {
   const assignment = resolveTaskAssignment(task, ctx.clients, ctx.projects, ctx.tasks);
+  const identity = resolveTaskIdentity(task, ctx);
   return {
     task_id: task.id,
     client: assignment.clientId,
@@ -253,11 +302,11 @@ export function buildTaskEntryCreatePayload(task: TaskView, ctx: HubEntryContext
     legacy_client_label: assignment.legacyClientLabel,
     repo_project: task.project,
     schema: task.orchestrator.schema,
-    agent: ctx.agent,
-    ...(ctx.agentVersion !== undefined ? { agent_version: ctx.agentVersion } : {}),
+    agent: identity.agent,
+    ...(identity.agentVersion !== undefined ? { agent_version: identity.agentVersion } : {}),
     ...(task.sessionDir !== undefined ? { session_dir: task.sessionDir } : {}),
-    plugin: ctx.plugin,
-    ...(ctx.pluginVersion !== undefined ? { plugin_version: ctx.pluginVersion } : {}),
+    plugin: identity.plugin,
+    ...(identity.pluginVersion !== undefined ? { plugin_version: identity.pluginVersion } : {}),
     waiting_quality: computeWaitingQuality(),
     cost_quality: computeCostQuality(task),
     subagent_linkage: computeSubagentLinkage(task),
@@ -269,10 +318,40 @@ export function buildTaskEntryCreatePayload(task: TaskView, ctx: HubEntryContext
  * fields only — never `client`, `project`, `task` or `legacy_client_label`,
  * so a re-sync can never undo a reassignment made in the web. See the
  * module docs' CRITICAL rule.
+ *
+ * `agent`/`agent_version`/`plugin`/`plugin_version` are included ONLY when
+ * the orchestrator record itself carries a who-measured `agent` — otherwise
+ * they are OMITTED entirely (never sent as `ctx`'s own identity), so a
+ * re-sync of a legacy record by a different process never overwrites the
+ * row's original identity in the hub. See `domain/work-record.ts`'s
+ * "Measurement rules" and {@link resolveTaskIdentity}.
  */
 export function buildTaskEntryUpdatePayload(task: TaskView, ctx: HubEntryContext): TaskEntryUpdatePayload {
-  const { client: _client, project: _project, task: _task, legacy_client_label: _legacy, ...rest } = buildTaskEntryCreatePayload(task, ctx);
-  return rest;
+  const {
+    client: _client,
+    project: _project,
+    task: _task,
+    legacy_client_label: _legacy,
+    agent,
+    agent_version,
+    plugin,
+    plugin_version,
+    ...rest
+  } = buildTaskEntryCreatePayload(task, ctx);
+
+  if (task.orchestrator.agent === undefined) return rest;
+
+  // `plugin`/`plugin_version` are resent only when the record itself carries
+  // them; a record with `agent` but no `plugin` must never have the syncing
+  // process's plugin written over the row's original one.
+  const recordHasPlugin = task.orchestrator.plugin !== undefined;
+  return {
+    ...rest,
+    agent,
+    ...(agent_version !== undefined ? { agent_version } : {}),
+    ...(recordHasPlugin ? { plugin } : {}),
+    ...(recordHasPlugin && plugin_version !== undefined ? { plugin_version } : {}),
+  };
 }
 
 /** One `work_records` row — raw per-`WorkRecord` detail, always `rollup: false`. */

package/src/domain/panel-model.ts

@@ -83,10 +83,13 @@ const SCREEN_TITLES: Record<Exclude<PanelScreenId, "root">, string> = {
   about: "About",
 };
 
-/** `kankaku` at root, `kankaku · <Screen>` on every other screen. */
+/** The prompt glyph that opens every panel title, the owner's mark for kankaku. */
+export const PANEL_TITLE_PREFIX = ">_";
+
+/** `>_ kankaku` at root, `>_ kankaku · <Screen>` on every other screen. */
 export function panelTitle(screen: PanelScreenId): string {
-  if (screen === "root") return "kankaku";
-  return `kankaku · ${SCREEN_TITLES[screen]}`;
+  if (screen === "root") return `${PANEL_TITLE_PREFIX} kankaku`;
+  return `${PANEL_TITLE_PREFIX} kankaku · ${SCREEN_TITLES[screen]}`;
 }
 
 /** One clickable/keyboard hint shown in the panel's footer. */
@@ -97,9 +100,9 @@ export interface PanelHint {
 
 /**
  * The footer hint row for a screen: navigation hints, an optional search
- * hint when the current body supports it, and how Escape/`q` behave — back
- * at root closes the panel outright, so root shows only `esc close`; every
- * other screen shows both `esc back` and `q close`.
+ * hint when the current body supports it, and how Escape/left arrow/`q`
+ * behave — back at root closes the panel outright, so root shows only
+ * `esc close`; every other screen shows both `esc/← back` and `q close`.
  */
 export function footerHints(screen: PanelScreenId, options: { searchable: boolean }): PanelHint[] {
   const hints: PanelHint[] = [{ key: "↑↓", label: "move" }];
@@ -113,7 +116,7 @@ export function footerHints(screen: PanelScreenId, options: { searchable: boolea
 
   hints.push({ key: "enter", label: "select" });
   if (options.searchable) hints.push({ key: "/", label: "search" });
-  hints.push({ key: "esc", label: "back" }, { key: "q", label: "close" });
+  hints.push({ key: "esc/←", label: "back" }, { key: "q", label: "close" });
   return hints;
 }
 

package/src/domain/sync-plan.ts

@@ -134,6 +134,16 @@ export function computeTaskContentHash(task: TaskView): string {
       // `undefined` is dropped by the serialiser, so a task that never knew
       // its reasoning effort keeps the hash it had before this field existed.
       thinkingLevel: task.orchestrator.thinkingLevel,
+      // A task gaining a who-measured identity
+      // (domain/hub-entry.ts#resolveTaskIdentity) must resync, since it
+      // changes which agent/plugin the row is attributed to; the version
+      // fields are left out on purpose so a version-only bump alone does not
+      // force a resync. The keys are added CONDITIONALLY: `stableStringify`
+      // renders an `undefined` value as `"agent":undefined`, so an
+      // unconditional key would change every legacy task's hash and force a
+      // full resync right after upgrading (see the golden-hash test).
+      ...(task.orchestrator.agent !== undefined ? { agent: task.orchestrator.agent } : {}),
+      ...(task.orchestrator.plugin !== undefined ? { plugin: task.orchestrator.plugin } : {}),
     }),
   );
 }

package/src/domain/work-record.ts

@@ -201,6 +201,23 @@ export interface WorkRecordMetadata {
    * (SUBAGENT-REQ-017). Never set on an `orchestrator` record.
    */
   profile?: string;
+  /**
+   * Coding agent that MEASURED this record, lowercase slug (e.g. `"pi"`).
+   * Who measured, not who syncs — a different process (a standalone
+   * `kankaku` TUI, or a session for a different agent sharing the same
+   * `worklog.jsonl`) may later push this record to the hub, and must never
+   * overwrite this identity with its own. See kankaku-hub `docs/contract.md`
+   * "Agent and measurement quality" and `domain/hub-entry.ts`. Optional and
+   * additive: `WORK_RECORD_SCHEMA` is unchanged and an older record without
+   * it still validates.
+   */
+  agent?: string;
+  /** The measuring agent's own version, when it could be determined without a hot-path cost. Never guessed — omitted rather than sent wrong. */
+  agentVersion?: string;
+  /** The integration that wrote this record, lowercase slug (e.g. `"kankaku"`). Same who-measured-not-who-syncs rule as {@link agent}. */
+  plugin?: string;
+  /** This integration's own version, from its `package.json`, read once. */
+  pluginVersion?: string;
 }
 
 export type WorkRecord = WorkRecordCore & WorkRecordMetadata;
@@ -294,6 +311,10 @@ export function isWorkRecord(value: unknown): value is WorkRecord {
     (record["roleConfidence"] === undefined || record["roleConfidence"] === "uncertain") &&
     (record["orchestratorRef"] === undefined || isOrchestratorRef(record["orchestratorRef"])) &&
     (record["costObserved"] === undefined || record["costObserved"] === true) &&
-    (record["profile"] === undefined || typeof record["profile"] === "string")
+    (record["profile"] === undefined || typeof record["profile"] === "string") &&
+    (record["agent"] === undefined || typeof record["agent"] === "string") &&
+    (record["agentVersion"] === undefined || typeof record["agentVersion"] === "string") &&
+    (record["plugin"] === undefined || typeof record["plugin"] === "string") &&
+    (record["pluginVersion"] === undefined || typeof record["pluginVersion"] === "string")
   );
 }

package/src/hub/index.ts

@@ -7,7 +7,9 @@
  * for which ones and why.
  */
 export * from "../adapters/cached-catalog.ts";
+export * from "../adapters/export-writer.ts";
 export * from "../adapters/file-modes.ts";
+export * from "../adapters/hub-actions.ts";
 export * from "../adapters/hub-credentials.ts";
 export * from "../adapters/jsonl-work-log.ts";
 export * from "../adapters/kankaku-dir.ts";
@@ -15,5 +17,9 @@ export * from "../adapters/lazy-jsonl-work-log.ts";
 export * from "../adapters/pocketbase-catalog.ts";
 export * from "../adapters/pocketbase-client.ts";
 export * from "../adapters/pocketbase-sink.ts";
+export * from "../adapters/project-config.ts";
+export * from "../adapters/report-data.ts";
+export * from "../adapters/report.ts";
+export * from "../adapters/report-views.ts";
 export * from "../adapters/sync-runner.ts";
 export * from "../adapters/sync-state-store.ts";