diff --git a/apps/server/src/kin/chat/KinChatService.ts b/apps/server/src/kin/chat/KinChatService.ts
index 9ddf482ff10a7..5170346f48f27 100644
--- a/apps/server/src/kin/chat/KinChatService.ts
+++ b/apps/server/src/kin/chat/KinChatService.ts
@@ -49,6 +49,7 @@ import * as SqlError from "effect/sql/SqlError";
import * as SecureRandom from "effect/crypto/SecureRandom";
import { toPersistenceSqlError } from "../../persistence/Errors.ts";
import { validateState } from "../widgets/registry.ts";
+import { deferralCardActions, deferralCardActionsReady } from "../widgets/deferralCard.ts";
import * as Hub from "./KinChatHub.ts";
import * as Repository from "./KinChatRepository.ts";
import type { AgentIdentity, PersonIdentity } from "./KinIdentity.ts";
@@ -949,7 +950,11 @@ const make = Effect.gen(function* () {
reason: "use_approvals",
message: "Use the signed approvals service.",
});
- if (input.type === "owner_check" || (input.type === "task" && input.widgetId === undefined))
+ if (
+ input.type === "owner_check" ||
+ input.type === "deferral" ||
+ (input.type === "task" && input.widgetId === undefined)
+ )
return yield* notAllowed;
let state = yield* validateState(input.type, input.state);
let widget: KinWidget;
@@ -1088,6 +1093,14 @@ const make = Effect.gen(function* () {
)
return yield* invalidState;
}
+ if (widget.type === "deferral") {
+ if (member.role !== "owner") return yield* notAllowed;
+ if (
+ !deferralCardActionsReady ||
+ !deferralCardActions.some((action) => action === request.actionId)
+ )
+ return yield* notAllowed;
+ }
const body = yield* encodeAction({
widgetId: request.widgetId,
revision: request.revision,
diff --git a/apps/server/src/kin/lead/LeadMemory.test.ts b/apps/server/src/kin/lead/LeadMemory.test.ts
index b9ece593335c8..01541b81f2a3a 100644
--- a/apps/server/src/kin/lead/LeadMemory.test.ts
+++ b/apps/server/src/kin/lead/LeadMemory.test.ts
@@ -481,7 +481,7 @@ it.live(
.pipe(Effect.flip)).reason,
"not_found",
);
- for (const due of ["bad", "2026-02-30", "2026-11-13T09:00:00"])
+ for (const due of ["bad", "2026-02-30", "2026-11-13T09:00:00", "1969-12-31", "0000-01-01"])
assert.strictEqual(
(yield* decodeDefer({ ...deferred, due }).pipe(Effect.result))._tag,
"Failure",
diff --git a/apps/server/src/kin/lead/LeadMemory.ts b/apps/server/src/kin/lead/LeadMemory.ts
index 9c98977df9f4f..78bb082da6bce 100644
--- a/apps/server/src/kin/lead/LeadMemory.ts
+++ b/apps/server/src/kin/lead/LeadMemory.ts
@@ -35,6 +35,9 @@ const date = Schema.String.check(
expected: "a date or timestamp with explicit offset",
}),
);
+const deferDue = date.check(
+ Schema.makeFilter((value) => /^20\d\d-/.test(value), { expected: "a date in 2000-2099" }),
+);
const itemId = KinMemoryItemId.check(Schema.isPattern(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,199}$/));
export const SearchInput = Schema.Struct({
kind: Schema.optional(MemoryItemFrontMatter.fields.kind),
@@ -65,7 +68,7 @@ export const WriteInput = Schema.Struct({
export const DeferInput = Schema.Struct({
itemId: Schema.optional(itemId),
what: TrimmedNonEmptyString.check(Schema.isMaxLength(8000)),
- due: date,
+ due: deferDue,
onDue: Schema.Literals(["remind", "start", "ask", "chase"]),
chatId: KinChatId,
sourceEventId: TrimmedNonEmptyString,
diff --git a/apps/server/src/kin/lead/layer.ts b/apps/server/src/kin/lead/layer.ts
index 208f96ba6f7fb..685c2742aa7d8 100644
--- a/apps/server/src/kin/lead/layer.ts
+++ b/apps/server/src/kin/lead/layer.ts
@@ -4,6 +4,7 @@ import * as OwnerCheck from "../triggers/ownerCheck.ts";
import * as TriggerScheduler from "../triggers/KinTriggerScheduler.ts";
import * as TriggerStore from "../triggers/KinTriggerStore.ts";
import * as TriggerInbox from "../triggers/KinTriggerInbox.ts";
+import * as TriggerService from "../triggers/KinTriggerService.ts";
import { forkParked } from "../../serverActivation.ts";
import { KinOrgId, KinChatId, KinMessageId } from "@t3tools/contracts";
import * as SecureRandom from "effect/crypto/SecureRandom";
@@ -126,6 +127,12 @@ const withServices = (entry: Layer.Layer) =>
}),
).pipe(Layer.provide(KinChatRepository.layer)),
),
+ Layer.provide(
+ TriggerService.syncHooksLayer.pipe(
+ Layer.provide(TriggerService.layer),
+ Layer.provide(KinChatRepository.layer),
+ ),
+ ),
Layer.provide(KinPersistence.layer),
);
diff --git a/apps/server/src/kin/memory/Memory.ts b/apps/server/src/kin/memory/Memory.ts
index d8aafb19a722a..cc6ca4aedc0cc 100644
--- a/apps/server/src/kin/memory/Memory.ts
+++ b/apps/server/src/kin/memory/Memory.ts
@@ -129,6 +129,19 @@ export class MemoryRecoveryHooks extends Context.Service<
}
>()("t3/kin/memory/Memory/MemoryRecoveryHooks") {}
+export interface MemorySyncSnapshot {
+ readonly head: string;
+ readonly items: ReadonlyArray;
+ readonly duplicateIds: ReadonlySet;
+}
+
+/** Sees every loaded snapshot and owns its own once-per-head, retry and failure handling. */
+export class MemorySyncHooks extends Context.Reference<{
+ readonly syncItems: (orgId: KinOrgId, snapshot: MemorySyncSnapshot) => Effect.Effect;
+}>("t3/kin/memory/Memory/MemorySyncHooks", {
+ defaultValue: () => ({ syncItems: () => Effect.void }),
+}) {}
+
export class Memory extends Context.Service<
Memory,
{
@@ -185,9 +198,7 @@ const folders = ["objectives", "commitments", "deferrals", "decisions", "people"
const maxBlobBytes = 256 * 1024;
-interface Snapshot {
- readonly head: string;
- readonly items: ReadonlyArray;
+interface Snapshot extends MemorySyncSnapshot {
readonly files: ReadonlyMap;
index?: string;
}
@@ -218,6 +229,8 @@ const make = Effect.gen(function* () {
const path = yield* Path.Path;
const sql = yield* SqlClient.SqlClient;
const writerLocks = new Map();
+ const pinnedHeads = new Map();
+ const hooks = yield* MemorySyncHooks;
const withWriterLock = (orgId: KinOrgId, effect: Effect.Effect) => {
let lock = writerLocks.get(orgId);
if (!lock) {
@@ -281,6 +294,9 @@ const make = Effect.gen(function* () {
operation: "record",
reason: "Anchor changed",
});
+ // The front-matter cache follows commits to the default branch.
+ if (branch === (config.defaultBranch ?? "main") && pinnedHeads.get(orgId) === previous)
+ pinnedHeads.set(orgId, head);
}),
)
.pipe(
@@ -297,7 +313,6 @@ const make = Effect.gen(function* () {
});
const cache = yield* MemoryCache.MemoryCache;
const locks = new Map();
- const pinnedHeads = new Map();
const initializedCheckouts = new Set();
const duplicateWarnings = new Map>();
const snapshots = new Map();
@@ -530,7 +545,10 @@ const make = Effect.gen(function* () {
return { writer: paths.writer, read: paths.read };
});
- const load = Effect.fn("Memory.load")(function* (orgId: KinOrgId, force = false) {
+ const loadSnapshot = Effect.fn("Memory.loadSnapshot")(function* (
+ orgId: KinOrgId,
+ force: boolean,
+ ) {
const paths = yield* pathsFor(orgId);
const pinned = pinnedHeads.get(orgId);
if (pinned === undefined) yield* validateWriter(orgId, paths, false);
@@ -693,6 +711,7 @@ const make = Effect.gen(function* () {
head,
items,
files,
+ duplicateIds,
...(previous?.head === head && previous.index !== undefined ? { index: previous.index } : {}),
};
snapshots.set(orgId, snapshot);
@@ -702,6 +721,11 @@ const make = Effect.gen(function* () {
}
return snapshot;
});
+ const load = Effect.fn("Memory.load")(function* (orgId: KinOrgId, force = false) {
+ const snapshot = yield* loadSnapshot(orgId, force);
+ yield* hooks.syncItems(orgId, snapshot);
+ return snapshot;
+ });
const query = Effect.fn("Memory.query")(function* (orgId: KinOrgId, q: MemoryQuery) {
for (const value of [q.dueBefore, q.dueAfter]) {
diff --git a/apps/server/src/kin/memory/MemoryWriter.test.ts b/apps/server/src/kin/memory/MemoryWriter.test.ts
index e30d07c199428..13f18b2810bd3 100644
--- a/apps/server/src/kin/memory/MemoryWriter.test.ts
+++ b/apps/server/src/kin/memory/MemoryWriter.test.ts
@@ -3,7 +3,12 @@ import { memoryGit } from "./git.ts";
import * as NodeZlib from "node:zlib";
import * as NodeServices from "@effect/platform-node/NodeServices";
import { expect, it } from "@effect/vitest";
-import { KinAgentId, KinOrgId, VcsProcessSpawnError } from "@t3tools/contracts";
+import {
+ KinAgentId,
+ KinOrgId,
+ type MemoryItemHead,
+ VcsProcessSpawnError,
+} from "@t3tools/contracts";
import * as Effect from "effect/Effect";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
@@ -58,6 +63,9 @@ it.live.each([
"review-null",
"credentials",
"read-during-record",
+ "deferral-card-remind",
+ "deferral-plain-remind",
+ "deferral-card-other-item",
"H3-packed-ref",
"M1-unanchored",
"M2-nondescendant",
@@ -120,6 +128,10 @@ it.live.each([
}),
);
}
+ if (scenario.startsWith("deferral-")) {
+ yield* fs.makeDirectory(`${source}/deferrals`);
+ yield* fs.writeFileString(`${source}/deferrals/def-001.md`, fixtureItem());
+ }
if (scenario === "B5-journal" || scenario === "P4-journal") {
yield* fs.makeDirectory(`${source}/journal/2026`, { recursive: true });
yield* fs.writeFile(
@@ -207,9 +219,18 @@ it.live.each([
credentialHelper: "fixture-server-helper",
repositories: [{ orgId, repoUrl: remote, path: "state" }],
});
+ const synced: Array> = [];
const memoryLayer = Memory.layer.pipe(
Layer.provide(config),
Layer.provide(Layer.succeed(Memory.MemoryRecoveryHooks, { notify: () => Effect.void })),
+ Layer.provide(
+ Layer.succeed(Memory.MemorySyncHooks, {
+ syncItems: (_org, snapshot) =>
+ Effect.sync(() => {
+ synced.push(snapshot.items.map(({ head }) => head));
+ }),
+ }),
+ ),
);
const hooks = Layer.succeed(Writer.MemoryWriterHooks, {
notify: Effect.fn("Test.notice")((notice) =>
@@ -233,7 +254,8 @@ it.live.each([
level:
scenario === "conflict" ||
scenario === "B5-journal" ||
- scenario === "read-during-record"
+ scenario === "read-during-record" ||
+ scenario.startsWith("deferral-")
? "L1"
: "L0",
timeZone: "Asia/Kolkata",
@@ -258,11 +280,22 @@ it.live.each([
itemId: scenario === "owner-other-item-keep" ? "other-item" : "def-001",
action: scenario === "owner-drop-keep" ? "drop" : "keep",
}
- : {
- saidBy: "fixture-owner",
- trust: "owner",
- source: "fixture-owner-message",
- },
+ : scenario === "deferral-card-remind" ||
+ scenario === "deferral-card-other-item"
+ ? {
+ saidBy: "fixture-owner",
+ trust: "owner",
+ source: "fixture-owner-message",
+ kind: "deferral_card",
+ itemId:
+ scenario === "deferral-card-other-item" ? "other-item" : "def-001",
+ action: "remind",
+ }
+ : {
+ saidBy: "fixture-owner",
+ trust: "owner",
+ source: "fixture-owner-message",
+ },
],
[
"member",
@@ -609,6 +642,37 @@ it.live.each([
).toBe("Success");
return;
}
+ if (scenario === "deferral-plain-remind" || scenario === "deferral-card-other-item") {
+ const result = yield* writer
+ .stage(orgId, "wake1", {
+ path: "deferrals/def-001.md",
+ content: fixtureItem({ on_due: "remind" }),
+ sourceEventId: "owner",
+ })
+ .pipe(Effect.result);
+ expect(result._tag === "Failure" && result.failure._tag).toBe("MemoryConflict");
+ return;
+ }
+ if (scenario === "deferral-card-remind") {
+ const stage = (onDue: string) =>
+ writer
+ .stage(orgId, "wake1", {
+ path: "deferrals/def-001.md",
+ content: fixtureItem({ on_due: onDue }),
+ sourceEventId: "owner",
+ })
+ .pipe(Effect.result);
+ const forged = yield* stage("ask");
+ expect(forged._tag === "Failure" && forged.failure._tag).toBe("MemoryConflict");
+ expect((yield* stage("remind"))._tag).toBe("Success");
+ const committed = yield* writer.commitWakeup(orgId, "wake1", "completed");
+ expect(
+ yield* git(paths.writer, ["show", `${committed.commit}:deferrals/def-001.md`]),
+ ).toContain("on_due: remind");
+ const last = synced.at(-1)?.find((item) => item.id === "def-001");
+ expect(last?.on_due).toBe("remind");
+ return;
+ }
if (scenario.endsWith("-keep")) {
const content = fixtureItem({
kind: "claim",
diff --git a/apps/server/src/kin/memory/MemoryWriter.ts b/apps/server/src/kin/memory/MemoryWriter.ts
index 1a00cc70a83fc..6285503d6004a 100644
--- a/apps/server/src/kin/memory/MemoryWriter.ts
+++ b/apps/server/src/kin/memory/MemoryWriter.ts
@@ -47,6 +47,7 @@ export interface WakeupContext extends JournalContext {
readonly itemId: string;
readonly action: "keep" | "update" | "drop";
}
+ | { readonly kind: "deferral_card"; readonly itemId: string; readonly action: "remind" }
)
>;
}
@@ -532,10 +533,18 @@ const make = Effect.gen(function* () {
)
mutable.add("review_by");
if (
- Object.entries(item).some(
- ([key, value]) =>
+ source.kind === "deferral_card" &&
+ source.itemId === item.id &&
+ item.kind === "deferral" &&
+ fm.on_due === "remind"
+ )
+ mutable.add("on_due");
+ const existing = new Map(Object.entries(item));
+ if (
+ [...new Set([...existing.keys(), ...proposed.keys()])].some(
+ (key) =>
!mutable.has(key) &&
- JSON.stringify(value) !== JSON.stringify(proposed.get(key)),
+ JSON.stringify(existing.get(key)) !== JSON.stringify(proposed.get(key)),
)
)
return yield* new MemoryConflict({ existingId: item.id });
@@ -804,6 +813,16 @@ const make = Effect.gen(function* () {
recorded,
]);
yield* memory.record(orgId, branch, recorded, commit);
+ // Arms deferrals from the commit now, not at the next wake-up.
+ if (branch === (config.defaultBranch ?? "main"))
+ yield* memory.rebuildCache(orgId).pipe(
+ Effect.catch((error) =>
+ Effect.logWarning("Could not refresh memory cache after commit", {
+ orgId,
+ errorTag: error._tag,
+ }),
+ ),
+ );
yield* push(commit);
return { commit };
}),
diff --git a/apps/server/src/kin/persistence/KinMigrations.test.ts b/apps/server/src/kin/persistence/KinMigrations.test.ts
index 98163746ceca1..0877625fa90a5 100644
--- a/apps/server/src/kin/persistence/KinMigrations.test.ts
+++ b/apps/server/src/kin/persistence/KinMigrations.test.ts
@@ -21,6 +21,7 @@ const tableNames = [
"kin_chat_members",
"kin_chats",
"kin_cursor",
+ "kin_deferral_runs",
"kin_events",
"kin_floor_grants",
"kin_floor_notices",
@@ -108,6 +109,7 @@ describe("Kin migrations", () => {
{ migration_id: 13, name: "Routines" },
{ migration_id: 14, name: "LeadToolCalls" },
{ migration_id: 15, name: "AuthSessionKeys" },
+ { migration_id: 16, name: "DeferralRuns" },
]);
assert.deepStrictEqual(
upstreamBefore.map((row) => [row.migration_id, row.name] as const),
@@ -169,6 +171,7 @@ describe("Kin migrations", () => {
{ migration_id: 13, name: "Routines" },
{ migration_id: 14, name: "LeadToolCalls" },
{ migration_id: 15, name: "AuthSessionKeys" },
+ { migration_id: 16, name: "DeferralRuns" },
]);
assert.deepStrictEqual(yield* upstreamHistory, upstreamBefore);
assert.deepStrictEqual(yield* sql`SELECT * FROM kin_orgs`, [
@@ -255,6 +258,7 @@ describe("Kin migrations", () => {
[13, "Routines"],
[14, "LeadToolCalls"],
[15, "AuthSessionKeys"],
+ [16, "DeferralRuns"],
]);
const before = yield* kinSchema;
assert.deepStrictEqual(
@@ -283,6 +287,7 @@ describe("Kin migrations", () => {
yield* sql`DROP INDEX idx_kin_messages_changes`;
yield* sql`ALTER TABLE kin_messages DROP COLUMN change_seq`;
yield* sql`ALTER TABLE kin_chats DROP COLUMN change_seq`;
+ yield* sql`DROP TABLE kin_deferral_runs`;
yield* sql`DROP TABLE kin_auth_key_repairs`;
yield* sql`DROP TABLE kin_auth_session_keys`;
yield* sql`DROP TABLE kin_judge_log`;
@@ -317,6 +322,7 @@ describe("Kin migrations", () => {
[13, "Routines"],
[14, "LeadToolCalls"],
[15, "AuthSessionKeys"],
+ [16, "DeferralRuns"],
]);
assert.deepStrictEqual(
yield* sql`SELECT member_id FROM kin_chat_members WHERE org_id = 'org' ORDER BY member_id`,
@@ -357,6 +363,7 @@ describe("Kin migrations", () => {
{ migration_id: 13, name: "Routines" },
{ migration_id: 14, name: "LeadToolCalls" },
{ migration_id: 15, name: "AuthSessionKeys" },
+ { migration_id: 16, name: "DeferralRuns" },
]);
assert.deepStrictEqual(yield* runKinMigrations(), []);
assert.deepStrictEqual(yield* runMigrations(), []);
diff --git a/apps/server/src/kin/persistence/KinMigrations.ts b/apps/server/src/kin/persistence/KinMigrations.ts
index 47b195065a1c1..f93768bc7945a 100644
--- a/apps/server/src/kin/persistence/KinMigrations.ts
+++ b/apps/server/src/kin/persistence/KinMigrations.ts
@@ -18,6 +18,7 @@ import SecretAllow from "./migrations/K012_SecretAllow.ts";
import Routines from "./migrations/K013_Routines.ts";
import LeadToolCalls from "./migrations/K014_LeadToolCalls.ts";
import AuthSessionKeys from "./migrations/K015_AuthSessionKeys.ts";
+import DeferralRuns from "./migrations/K016_DeferralRuns.ts";
const run = Migrator.make({});
const loader = Migrator.fromRecord({
@@ -36,6 +37,7 @@ const loader = Migrator.fromRecord({
"13_Routines": Routines,
"14_LeadToolCalls": LeadToolCalls,
"15_AuthSessionKeys": AuthSessionKeys,
+ "16_DeferralRuns": DeferralRuns,
});
export const runKinMigrations = Effect.fn("KinMigrations.run")(function* () {
diff --git a/apps/server/src/kin/persistence/migrations/K016_DeferralRuns.ts b/apps/server/src/kin/persistence/migrations/K016_DeferralRuns.ts
new file mode 100644
index 0000000000000..f91ae1f6fbea4
--- /dev/null
+++ b/apps/server/src/kin/persistence/migrations/K016_DeferralRuns.ts
@@ -0,0 +1,17 @@
+import * as Effect from "effect/Effect";
+import * as SqlClient from "effect/sql/SqlClient";
+
+export default Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+ // TRIG-7 writes armed/disarmed; the due flow (TRIG-8) owns the remaining states.
+ yield* sql`CREATE TABLE kin_deferral_runs (
+ org_id TEXT NOT NULL REFERENCES kin_orgs(org_id),
+ item_id TEXT NOT NULL,
+ state TEXT NOT NULL,
+ due_at INTEGER CHECK (due_at IS NULL OR typeof(due_at) = 'integer'),
+ on_due TEXT NOT NULL CHECK (on_due IN ('remind', 'start', 'ask', 'chase')),
+ snapshot_json TEXT NOT NULL,
+ updated_at INTEGER NOT NULL CHECK (typeof(updated_at) = 'integer'),
+ PRIMARY KEY (org_id, item_id)
+ )`;
+});
diff --git a/apps/server/src/kin/triggers/KinTriggerService.test.ts b/apps/server/src/kin/triggers/KinTriggerService.test.ts
new file mode 100644
index 0000000000000..07fe4e79dee00
--- /dev/null
+++ b/apps/server/src/kin/triggers/KinTriggerService.test.ts
@@ -0,0 +1,325 @@
+import { assert, it } from "@effect/vitest";
+import {
+ KinChatId,
+ KinDeferralCard,
+ KinMemoryItemId,
+ KinOrgId,
+ KinPersonId,
+ KinWidgetId,
+ type MemoryItemHead,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import * as TestClock from "effect/testing/TestClock";
+
+import * as Sqlite from "../../persistence/Sqlite.ts";
+import * as Chat from "../chat/KinChatService.ts";
+import * as Hub from "../chat/KinChatHub.ts";
+import * as Repository from "../chat/KinChatRepository.ts";
+import * as JudgeShadow from "../floor/JudgeShadow.ts";
+import * as Memory from "../memory/Memory.ts";
+import * as Persistence from "../persistence/KinPersistence.ts";
+import * as TriggerService from "./KinTriggerService.ts";
+import { item, orgId, otherOrg, seed } from "./routines.testkit.ts";
+
+const decodeCard = Schema.decodeSync(Schema.fromJsonString(KinDeferralCard));
+const now = Date.parse("2026-11-09T09:00:00.000Z");
+const due = "2026-11-13T09:00+05:30";
+const dueAt = Date.parse("2026-11-13T03:30:00.000Z");
+
+const layer = TriggerService.syncHooksLayer.pipe(
+ Layer.provideMerge(TriggerService.layer),
+ Layer.provideMerge(
+ Chat.layer.pipe(Layer.provide(JudgeShadow.layerOff), Layer.provideMerge(Hub.layer)),
+ ),
+ Layer.provideMerge(Repository.layer),
+ Layer.provideMerge(Persistence.layer.pipe(Layer.provideMerge(Sqlite.layerMemory))),
+);
+
+const deferral = (overrides: Partial = {}) =>
+ item("def-1", {
+ kind: "deferral",
+ path: "deferrals/def-1.md",
+ due,
+ on_due: "start",
+ chat: KinChatId.make(`chat-${overrides.orgId ?? orgId}`),
+ ...overrides,
+ });
+
+const setup = Effect.fn("test.deferralSetup")(function* () {
+ yield* seed();
+ const sql = yield* SqlClient.SqlClient;
+ yield* sql`INSERT INTO kin_trigger_settings VALUES (${orgId}, 'Asia/Kolkata', '08:30', '18:30', '03:00', 0, 1, '09:00', '{"from":"21:00","to":"08:00"}')`;
+ yield* TestClock.setTime(now);
+ return { sql, service: yield* TriggerService.KinTriggerService };
+});
+
+const triggers = Effect.fn("test.deferralTriggers")(function* (org: string) {
+ const sql = yield* SqlClient.SqlClient;
+ return yield* sql<{
+ id: string;
+ enabled: number;
+ nextRunAt: number | null;
+ updatedAt: number;
+ }>`SELECT trigger_id AS id, enabled, next_run_at AS "nextRunAt", updated_at AS "updatedAt"
+ FROM kin_triggers WHERE org_id = ${org} ORDER BY trigger_id`;
+});
+
+const card = Effect.fn("test.deferralCard")(function* (org: string) {
+ const sql = yield* SqlClient.SqlClient;
+ const rows = yield* sql<{
+ revision: number;
+ state: string;
+ closedAt: string | null;
+ }>`SELECT revision, state_json AS state, closed_at AS "closedAt" FROM kin_widgets
+ WHERE org_id = ${org} AND type = 'deferral' ORDER BY widget_id`;
+ return rows.map((row) => ({ ...row, state: decodeCard(row.state) }));
+});
+
+it.effect("arms from front matter, re-arms on edits, and re-syncs without writes", () =>
+ Effect.gen(function* () {
+ const { sql, service } = yield* setup();
+ assert.equal(yield* service.syncItem(deferral()), "armed");
+ const armed = yield* triggers(orgId);
+ assert.deepEqual(
+ armed.map(({ id, enabled, nextRunAt }) => [id, enabled, nextRunAt]),
+ [
+ ["deferral:def-1:due", 1, dueAt],
+ ["deferral:def-1:heads_up", 1, dueAt - 30 * 60_000],
+ ],
+ );
+ const [posted] = yield* card(orgId);
+ assert.equal(posted?.state.text, "Deferred to Fri 13 Nov, 9:00. I'll start then.");
+ const [message] = yield* sql<{ body: string }>`SELECT body FROM kin_messages
+ WHERE org_id = ${orgId} AND kind = 'system' ORDER BY message_id`;
+ assert.equal(message?.body, posted?.state.text);
+
+ yield* TestClock.adjust("1 minute");
+ assert.equal(yield* service.syncItem(deferral()), "unchanged");
+ yield* sql`UPDATE kin_triggers SET next_run_at = NULL WHERE org_id = ${orgId} AND trigger_id = 'deferral:def-1:due'`;
+ assert.equal(yield* service.syncItem(deferral()), "unchanged");
+ assert.deepEqual(
+ (yield* triggers(orgId)).map(({ nextRunAt, updatedAt }) => [nextRunAt, updatedAt]),
+ [
+ [null, now],
+ [dueAt - 30 * 60_000, now],
+ ],
+ );
+ assert.equal((yield* card(orgId))[0]?.revision, 1);
+
+ const moved = "2026-11-16T09:00+05:30";
+ assert.equal(yield* service.syncItem(deferral({ due: moved })), "armed");
+ assert.deepEqual(
+ (yield* triggers(orgId)).map(({ nextRunAt }) => nextRunAt),
+ [Date.parse(moved), Date.parse(moved) - 30 * 60_000],
+ );
+ assert.equal(yield* service.syncItem(deferral({ due: moved, on_due: "remind" })), "armed");
+ assert.deepEqual(
+ (yield* triggers(orgId)).map(({ enabled, nextRunAt }) => [enabled, nextRunAt]),
+ [
+ [1, Date.parse(moved)],
+ [0, null],
+ ],
+ );
+ const [updated] = yield* card(orgId);
+ assert.equal(updated?.revision, 3);
+ assert.equal(updated?.state.text, "Deferred to Mon 16 Nov, 9:00. I'll remind you then.");
+ const [run] = yield* sql<{ state: string; dueAt: number; onDue: string }>`
+ SELECT state, due_at AS "dueAt", on_due AS "onDue" FROM kin_deferral_runs
+ WHERE org_id = ${orgId} ORDER BY item_id`;
+ assert.deepEqual(run, { state: "armed", dueAt: Date.parse(moved), onDue: "remind" });
+
+ // Same fires, different on_due: only the run row and card can tell them apart.
+ assert.equal(yield* service.syncItem(deferral({ due: moved, on_due: "ask" })), "armed");
+ const [asked] = yield* sql<{ onDue: string }>`SELECT on_due AS "onDue" FROM kin_deferral_runs
+ WHERE org_id = ${orgId} ORDER BY item_id`;
+ assert.equal(asked?.onDue, "ask");
+ assert.equal((yield* card(orgId))[0]?.state.onDue, "ask");
+
+ yield* sql`UPDATE kin_triggers SET schedule_json = 'not json'
+ WHERE org_id = ${orgId} AND trigger_id = 'deferral:def-1:due'`;
+ assert.equal(yield* service.syncItem(deferral({ due: moved, on_due: "ask" })), "armed");
+ assert.deepEqual(
+ (yield* triggers(orgId)).map(({ enabled, nextRunAt }) => [enabled, nextRunAt]),
+ [
+ [1, Date.parse(moved)],
+ [0, null],
+ ],
+ );
+ }).pipe(Effect.provide(layer)),
+);
+
+it.effect.each([
+ ["done", { status: "done" }],
+ ["cancelled", { status: "cancelled" }],
+ ["invalid_at", { invalid_at: "2026-11-09T09:00:00.000Z" }],
+ ["pre-1970", { due: "1969-12-31" }],
+ ["year-0", { due: "0000-01-01" }],
+ ["missing", undefined],
+] as const)("disarms on %s and re-arms when reopened", ([, overrides]) =>
+ Effect.gen(function* () {
+ const { sql, service } = yield* setup();
+ yield* service.syncItem(deferral());
+ if (overrides === undefined) yield* service.syncOrg(orgId, []);
+ else assert.equal(yield* service.syncItem(deferral(overrides)), "disarmed");
+ assert.deepEqual(
+ (yield* triggers(orgId)).map(({ enabled, nextRunAt }) => [enabled, nextRunAt]),
+ [
+ [0, null],
+ [0, null],
+ ],
+ );
+ assert.isNotNull((yield* card(orgId))[0]?.closedAt);
+ const [run] = yield* sql<{ state: string }>`SELECT state FROM kin_deferral_runs
+ WHERE org_id = ${orgId} ORDER BY item_id`;
+ assert.equal(run?.state, "disarmed");
+ assert.equal(
+ yield* service.syncItem(
+ overrides === undefined ? deferral({ status: "done" }) : deferral(overrides),
+ ),
+ "unchanged",
+ );
+
+ yield* service.syncOrg(orgId, [deferral()]);
+ assert.deepEqual(
+ (yield* triggers(orgId)).map(({ enabled }) => enabled),
+ [1, 1],
+ );
+ const [reopened] = yield* card(orgId);
+ assert.isNull(reopened?.closedAt);
+ assert.lengthOf(yield* card(orgId), 1);
+ }).pipe(Effect.provide(layer)),
+);
+
+it.effect("keeps organizations apart", () =>
+ Effect.gen(function* () {
+ const { sql, service } = yield* setup();
+ yield* service.syncItem(deferral());
+ yield* service.syncItem(deferral({ orgId: otherOrg }));
+ yield* service.syncOrg(orgId, [deferral({ orgId: otherOrg, status: "done" })]);
+ assert.deepEqual(
+ (yield* triggers(orgId)).map(({ enabled }) => enabled),
+ [0, 0],
+ );
+ assert.deepEqual(
+ (yield* triggers(otherOrg)).map(({ enabled }) => enabled),
+ [1, 1],
+ );
+ assert.equal((yield* card(otherOrg))[0]?.closedAt, null);
+
+ const foreign = item("def-foreign", {
+ kind: "deferral",
+ path: "deferrals/def-foreign.md",
+ due,
+ chat: KinChatId.make(`chat-${otherOrg}`),
+ });
+ assert.equal(yield* service.syncItem(foreign), "armed");
+ assert.lengthOf(
+ yield* sql`SELECT widget_id FROM kin_widgets WHERE org_id = ${orgId} AND state_json LIKE '%def-foreign%' ORDER BY widget_id`,
+ 0,
+ );
+ const unknown = yield* service
+ .syncItem(deferral({ orgId: KinOrgId.make("z") }))
+ .pipe(Effect.flip);
+ assert.equal(unknown._tag, "KinTriggerSyncError");
+ }).pipe(Effect.provide(layer)),
+);
+
+it.effect("syncs each head once, retries failures, and isolates failing items", () =>
+ Effect.gen(function* () {
+ const { sql } = yield* setup();
+ const hooks = yield* Memory.MemorySyncHooks;
+ const other = deferral({ id: KinMemoryItemId.make("def-2"), path: "deferrals/def-2.md" });
+ const snapshot = (
+ head: string,
+ items: ReadonlyArray,
+ duplicateIds: ReadonlyArray = [],
+ ) => ({
+ head,
+ items: items.map((head) => ({ head, body: "" })),
+ duplicateIds: new Set(duplicateIds),
+ });
+ const runs = () =>
+ sql<{ itemId: string; state: string }>`SELECT item_id AS "itemId", state
+ FROM kin_deferral_runs WHERE org_id = ${orgId} ORDER BY item_id`;
+ yield* sql`CREATE TRIGGER fail_def_1 BEFORE INSERT ON kin_deferral_runs
+ WHEN NEW.item_id = 'def-1' BEGIN SELECT RAISE(ABORT, 'fixture'); END`;
+ yield* hooks.syncItems(orgId, snapshot("h1", [deferral(), other]));
+ assert.deepEqual(yield* runs(), [{ itemId: "def-2", state: "armed" }]);
+
+ yield* sql`DROP TRIGGER fail_def_1`;
+ yield* hooks.syncItems(orgId, snapshot("h1", [deferral(), other]));
+ assert.deepEqual(yield* runs(), [
+ { itemId: "def-1", state: "armed" },
+ { itemId: "def-2", state: "armed" },
+ ]);
+ yield* sql`UPDATE kin_deferral_runs SET state = 'disarmed' WHERE org_id = ${orgId} AND item_id = 'def-2'`;
+ yield* hooks.syncItems(orgId, snapshot("h1", [deferral(), other]));
+ assert.equal((yield* runs())[1]?.state, "disarmed");
+
+ const copy = deferral({ path: "deferrals/def-1-copy.md" });
+ yield* hooks.syncItems(orgId, snapshot("h2", [deferral(), copy, other], ["def-1"]));
+ assert.deepEqual(yield* runs(), [
+ { itemId: "def-1", state: "disarmed" },
+ { itemId: "def-2", state: "armed" },
+ ]);
+ assert.deepEqual(
+ (yield* triggers(orgId)).map(({ id, enabled }) => [id, enabled]),
+ [
+ ["deferral:def-1:due", 0],
+ ["deferral:def-1:heads_up", 0],
+ ["deferral:def-2:due", 1],
+ ["deferral:def-2:heads_up", 1],
+ ],
+ );
+
+ const stuck = deferral({ id: KinMemoryItemId.make("def-3"), path: "deferrals/def-3.md" });
+ yield* sql`CREATE TRIGGER fail_def_3 BEFORE INSERT ON kin_deferral_runs
+ WHEN NEW.item_id = 'def-3' BEGIN SELECT RAISE(ABORT, 'fixture'); END`;
+ for (let attempt = 0; attempt < 3; attempt++)
+ yield* hooks.syncItems(orgId, snapshot("h3", [stuck, other]));
+ yield* sql`DROP TRIGGER fail_def_3`;
+ yield* hooks.syncItems(orgId, snapshot("h3", [stuck, other]));
+ assert.notInclude(
+ (yield* runs()).map(({ itemId }) => itemId),
+ "def-3",
+ "a head that failed three times is not retried",
+ );
+ yield* hooks.syncItems(orgId, snapshot("h4", [stuck, other]));
+ assert.include(
+ (yield* runs()).map(({ itemId }) => itemId),
+ "def-3",
+ );
+ }).pipe(Effect.provide(layer)),
+);
+
+it.effect("refuses deferral cards from the model and taps until the dispatcher lands", () =>
+ Effect.gen(function* () {
+ const { service } = yield* setup();
+ yield* service.syncItem(deferral());
+ const chat = yield* Chat.KinChatService;
+ const [posted] = yield* card(orgId);
+ const upsert = yield* chat
+ .upsertWidget(
+ { _tag: "person", orgId, personId: KinPersonId.make(`owner-${orgId}`) },
+ { chatId: KinChatId.make(`chat-${orgId}`), type: "deferral", state: posted!.state },
+ )
+ .pipe(Effect.flip);
+ assert.equal(upsert._tag === "KinChatError" && upsert.reason, "not_allowed");
+ const failure = yield* chat
+ .act(
+ { _tag: "person", orgId, personId: KinPersonId.make(`owner-${orgId}`) },
+ {
+ widgetId: KinWidgetId.make(`deferral:${orgId}:def-1`),
+ revision: 1,
+ actionId: "remind",
+ value: KinMemoryItemId.make("def-1"),
+ clientActionId: "remind",
+ },
+ )
+ .pipe(Effect.flip);
+ assert.equal(failure._tag === "KinChatError" && failure.reason, "not_allowed");
+ }).pipe(Effect.provide(layer)),
+);
diff --git a/apps/server/src/kin/triggers/KinTriggerService.ts b/apps/server/src/kin/triggers/KinTriggerService.ts
new file mode 100644
index 0000000000000..0a2c2949591ca
--- /dev/null
+++ b/apps/server/src/kin/triggers/KinTriggerService.ts
@@ -0,0 +1,402 @@
+import {
+ KinChatId,
+ type KinDeferralCard,
+ KinMemoryItemId,
+ KinMessageId,
+ KinOrgId,
+ KinTriggerSchedule,
+ KinTriggerSubject,
+ KinWidgetId,
+ type MemoryItemHead,
+} from "@t3tools/contracts";
+import * as Clock from "effect/Clock";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import { isSqlError } from "effect/sql/SqlError";
+
+import { toPersistenceSqlError } from "../../persistence/Errors.ts";
+import { KinChatHub } from "../chat/KinChatHub.ts";
+import * as Repository from "../chat/KinChatRepository.ts";
+import * as Memory from "../memory/Memory.ts";
+import * as MemoryCache from "../memory/MemoryCache.ts";
+import {
+ confirmText,
+ DeferralSnapshot,
+ deferralSnapshot,
+ deferralTriggerId,
+ deferralWidgetId,
+ planDeferral,
+ type DeferralPhase,
+ type DeferralPlan,
+} from "./deferrals.ts";
+
+export class KinTriggerSyncError extends Schema.TaggedError()(
+ "KinTriggerSyncError",
+ { orgId: KinOrgId, cause: Schema.Defect() },
+) {}
+
+type SyncItem = MemoryItemHead & { readonly duplicate?: boolean };
+export type SyncResult = "armed" | "disarmed" | "unchanged";
+
+export class KinTriggerService extends Context.Service<
+ KinTriggerService,
+ {
+ /** Upserts or disarms one deferral's triggers from its front matter. Idempotent. */
+ readonly syncItem: (item: SyncItem) => Effect.Effect;
+ /** Syncs a whole snapshot; armed deferrals missing from it are disarmed. */
+ readonly syncOrg: (
+ orgId: KinOrgId,
+ items: ReadonlyArray,
+ ) => Effect.Effect;
+ }
+>()("t3/kin/triggers/KinTriggerService") {}
+
+const phases: ReadonlyArray = ["heads_up", "due"];
+const disarmedPlan: DeferralPlan = { armed: false, dueAt: null, onDue: "remind", phases: [] };
+const encodeSchedule = Schema.encodeEffect(Schema.fromJsonString(KinTriggerSchedule));
+const decodeSchedule = Schema.decodeUnknownEffect(Schema.fromJsonString(KinTriggerSchedule));
+const encodeSubject = Schema.encodeEffect(Schema.fromJsonString(KinTriggerSubject));
+const encodeSnapshot = Schema.encodeEffect(Schema.fromJsonString(DeferralSnapshot));
+const iso = (ms: number) => DateTime.formatIso(DateTime.makeUnsafe(ms));
+
+interface StoredTrigger {
+ readonly runAt: number | undefined;
+ readonly enabled: boolean;
+ readonly nextRunAt: number | null;
+}
+interface Stored {
+ readonly run: { readonly state: string; readonly dueAt: number | null; readonly onDue: string };
+ readonly triggers: Map;
+}
+
+// A fired `once` keeps its runAt with next_run_at cleared; re-syncing must not refire it.
+const triggerCurrent = (runAt: number | undefined, row: StoredTrigger | undefined) =>
+ runAt === undefined
+ ? row === undefined || (!row.enabled && row.nextRunAt === null)
+ : row?.enabled === true && row.runAt === runAt;
+
+const isCurrent = (plan: DeferralPlan, stored: Stored | undefined) =>
+ phases.every((phase) =>
+ triggerCurrent(
+ plan.phases.find((entry) => entry.phase === phase)?.runAt,
+ stored?.triggers.get(phase),
+ ),
+ ) &&
+ (plan.armed
+ ? stored !== undefined &&
+ stored.run.state !== "disarmed" &&
+ stored.run.dueAt === plan.dueAt &&
+ stored.run.onDue === plan.onDue
+ : stored === undefined || stored.run.state === "disarmed");
+
+const make = Effect.gen(function* () {
+ const sql = yield* SqlClient.SqlClient;
+ const cache = yield* MemoryCache.MemoryCache;
+ const repo = yield* Repository.KinChatRepository;
+ const hub = yield* Effect.serviceOption(KinChatHub);
+ const publish = (event: Parameters[0]) =>
+ Option.isSome(hub) ? sql.afterCommit(hub.value.publish(event)) : Effect.void;
+
+ // Trigger rows are only written in the same transaction as their run row.
+ const readStored = Effect.fn("KinTriggerService.readStored")(function* (
+ orgId: KinOrgId,
+ itemId?: KinMemoryItemId,
+ ) {
+ const rows = yield* sql<{
+ itemId: string;
+ state: string;
+ dueAt: number | null;
+ onDue: string;
+ triggerId: string | null;
+ schedule: string | null;
+ enabled: number | null;
+ nextRunAt: number | null;
+ }>`
+ SELECT r.item_id AS "itemId", r.state, r.due_at AS "dueAt", r.on_due AS "onDue",
+ t.trigger_id AS "triggerId", t.schedule_json AS schedule,
+ t.enabled, t.next_run_at AS "nextRunAt"
+ FROM kin_deferral_runs r
+ LEFT JOIN kin_triggers t ON t.org_id = r.org_id
+ AND t.trigger_id IN ('deferral:' || r.item_id || ':heads_up', 'deferral:' || r.item_id || ':due')
+ WHERE r.org_id = ${orgId} ${itemId === undefined ? sql`` : sql`AND r.item_id = ${itemId}`}
+ ORDER BY r.item_id, t.trigger_id
+ `;
+ const stored = new Map();
+ for (const row of rows) {
+ let entry = stored.get(row.itemId);
+ if (entry === undefined) {
+ entry = {
+ run: { state: row.state, dueAt: row.dueAt, onDue: row.onDue },
+ triggers: new Map(),
+ };
+ stored.set(row.itemId, entry);
+ }
+ const phase = phases.find((each) => deferralTriggerId(row.itemId, each) === row.triggerId);
+ if (phase === undefined || row.schedule === null) continue;
+ // An undecodable row reads as stale, so the next apply overwrites it instead of failing the org.
+ const schedule = yield* decodeSchedule(row.schedule).pipe(Effect.option);
+ entry.triggers.set(phase, {
+ runAt:
+ Option.isSome(schedule) && schedule.value.type === "once"
+ ? Date.parse(schedule.value.runAt)
+ : Number.NaN,
+ enabled: row.enabled === 1,
+ nextRunAt: row.nextRunAt,
+ });
+ }
+ return stored;
+ });
+
+ const writeTrigger = Effect.fn("KinTriggerService.writeTrigger")(function* (
+ orgId: KinOrgId,
+ itemId: KinMemoryItemId,
+ phase: DeferralPhase,
+ runAt: number | undefined,
+ timeZone: string,
+ now: number,
+ ) {
+ const id = deferralTriggerId(itemId, phase);
+ if (runAt === undefined)
+ return yield* sql`UPDATE kin_triggers SET enabled = 0, next_run_at = NULL,
+ updated_at = max(updated_at, ${now}) WHERE org_id = ${orgId} AND trigger_id = ${id}`;
+ const schedule = yield* encodeSchedule({ type: "once", runAt: iso(runAt) });
+ const subject = yield* encodeSubject({ type: "deferral", itemId, phase });
+ const inserted = yield* sql`
+ INSERT INTO kin_triggers (trigger_id, org_id, subject_json, schedule_json, time_zone, enabled,
+ next_run_at, last_fire_id, created_at, updated_at)
+ VALUES (${id}, ${orgId}, ${subject}, ${schedule}, ${timeZone}, 1, ${runAt}, NULL, ${now}, ${now})
+ ON CONFLICT DO NOTHING RETURNING trigger_id
+ `;
+ if (inserted.length === 0)
+ yield* sql`UPDATE kin_triggers SET subject_json = ${subject}, schedule_json = ${schedule},
+ time_zone = ${timeZone}, enabled = 1, next_run_at = ${runAt},
+ updated_at = max(updated_at, ${now})
+ WHERE org_id = ${orgId} AND trigger_id = ${id}`;
+ });
+
+ const syncCard = Effect.fn("KinTriggerService.syncCard")(function* (
+ orgId: KinOrgId,
+ itemId: KinMemoryItemId,
+ item: SyncItem | undefined,
+ plan: DeferralPlan,
+ timeZone: string,
+ now: number,
+ ) {
+ const widgetId = KinWidgetId.make(deferralWidgetId(orgId, itemId));
+ const existing = yield* repo.getWidget({ orgId, widgetId });
+ const at = iso(now);
+ if (!plan.armed || plan.dueAt === null || item === undefined) {
+ if (Option.isNone(existing) || existing.value.closedAt !== null) return;
+ const widget = yield* repo.updateWidget({
+ ...existing.value,
+ expectedRevision: existing.value.revision,
+ closedAt: at,
+ updatedAt: at,
+ });
+ return yield* publish({ type: "widget.updated", orgId, widget });
+ }
+ const state: KinDeferralCard = {
+ itemId,
+ title: item.title,
+ dueAt: iso(plan.dueAt),
+ onDue: plan.onDue,
+ text: confirmText(plan.dueAt, plan.onDue, timeZone),
+ };
+ if (Option.isSome(existing)) {
+ const widget = yield* repo.updateWidget({
+ ...existing.value,
+ expectedRevision: existing.value.revision,
+ state,
+ closedAt: null,
+ updatedAt: at,
+ });
+ return yield* publish({ type: "widget.updated", orgId, widget });
+ }
+ // Only kin_defer items name a chat; other deferrals arm without a card.
+ if (item.chat === undefined) return;
+ const chatId = KinChatId.make(item.chat);
+ const [chat] = yield* sql`SELECT 1 FROM kin_chats
+ WHERE org_id = ${orgId} AND chat_id = ${chatId} ORDER BY chat_id`;
+ if (chat === undefined)
+ return yield* Effect.logWarning("Deferral chat is not in its organization", {
+ orgId,
+ itemId,
+ });
+ const message = yield* repo.insertMessage({
+ orgId,
+ chatId,
+ messageId: KinMessageId.make(widgetId),
+ author: { _tag: "system" },
+ kind: "system",
+ body: state.text,
+ intent: null,
+ mentions: [],
+ replyTo: null,
+ widgetId: null,
+ floorRunId: null,
+ status: "posted",
+ sentBy: null,
+ clientMessageId: null,
+ createdAt: at,
+ editedAt: null,
+ });
+ const widget = {
+ orgId,
+ chatId,
+ messageId: message.messageId,
+ widgetId,
+ widgetClass: "native" as const,
+ type: "deferral",
+ state,
+ source: null,
+ feed: null,
+ awaiting: [],
+ pinnedAt: null,
+ closedAt: null,
+ updatedAt: at,
+ };
+ yield* repo.insertWidget(widget);
+ yield* publish({ type: "message.posted", orgId, message });
+ yield* publish({ type: "widget.updated", orgId, widget: { ...widget, revision: 1 } });
+ });
+
+ const apply = Effect.fn("KinTriggerService.apply")(function* (
+ orgId: KinOrgId,
+ itemId: KinMemoryItemId,
+ item: SyncItem | undefined,
+ plan: DeferralPlan,
+ timeZone: string,
+ now: number,
+ ) {
+ return yield* sql.withTransaction(
+ Effect.gen(function* () {
+ const [org] = yield* sql`SELECT 1 FROM kin_orgs WHERE org_id = ${orgId} ORDER BY org_id`;
+ if (org === undefined) return yield* Effect.fail("unknown_org" as const);
+ const stored = (yield* readStored(orgId, itemId)).get(itemId);
+ if (isCurrent(plan, stored)) return "unchanged" as const;
+ for (const phase of phases) {
+ const runAt = plan.phases.find((entry) => entry.phase === phase)?.runAt;
+ if (!triggerCurrent(runAt, stored?.triggers.get(phase)))
+ yield* writeTrigger(orgId, itemId, phase, runAt, timeZone, now);
+ }
+ if (plan.armed && item !== undefined) {
+ const snapshot = yield* encodeSnapshot(deferralSnapshot(item));
+ const inserted = yield* sql`
+ INSERT INTO kin_deferral_runs (org_id, item_id, state, due_at, on_due, snapshot_json, updated_at)
+ VALUES (${orgId}, ${itemId}, 'armed', ${plan.dueAt}, ${plan.onDue}, ${snapshot}, ${now})
+ ON CONFLICT DO NOTHING RETURNING item_id
+ `;
+ if (inserted.length === 0)
+ yield* sql`UPDATE kin_deferral_runs SET state = 'armed', due_at = ${plan.dueAt},
+ on_due = ${plan.onDue}, snapshot_json = ${snapshot}, updated_at = ${now}
+ WHERE org_id = ${orgId} AND item_id = ${itemId}`;
+ } else
+ yield* sql`UPDATE kin_deferral_runs SET state = 'disarmed', updated_at = ${now}
+ WHERE org_id = ${orgId} AND item_id = ${itemId} AND state <> 'disarmed'`;
+ yield* syncCard(orgId, itemId, item, plan, timeZone, now);
+ return plan.armed ? ("armed" as const) : ("disarmed" as const);
+ }),
+ );
+ });
+
+ const wrap = (orgId: KinOrgId) =>
+ Effect.mapError(
+ (cause: unknown) =>
+ new KinTriggerSyncError({
+ orgId,
+ cause: isSqlError(cause) ? toPersistenceSqlError("KinTriggerService.sync")(cause) : cause,
+ }),
+ );
+
+ return KinTriggerService.of({
+ syncItem: Effect.fn("KinTriggerService.syncItem")(function* (item) {
+ if (item.kind !== "deferral") return "unchanged" as const;
+ const timeZone = yield* cache.ownerTimeZone(item.orgId);
+ const now = yield* Clock.currentTimeMillis;
+ return yield* apply(item.orgId, item.id, item, planDeferral(item), timeZone, now).pipe(
+ wrap(item.orgId),
+ );
+ }),
+ syncOrg: Effect.fn("KinTriggerService.syncOrg")(function* (orgId, items) {
+ const stored = yield* readStored(orgId).pipe(wrap(orgId));
+ const present = new Set();
+ const pending: Array = [];
+ for (const item of items) {
+ if (item.orgId !== orgId || item.kind !== "deferral") continue;
+ present.add(item.id);
+ const plan = planDeferral(item);
+ if (!isCurrent(plan, stored.get(item.id))) pending.push([item.id, item, plan]);
+ }
+ for (const [itemId, entry] of stored)
+ if (!present.has(itemId) && entry.run.state !== "disarmed")
+ pending.push([KinMemoryItemId.make(itemId), undefined, disarmedPlan]);
+ if (pending.length === 0) return;
+ const timeZone = yield* cache.ownerTimeZone(orgId);
+ const now = yield* Clock.currentTimeMillis;
+ const failures: Array = [];
+ for (const [itemId, item, plan] of pending)
+ yield* apply(orgId, itemId, item, plan, timeZone, now).pipe(
+ wrap(orgId),
+ Effect.catch((error) => {
+ failures.push(error);
+ return Effect.logWarning("Could not sync deferral", { orgId, itemId, cause: error });
+ }),
+ );
+ if (failures.length > 0) return yield* failures[0]!;
+ }),
+ });
+});
+
+export const layer = Layer.effect(KinTriggerService, make).pipe(Layer.provide(MemoryCache.layer));
+
+const maxSyncAttempts = 3;
+
+/** Arms deferrals from each new memory head; a failed sync retries on the next few loads. */
+export const syncHooksLayer = Layer.effect(
+ Memory.MemorySyncHooks,
+ Effect.gen(function* () {
+ const service = yield* KinTriggerService;
+ const syncedHeads = new Map();
+ const failedAttempts = new Map();
+ return {
+ syncItems: Effect.fn("KinTriggerService.syncItems")(function* (orgId, snapshot) {
+ if (syncedHeads.get(orgId) === snapshot.head) return;
+ const failed = failedAttempts.get(orgId);
+ const attempt = failed?.head === snapshot.head ? failed.count + 1 : 1;
+ yield* service
+ .syncOrg(
+ orgId,
+ snapshot.items.map(({ head }) => ({
+ ...head,
+ duplicate: snapshot.duplicateIds.has(head.id),
+ })),
+ )
+ .pipe(
+ Effect.tap(() =>
+ Effect.sync(() => {
+ syncedHeads.set(orgId, snapshot.head);
+ failedAttempts.delete(orgId);
+ }),
+ ),
+ Effect.catch((error) => {
+ // A permanent failure would otherwise rerun the sync inside the memory lock on every load.
+ const giveUp = attempt >= maxSyncAttempts;
+ if (giveUp) syncedHeads.set(orgId, snapshot.head);
+ else failedAttempts.set(orgId, { head: snapshot.head, count: attempt });
+ return Effect.logWarning(
+ giveUp
+ ? "Could not sync deferral triggers; skipping this head"
+ : "Could not sync deferral triggers; retrying on next load",
+ { orgId, attempt, cause: error },
+ );
+ }),
+ );
+ }),
+ };
+ }),
+);
diff --git a/apps/server/src/kin/triggers/deferrals.test.ts b/apps/server/src/kin/triggers/deferrals.test.ts
new file mode 100644
index 0000000000000..706d45c58f43c
--- /dev/null
+++ b/apps/server/src/kin/triggers/deferrals.test.ts
@@ -0,0 +1,172 @@
+import { assert, it } from "@effect/vitest";
+import {
+ KinAgentId,
+ KinChatId,
+ KinEvent,
+ KinEventId,
+ KinMemberId,
+ KinMessageId,
+ KinPersonId,
+ KinWakeupId,
+ KinWidgetId,
+} from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import * as TestClock from "effect/testing/TestClock";
+
+import * as Repository from "../chat/KinChatRepository.ts";
+import * as Queue from "../lead/KinEventQueue.ts";
+import * as MemoryWriter from "../memory/MemoryWriter.ts";
+import * as Deferrals from "./deferrals.ts";
+import * as TriggerService from "./KinTriggerService.ts";
+import { fixture, item, orgId, otherOrg, seed } from "./routines.testkit.ts";
+
+const encodeJson = Schema.encodeSync(Schema.fromJsonString(Schema.Unknown));
+const decodeEvent = Schema.decodeSync(KinEvent);
+const deferral = item("def-1", {
+ kind: "deferral",
+ path: "deferrals/def-1.md",
+ due: "2026-11-13T09:00+05:30",
+ on_due: "start",
+ chat: KinChatId.make("chat-a"),
+});
+const widgetId = KinWidgetId.make(`deferral:${orgId}:def-1`);
+
+it.effect("applies verified owner taps on the confirm card and ignores forged ones", () =>
+ Effect.gen(function* () {
+ yield* seed();
+ yield* TestClock.setTime(Date.parse("2026-11-09T09:00:00.000Z"));
+ const sql = yield* SqlClient.SqlClient;
+ const repo = yield* Repository.KinChatRepository;
+ const queue = yield* Queue.KinEventQueue;
+ const deferrals = yield* Deferrals.Deferrals;
+ yield* (yield* TriggerService.KinTriggerService).syncItem(deferral);
+ const staged: MemoryWriter.MemoryChange[] = [];
+ const writer = Layer.mock(MemoryWriter.MemoryWriter)({
+ stage: (_org, _wakeup, change) => Effect.sync(() => void staged.push(change)),
+ });
+ const tapOnce = Effect.fn("test.deferralTap")(function* (
+ actionId: string,
+ label: string,
+ target: KinWidgetId = widgetId,
+ ) {
+ const memberId = "owner-member-a";
+ // Stands in for the gated dispatcher: chat act refuses deferral taps today.
+ const message = yield* repo.insertMessage({
+ orgId,
+ chatId: KinChatId.make("chat-a"),
+ messageId: KinMessageId.make(`tap-${actionId}-${label}`),
+ author: {
+ _tag: "human",
+ personId: KinPersonId.make("owner-a"),
+ memberId: KinMemberId.make(memberId),
+ },
+ kind: "widget_action",
+ body: encodeJson({ widgetId: target, revision: 1, actionId, value: "def-1" }),
+ intent: null,
+ mentions: [],
+ replyTo: KinMessageId.make(target),
+ widgetId: target,
+ floorRunId: null,
+ status: "posted",
+ sentBy: KinPersonId.make("owner-a"),
+ clientMessageId: { kind: "act", id: `${actionId}-${label}` },
+ createdAt: "2026-11-09T09:00:00.000Z",
+ editedAt: null,
+ });
+ const eventId = `${actionId}-${label}`;
+ yield* queue.enqueue(
+ decodeEvent({
+ _tag: "widget.action",
+ orgId,
+ eventId,
+ agentId: "lead-a",
+ receivedAt: "2026-11-09T09:00:00.000Z",
+ dedupeKey: eventId,
+ provenance: { _tag: "human", personId: "owner-a", memberId },
+ chatId: "chat-a",
+ messageId: message.messageId,
+ actionId,
+ }),
+ );
+ yield* TestClock.adjust("20 seconds");
+ const wakeupId = KinWakeupId.make(`wake-${eventId}`);
+ yield* queue.claim({ orgId, agentId: KinAgentId.make("lead-a"), wakeupId, model: "fixture" });
+ if (label === "demoted")
+ yield* sql`UPDATE kin_chat_members SET role = 'member' WHERE org_id = ${orgId} AND member_id = ${memberId}`;
+ const result = yield* deferrals
+ .act(orgId, wakeupId, KinEventId.make(eventId))
+ .pipe(Effect.provide(writer), Effect.result);
+ const forged = yield* deferrals
+ .act(otherOrg, wakeupId, KinEventId.make(eventId))
+ .pipe(Effect.provide(writer), Effect.flip);
+ assert.equal(forged._tag, "DeferralError");
+ yield* queue.finish({ orgId, wakeupId, status: "completed" });
+ return result;
+ });
+ const tap = (actionId: string, label: string, target?: KinWidgetId) =>
+ Effect.scoped(tapOnce(actionId, label, target));
+
+ const remind = yield* tap("remind", "owner");
+ assert.equal(remind._tag === "Success" && remind.success.action, "remind");
+ assert.lengthOf(staged, 1);
+ assert.equal(staged[0]?.sourceEventId, "remind-owner");
+ assert.include(staged[0]!.content, "on_due: remind");
+
+ const change = yield* tap("change", "owner");
+ assert.equal(change._tag === "Success" && change.success.action, "change");
+ assert.lengthOf(staged, 1);
+
+ const real = Option.getOrThrow(yield* repo.getWidget({ orgId, widgetId }));
+ const forgedId = KinWidgetId.make("model-card");
+ const anchor = yield* repo.insertMessage({
+ orgId,
+ chatId: real.chatId,
+ messageId: KinMessageId.make(forgedId),
+ author: { _tag: "system" },
+ kind: "system",
+ body: "",
+ intent: null,
+ mentions: [],
+ replyTo: null,
+ widgetId: null,
+ floorRunId: null,
+ status: "posted",
+ sentBy: null,
+ clientMessageId: null,
+ createdAt: "2026-11-09T09:00:00.000Z",
+ editedAt: null,
+ });
+ yield* repo.insertWidget({
+ orgId,
+ chatId: real.chatId,
+ messageId: anchor.messageId,
+ widgetId: forgedId,
+ widgetClass: "native",
+ type: "deferral",
+ state: real.state,
+ source: null,
+ feed: null,
+ awaiting: [],
+ pinnedAt: null,
+ closedAt: null,
+ updatedAt: "2026-11-09T09:00:00.000Z",
+ });
+ assert.equal((yield* tap("remind", "forged", forgedId))._tag, "Failure");
+ assert.lengthOf(staged, 1);
+
+ const member = yield* tap("remind", "demoted");
+ assert.equal(member._tag, "Failure");
+ assert.lengthOf(staged, 1);
+ }).pipe(
+ Effect.provide(
+ Deferrals.layer.pipe(
+ Layer.provideMerge(TriggerService.layer),
+ Layer.provideMerge(fixture([deferral])),
+ ),
+ ),
+ ),
+);
diff --git a/apps/server/src/kin/triggers/deferrals.ts b/apps/server/src/kin/triggers/deferrals.ts
new file mode 100644
index 0000000000000..a90798dab3ef9
--- /dev/null
+++ b/apps/server/src/kin/triggers/deferrals.ts
@@ -0,0 +1,166 @@
+import {
+ KinChatId,
+ KinDeferralCard,
+ KinEventId,
+ KinMemoryItemId,
+ KinOrgId,
+ KinTriggerId,
+ type MemoryItemHead,
+} from "@t3tools/contracts";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as SqlClient from "effect/sql/SqlClient";
+import { stringify } from "yaml";
+
+import * as Repository from "../chat/KinChatRepository.ts";
+import * as Memory from "../memory/Memory.ts";
+import * as MemoryWriter from "../memory/MemoryWriter.ts";
+import { memoryDateMillis } from "../memory/frontMatter.ts";
+import { deferralCardActions } from "../widgets/deferralCard.ts";
+import { verifyOwnerTap } from "./ownerCheck.ts";
+
+const HEADS_UP_MS = 30 * 60_000;
+export type OnDue = KinDeferralCard["onDue"];
+export type DeferralPhase = "heads_up" | "due";
+
+export interface DeferralPlan {
+ readonly armed: boolean;
+ readonly dueAt: number | null;
+ readonly onDue: OnDue;
+ readonly phases: ReadonlyArray<{ readonly phase: DeferralPhase; readonly runAt: number }>;
+}
+
+export const deferralTriggerId = (itemId: string, phase: DeferralPhase) =>
+ KinTriggerId.make(`deferral:${itemId}:${phase}`);
+export const deferralWidgetId = (orgId: string, itemId: string) => `deferral:${orgId}:${itemId}`;
+
+// A deferral without on_due only reminds: silence never starts work. Pre-epoch run
+// times would fail every scheduler tick, so they leave the item unarmed.
+export function planDeferral(
+ item: MemoryItemHead & { readonly duplicate?: boolean },
+): DeferralPlan {
+ const onDue = item.on_due ?? "remind";
+ const due = memoryDateMillis(item.due);
+ const dueAt = Number.isFinite(due) ? due : null;
+ const armed =
+ item.kind === "deferral" &&
+ item.status === "open" &&
+ item.invalid_at === null &&
+ item.superseded_by === null &&
+ item.duplicate !== true &&
+ dueAt !== null;
+ if (!armed || dueAt === null) return { armed: false, dueAt, onDue, phases: [] };
+ const dueFire = { phase: "due" as const, runAt: dueAt };
+ const phases: DeferralPlan["phases"] =
+ onDue === "start" ? [{ phase: "heads_up", runAt: dueAt - HEADS_UP_MS }, dueFire] : [dueFire];
+ if (phases.some(({ runAt }) => runAt < 0)) return { armed: false, dueAt, onDue, phases: [] };
+ return { armed, dueAt, onDue, phases };
+}
+
+/** The item half of the recheck baseline; TRIG-8 adds the GitHub half. */
+export const DeferralSnapshot = Schema.Struct({
+ recordedAt: Schema.String,
+ supersededBy: Schema.NullOr(KinMemoryItemId),
+ links: Schema.Array(Schema.String),
+});
+export const deferralSnapshot = (item: MemoryItemHead): typeof DeferralSnapshot.Type => ({
+ recordedAt: item.recorded_at,
+ supersededBy: item.superseded_by,
+ links: item.links,
+});
+
+const then: Record = {
+ start: "I'll start then.",
+ remind: "I'll remind you then.",
+ ask: "I'll ask you then.",
+ chase: "I'll chase it then.",
+};
+
+export function confirmText(dueAt: number, onDue: OnDue, timeZone: string): string {
+ const parts = Object.fromEntries(
+ new Intl.DateTimeFormat("en-GB", {
+ timeZone,
+ weekday: "short",
+ day: "numeric",
+ month: "short",
+ hour: "numeric",
+ minute: "2-digit",
+ hourCycle: "h23",
+ })
+ .formatToParts(dueAt)
+ .map((part) => [part.type, part.value]),
+ );
+ return `Deferred to ${parts.weekday} ${parts.day} ${parts.month}, ${Number(parts.hour)}:${parts.minute}. ${then[onDue]}`;
+}
+
+export class DeferralError extends Schema.TaggedError()("DeferralError", {
+ orgId: KinOrgId,
+ cause: Schema.Defect(),
+}) {}
+
+const decodeCard = Schema.decodeUnknownEffect(KinDeferralCard);
+const decodeAction = Schema.decodeUnknownEffect(
+ Schema.Struct({ actionId: Schema.Literals(deferralCardActions), value: KinMemoryItemId }),
+);
+
+export class Deferrals extends Context.Service<
+ Deferrals,
+ {
+ /** Applies a verified owner tap on a deferral card. [Change] hands the item to the lead. */
+ readonly act: (
+ orgId: KinOrgId,
+ wakeupId: string,
+ eventId: KinEventId,
+ ) => Effect.Effect<
+ {
+ readonly chatId: KinChatId;
+ readonly itemId: KinMemoryItemId;
+ readonly action: (typeof deferralCardActions)[number];
+ },
+ DeferralError,
+ MemoryWriter.MemoryWriter
+ >;
+ }
+>()("t3/kin/triggers/deferrals") {}
+
+const make = Effect.gen(function* () {
+ const memory = yield* Memory.Memory;
+ const sql = yield* SqlClient.SqlClient;
+ const repo = yield* Repository.KinChatRepository;
+ return Deferrals.of({
+ act: Effect.fn("Deferrals.act")((orgId, wakeupId, eventId) =>
+ Effect.gen(function* () {
+ const writer = yield* MemoryWriter.MemoryWriter;
+ const tap = yield* verifyOwnerTap(orgId, wakeupId, eventId, "deferral").pipe(
+ Effect.provideService(SqlClient.SqlClient, sql),
+ Effect.provideService(Repository.KinChatRepository, repo),
+ );
+ const action = yield* decodeAction(tap.action);
+ const card = yield* decodeCard(tap.widget.state);
+ if (
+ card.itemId !== action.value ||
+ tap.widget.widgetId !== deferralWidgetId(orgId, card.itemId)
+ )
+ return yield* Effect.fail("unknown_item" as const);
+ if (action.actionId === "remind") {
+ const item = yield* memory.readItemQuietly(orgId, card.itemId);
+ if (item.head.kind !== "deferral" || item.head.status !== "open")
+ return yield* Effect.fail("not_open" as const);
+ if (item.head.on_due !== "remind") {
+ const { orgId: _org, path, ...frontMatter } = item.head;
+ yield* writer.stage(orgId, wakeupId, {
+ path,
+ content: `---\n${stringify({ ...frontMatter, on_due: "remind" })}---\n${item.body}`,
+ sourceEventId: eventId,
+ });
+ }
+ }
+ return { chatId: tap.chatId, itemId: card.itemId, action: action.actionId };
+ }).pipe(Effect.mapError((cause) => new DeferralError({ orgId, cause }))),
+ ),
+ });
+});
+
+export const layer = Layer.effect(Deferrals, make);
diff --git a/apps/server/src/kin/triggers/ownerCheck.ts b/apps/server/src/kin/triggers/ownerCheck.ts
index f31102d5990c0..d554c4d7d843b 100644
--- a/apps/server/src/kin/triggers/ownerCheck.ts
+++ b/apps/server/src/kin/triggers/ownerCheck.ts
@@ -37,12 +37,20 @@ type Selection = typeof Selection.Type;
const decodeCard = Schema.decodeUnknownEffect(KinOwnerCheckCard);
const decodeEvent = Schema.decodeUnknownEffect(Schema.fromJsonString(KinEvent));
const decodeAction = Schema.decodeUnknownEffect(
+ Schema.Struct({
+ widgetId: KinWidgetId,
+ revision: Schema.Int,
+ actionId: Schema.Literals(["keep", "update", "drop"]),
+ value: KinMemoryItemId,
+ }),
+);
+const decodeTap = Schema.decodeUnknownEffect(
Schema.fromJsonString(
Schema.Struct({
widgetId: KinWidgetId,
revision: Schema.Int,
- actionId: Schema.Literals(["keep", "update", "drop"]),
- value: KinMemoryItemId,
+ actionId: Schema.String,
+ value: Schema.optional(Schema.Unknown),
}),
),
);
@@ -95,6 +103,66 @@ export function pickOwnerCheckItems(
.map(({ item, rank }) => ({ itemId: item.id, reason: reasons[rank] ?? "no_evidence" }));
}
+/** Verifies a claimed widget tap as the org owner's own action on an open card of `type`. */
+export const verifyOwnerTap = Effect.fn("OwnerCheck.verifyOwnerTap")(function* (
+ orgId: KinOrgId,
+ wakeupId: string,
+ eventId: KinEventId,
+ type: string,
+) {
+ const sql = yield* SqlClient.SqlClient;
+ const repo = yield* Repository.KinChatRepository;
+ return yield* sql
+ .withTransaction(
+ Effect.gen(function* () {
+ const [row] = yield* sql<{
+ json: string;
+ }>`SELECT e.json FROM kin_events e JOIN kin_wakeups w ON w.org_id = e.org_id AND w.wakeup_id = e.wakeup_id WHERE e.org_id = ${orgId} AND e.event_id = ${eventId} AND e.wakeup_id = ${wakeupId} AND e.state = 'claimed' AND w.status = 'running' ORDER BY e.event_id`;
+ if (row === undefined) return yield* Effect.fail("unclaimed_action" as const);
+ const event = yield* decodeEvent(row.json);
+ if (
+ event.orgId !== orgId ||
+ event.eventId !== eventId ||
+ event._tag !== "widget.action" ||
+ event.provenance._tag !== "human"
+ )
+ return yield* Effect.fail("not_owner" as const);
+ const message = yield* repo.getMessage({ orgId, messageId: event.messageId });
+ if (
+ Option.isNone(message) ||
+ message.value.chatId !== event.chatId ||
+ message.value.kind !== "widget_action" ||
+ message.value.authorRole !== "owner" ||
+ message.value.author._tag !== "human" ||
+ message.value.author.personId !== event.provenance.personId ||
+ message.value.author.memberId !== event.provenance.memberId
+ )
+ return yield* Effect.fail("not_owner" as const);
+ const owners =
+ yield* sql`SELECT m.member_id FROM kin_chat_members m JOIN kin_agents a ON a.org_id = m.org_id AND a.owner_person_id = m.person_id WHERE m.org_id = ${orgId} AND m.member_id = ${event.provenance.memberId} AND m.chat_id = ${event.chatId} AND m.person_id = ${event.provenance.personId} AND m.role = 'owner' AND m.left_at IS NULL AND a.agent_id = ${event.agentId} AND a.retired_at IS NULL ORDER BY m.member_id`;
+ if (owners.length === 0) return yield* Effect.fail("not_owner" as const);
+ const action = yield* decodeTap(message.value.body);
+ const widget = yield* repo.getWidget({ orgId, widgetId: action.widgetId });
+ if (
+ Option.isNone(widget) ||
+ widget.value.type !== type ||
+ widget.value.chatId !== event.chatId ||
+ message.value.widgetId !== action.widgetId ||
+ widget.value.closedAt !== null ||
+ widget.value.revision !== action.revision ||
+ event.actionId !== action.actionId
+ )
+ return yield* Effect.fail("invalid_card" as const);
+ return { action, chatId: event.chatId, widget: widget.value };
+ }),
+ )
+ .pipe(
+ Effect.mapError((cause) =>
+ isSqlError(cause) ? toPersistenceSqlError("OwnerCheck.verifyOwnerTap")(cause) : cause,
+ ),
+ );
+});
+
export class OwnerCheckError extends Schema.TaggedError()("OwnerCheckError", {
orgId: KinOrgId,
cause: Schema.Defect(),
@@ -233,62 +301,17 @@ const make = Effect.gen(function* () {
orgId,
Effect.gen(function* () {
const writer = yield* MemoryWriter.MemoryWriter;
- const verified = yield* sql
- .withTransaction(
- Effect.gen(function* () {
- const [row] = yield* sql<{
- json: string;
- }>`SELECT e.json FROM kin_events e JOIN kin_wakeups w ON w.org_id = e.org_id AND w.wakeup_id = e.wakeup_id WHERE e.org_id = ${orgId} AND e.event_id = ${eventId} AND e.wakeup_id = ${wakeupId} AND e.state = 'claimed' AND w.status = 'running' ORDER BY e.event_id`;
- if (row === undefined) return yield* Effect.fail("unclaimed_action");
- const event = yield* decodeEvent(row.json);
- if (
- event.orgId !== orgId ||
- event.eventId !== eventId ||
- event._tag !== "widget.action" ||
- event.provenance._tag !== "human"
- )
- return yield* Effect.fail("not_owner");
- const message = yield* repo.getMessage({ orgId, messageId: event.messageId });
- if (
- Option.isNone(message) ||
- message.value.chatId !== event.chatId ||
- message.value.kind !== "widget_action" ||
- message.value.authorRole !== "owner" ||
- message.value.author._tag !== "human" ||
- message.value.author.personId !== event.provenance.personId ||
- message.value.author.memberId !== event.provenance.memberId
- )
- return yield* Effect.fail("not_owner");
- const owners =
- yield* sql`SELECT m.member_id FROM kin_chat_members m JOIN kin_agents a ON a.org_id = m.org_id AND a.owner_person_id = m.person_id WHERE m.org_id = ${orgId} AND m.member_id = ${event.provenance.memberId} AND m.chat_id = ${event.chatId} AND m.person_id = ${event.provenance.personId} AND m.role = 'owner' AND m.left_at IS NULL AND a.agent_id = ${event.agentId} AND a.retired_at IS NULL ORDER BY m.member_id`;
- if (owners.length === 0) return yield* Effect.fail("not_owner");
- const action = yield* decodeAction(message.value.body);
- const widget = yield* repo.getWidget({ orgId, widgetId: action.widgetId });
- if (
- Option.isNone(widget) ||
- widget.value.type !== "owner_check" ||
- widget.value.chatId !== event.chatId ||
- message.value.widgetId !== action.widgetId ||
- widget.value.closedAt !== null ||
- widget.value.revision !== action.revision ||
- event.actionId !== action.actionId
- )
- return yield* Effect.fail("invalid_card");
- const card = yield* decodeCard(widget.value.state);
- if (
- !card.items.some(
- (item) => item.itemId === action.value && item.handled === undefined,
- )
- )
- return yield* Effect.fail("unknown_item");
- return { action, chatId: event.chatId, widget: widget.value, card };
- }),
- )
- .pipe(
- Effect.mapError((cause) =>
- isSqlError(cause) ? toPersistenceSqlError("OwnerCheck.act")(cause) : cause,
- ),
- );
+ const tap = yield* verifyOwnerTap(orgId, wakeupId, eventId, "owner_check").pipe(
+ Effect.provideService(SqlClient.SqlClient, sql),
+ Effect.provideService(Repository.KinChatRepository, repo),
+ );
+ const action = yield* decodeAction(tap.action);
+ const card = yield* decodeCard(tap.widget.state);
+ if (
+ !card.items.some((item) => item.itemId === action.value && item.handled === undefined)
+ )
+ return yield* Effect.fail("unknown_item");
+ const verified = { action, chatId: tap.chatId, widget: tap.widget, card };
const item = yield* memory.readItemQuietly(orgId, verified.action.value);
if (verified.action.actionId !== "update") {
const { orgId: _org, path, ...frontMatter } = item.head;
diff --git a/apps/server/src/kin/widgets/deferralCard.ts b/apps/server/src/kin/widgets/deferralCard.ts
new file mode 100644
index 0000000000000..c0e644b6879a4
--- /dev/null
+++ b/apps/server/src/kin/widgets/deferralCard.ts
@@ -0,0 +1,4 @@
+// Taps need the owner-tap dispatcher that also gates the owner check; see the
+// deferral card release gate in docs/kin/specs/triggers.md.
+export const deferralCardActionsReady = false;
+export const deferralCardActions = ["change", "remind"] as const;
diff --git a/apps/server/src/kin/widgets/registry.ts b/apps/server/src/kin/widgets/registry.ts
index 31b038ab429bf..e4da474d02201 100644
--- a/apps/server/src/kin/widgets/registry.ts
+++ b/apps/server/src/kin/widgets/registry.ts
@@ -1,10 +1,16 @@
-import { KinChatError, KinTaskCardState, KinOwnerCheckCard } from "@t3tools/contracts";
+import {
+ KinChatError,
+ KinDeferralCard,
+ KinTaskCardState,
+ KinOwnerCheckCard,
+} from "@t3tools/contracts";
import * as Effect from "effect/Effect";
import * as Schema from "effect/Schema";
const schemas = new Map>([
["task", KinTaskCardState],
["owner_check", KinOwnerCheckCard],
+ ["deferral", KinDeferralCard],
]);
export const validateState = Effect.fn("KinWidgetRegistry.validateState")(function* (
diff --git a/docs/kin/specs/triggers.md b/docs/kin/specs/triggers.md
index 69d876d00f1e1..4ff8bdfa62299 100644
--- a/docs/kin/specs/triggers.md
+++ b/docs/kin/specs/triggers.md
@@ -113,7 +113,7 @@ Defaults: brief 08:30 daily, summary 18:30 Mon–Fri, dream 03:00 daily, full re
| Kind | Late policy (decided by the consumer, using `lateByMs` and owner time) |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Deferral `heads_up` | If `due` has also passed, skip the heads-up and handle `due` as late. |
-| Deferral `due` | Run the due flow with "This was due at 9:00"; the grace starts from now. |
+| Deferral `due` | Within the 30-minute grace, run the due flow with "This was due at 9:00"; the grace starts from now. Older fires ask, never start. |
| Reminder, follow-up | Deliver with "This was due at …". Pings respect quiet hours. |
| Morning brief | Post if before the evening summary time; otherwise fold into the evening summary. |
| Evening summary | Post if before the next dream; otherwise fold into the next morning brief. |
@@ -203,9 +203,20 @@ Arming comes from memory. When the front-matter cache (LEAD) sees a `deferrals/*
| `ask` | `due` only | post a decision card |
| `chase` | `due` only | ping the promiser (ping rules) |
-Item edits move or disarm the triggers: a new `due` re-arms; `status` other than `open` or a set `invalid_at` disables them. A due time already past at save fires at once, marked late; no "pick a future time" error.
+Item edits move or disarm the triggers: a new `due` re-arms; `status` other than `open` or a set `invalid_at` disables them. A due time already past at save fires at once, marked late; no "pick a future time" error. A missing `on_due` means `remind`, so silence never starts work.
-**Confirm.** When the lead calls `kin_defer` (LEAD), Kin writes the item, arms the triggers, and the lead posts a `KinDeferralCard` widget (CHAT envelope): "Deferred to Fri 13 Nov, 9:00. I'll start then." [Change] [Just remind me]. [Just remind me] sets `on_due: remind`, and the triggers re-arm.
+The cache hook is `MemorySyncHooks` in [`Memory.ts`](../../../apps/server/src/kin/memory/Memory.ts): each new head goes once to `KinTriggerService.syncOrg`, which also disarms armed deferrals missing from the snapshot or sharing a duplicate id. A failing item is logged without blocking the others, and the head retries on the next two loads, then waits for the next head. The deferral `trigger_reconcile` described below is not built yet, so until it is, a new head is the only recovery. A due time whose fires would land before 1970 never arms; `kin_defer` accepts only years 2000–2099. A commit to the default branch moves the cache to the new head and reloads it, so a `kin_defer` item arms when its wake-up commits, not at the next wake-up; shadow (L0) commits never arm. Trigger ids are `deferral::heads_up|due`. Re-syncing an unchanged `due` writes nothing, so a fired `once` is never re-armed. The run row in `kin_deferral_runs` (migration K016) holds the snapshot and an `armed`/`disarmed` state; TRIG-8 owns the due-flow states. The snapshot holds the item half only (`recorded_at`, `superseded_by`, links). There is no GitHub reader in Kin yet, so TRIG-8 must add the GitHub half (issue/PR state, assignees, linked PRs) at arm time before the due flow ships.
+
+**Confirm.** When the lead calls `kin_defer` (LEAD), Kin writes the item, arms the triggers, and the lead posts a `KinDeferralCard` widget (CHAT envelope): "Deferred to Fri 13 Nov, 9:00. I'll start then." [Change] [Just remind me]. [Just remind me] sets `on_due: remind`, and the triggers re-arm. [Change] writes nothing: it hands the item to the lead, which asks the owner what to change, marks the old item `cancelled` and calls `kin_defer` for the new one.
+
+Code posts the card, never the model. It goes to the item's `chat` when that chat belongs to the item's org; deferrals without a chat arm without a card. Times use the owner's zone. A re-arm updates the card text in place, a disarm closes the card, and reopening the item reopens it. The card awaits nobody.
+
+**Deferral card release gate (TRIG-7):** cards post live, but `KinChatService.act` refuses deferral-card taps (`deferralCardActionsReady = false`) until the owner-tap dispatcher from the owner-check gate exists. `Deferrals.act` already verifies the tap with the same `verifyOwnerTap` as the owner check. Before enabling taps:
+
+- the owner-check gate's dispatcher steps must land (chat act enqueues `widget.action`; `WakeupRunner` intercepts card actions without showing them to the model);
+- `WakeupRunner` must run `Deferrals.act` for `deferral` actions, then `MemoryWriter.commitWakeup` (the commit re-arms through the cache hook), then queue `finish`. [Change] goes to the lead as an owner message about the item;
+- production `MemoryWriterAuthority.resolve` must grant `kind: "deferral_card"` (item id, action `remind`) only after verifying the claimed owner tap. With that grant, the writer lets `on_due` change, and only to `remind`;
+- web and mobile must render the native card and its closed state.
**Flow for `start`** (`kin_deferral_runs.state`):
@@ -223,7 +234,8 @@ armed ──heads_up fire──▶ recheck ──changed──▶ asked (decis
```
- **The recheck is code.** It runs `gh api` reads for every GitHub link plus a read of the memory item. Any difference from the snapshot means "changed": an issue closed, an assignee added, another linked PR, or the item superseded. The ask then names what changed.
-- **Late.** If the machine woke after `due`, the `heads_up` fire is skipped. The `due` fire posts the same card with "This was due at 9:00" and a 30-minute grace from now; silence still means go.
+- **Late.** If the machine woke after `due`, the `heads_up` fire is skipped. A `due` fire within the 30-minute grace window posts the same card with "This was due at 9:00" and a grace from now; silence still means go. An older fire asks instead of starting.
+- **Stale fires.** Fires wait in the inbox until TRIG-8 consumes them. TRIG-8 drops a fire whose run row is `disarmed` or whose `due_at` no longer equals the fire's due instant.
- **Level and stop switch.** Below L2, or with the org's stop switch on, `start` becomes `ask`. Silence never starts work then.
- **Idempotent start.** Starting is a Work-class action keyed by `fireId`, so a replay can't start two workers.
- **Bring it up early.** When a message touches the topic before the due time, the lead mentions it (LEAD, using the cache). The Monday morning brief lists deferrals due this week.
@@ -501,7 +513,7 @@ Kin runs on one always-on machine, the **Kin host**. The laptop and phone are cl
- **Scheduler:** a deferral due 09:00 +05:30 fires once at 09:00. Two ticks at the same instant give one inbox row. Advancing the clock 10 h with the scheduler stopped, then starting it, gives one inbox fire with `lateByMs = 10 h`; the deferral consumer (TRIG-8) posts the "This was due at 9:00" card. Recurring downtime emits one stored slot, not every missed occurrence.
- **Timezone:** with the server zone `UTC` and the org zone `Asia/Kolkata`, the dream fires at 21:30 UTC. A 09:00 routine in `America/New_York` stays at 09:00 across both DST transitions; weekdays are owner-local. Two orgs with different zones fire independently; changing one org's zone or routine times recomputes only its schedules.
- **Sink:** a signed GitHub `pull_request` request through the real `ScheduledTaskService` gives exactly one inbox row and no thread launch. A replay gives `duplicate` and no new row. A bot-sender request gives `filtered`. A non-Kin task still launches normally.
-- **Deferral:** unchanged recheck, then heads-up, then silence, then `started` at due. A linked issue closed before due leads to `asked`, and nothing starts. With the stop switch on, it asks. [Monday] re-arms to next Monday 09:00.
+- **Deferral:** unchanged recheck, then heads-up, then silence, then `started` at due. A linked issue closed before due leads to `asked`, and nothing starts. With the stop switch on, it asks. [Monday] re-arms to next Monday 09:00. A `due` fire consumed two hours late asks; a queued fire for a disarmed or moved deferral is dropped.
- **Dream:** a dream touching `rules.md` fails, and `main` is unchanged. A dream with one journal fold and one `decisions/` change opens two PRs, and only the auto one merges.
- **Secret scan:** a journal line holding `ghp_` plus 36 characters blocks the entire commit, and the owner gets one typed notification without the value.
- **Purge:** on a fixture repo, the file is gone from `git log --all -p`, a tombstone exists, and an audit row exists.
diff --git a/packages/contracts/src/kinLead.ts b/packages/contracts/src/kinLead.ts
index 3596dc22ab969..c3594ec11f9d0 100644
--- a/packages/contracts/src/kinLead.ts
+++ b/packages/contracts/src/kinLead.ts
@@ -142,6 +142,15 @@ export const WorkerReport = Schema.Struct({
});
export type WorkerReport = typeof WorkerReport.Type;
+export const KinDeferralCard = Schema.Struct({
+ itemId: KinMemoryItemId,
+ title: Schema.String,
+ dueAt: Schema.toEncoded(CanonicalUtcTimestamp),
+ onDue: Schema.Literals(["remind", "start", "ask", "chase"]),
+ text: Schema.String,
+});
+export type KinDeferralCard = typeof KinDeferralCard.Type;
+
const EventBase = {
orgId: KinOrgId,
eventId: KinEventId,